Colleague 7 API

Colleague API Developer Guide

Authentication, conventions and every published operation.
← Back to Help Centre
 

 

A guide for web developers preparing an integration with Colleague 7, the recruitment CRM. It covers authentication, conventions and reference codes, common integration patterns, and every published operation.

75
endpoints
81
operations (incl. dual-verb searches)
17
functional areas
REST / JSON
via Azure API Management

 

The API is a REST/JSON service fronted by Microsoft Azure API Management. Each subscription is tied to one Colleague client database, and every request runs in the context of a named Colleague user. It is organised around Colleague's core records:

 Record What it is Create Read Update Search
 Candidate A job seeker, with CV documents, experience, skills and notes Yes Yes Yes Simple + Advanced
 Company A client organisation Yes Yes Yes Simple + Advanced
 Contact A person at a Company (hiring manager etc.) Yes Yes Yes Simple + Advanced
 Lead A sales lead / business opportunity, optionally linked to a Company and Contact Yes Yes Yes Simple + Advanced
 Requirement A job / vacancy Yes Yes Yes (plus attach candidates) Simple + Advanced
 Placement A placement or offer - Yes Yes Simple + Advanced

 

Supporting areas: Checklists (compliance and onboarding), Documents and social links, Notes, History (activity), Lists, Ownership, and reference data (Lookups, Skills, Fields, Users, Teams).

Leads and Requirements can be created and updated through the API. Placements can be read and updated but not created, so Placements still start in Colleague. There are no delete operations for core records. The only deletes are for lists, list entries, social media links, and items and documents on checklists (Placement checklist items via Checklist/DeleteItems).
Authentication
 

Base URL: https://coll7openapi.azure-api.net. All paths begin with /api/.

Authentication uses an Azure APIM subscription key. Send it in a header (recommended):

Ocp-Apim-Subscription-Key: <your-subscription-key>

Alternatively, the key can go in the query string as ?subscription-key=…. Avoid this, because query strings tend to end up in logs. A missing or unrecognised key returns 401.

User context. Almost every operation also needs a Colleague UserId, either as a query parameter or as userId in the JSON body. Colleague uses it for permissions and audit fields (created by / amended by). Insert and update bodies accept createdBy / amendedBy to attribute a change to a different user, for example the consultant who triggered it.

The subscription key gives access to a client's whole database. Keep it server-side only. Never ship it to a browser or mobile app, and route front-end features such as job boards and application forms through your own backend.
Conventions
 
HTTP verbs
The API uses its own verb mapping:
GET simple reads and searches
PUT create (/Insert, InsertList…) and a few reads that need a body (Notes/Get, Skill/GetEntitySkills)
PATCH update (/Update)
POST Advanced Search (PATCH also accepted), uploads, and some updates
DELETE list entries and social links only
Request bodies
The spec declares bodies as application/json-patch+json, but they are ordinary JSON objects, not RFC 6902 patch arrays. application/json, text/json and application/*+json are also accepted. Uploads (UploadDocument, SubmitApplication, Checklist/AttachDocument) use multipart/form-data, with metadata in the query string.
Partial updates
Update calls take a list of PatchDto pairs, so you only send what changed:
"candidateUpdates": [
  {"fieldName": "mobileNumber", "fieldValue": "07700 900456"}
]
Custom fields go in a separate customFieldUpdates list. Field names follow the API Field Directory.
Lookup codes
Drop-down fields (title, gender, status, type, source, nationality, country, currency, document type…) store a lookup code, not display text. Discover codes with Lookup/Get (pass a parent such as REQSTATUS) or Lookup/GetCandidateLookups. Skills come from Skill/GetAll. The Lead, Requirement, Placement and Checklist calls accept either the lookup description or the code (e.g. LEADSTATUS, LEADSOURCE, REQSTATUS, CURRENCY, CHECKLISTSTATUS).
Searching
Simple Search (GET …/Search) supports prefix match on names and contains match on email and phone, and returns IDs only for Candidates, Companies and Contacts.
Advanced Search (POST …/AdvancedSearch) takes parameters (fieldName/fieldValue) and the columns to return. Get valid field names from Field/GetSearchableFields.
IDs, dates and archived records
Record IDs are 64-bit integers. Use a 64-bit or string type in JavaScript if IDs could exceed 253. Dates are ISO-8601 date-times. The Insert Candidate docs give dd MMM yyyy for DOB and availability, so test which format your tenant accepts. Checklist dates (completionDate, sentDate, expiryDate) are plain dates such as 2026-11-12. Archived records (and Contact leavers) are excluded unless you set IncludeArchivedRecords / IncludeLeavers.
Reference codes
 
Entity type (EntityType)
0 Candidate
1 Company
2 Contact
3 Requirement
4 Placement / Offer
9 Interview (Lists only)
25 Lead (Notes, Checklists)
Field/GetSearchableFields and GetPublicCustomFields take the entity name as text instead. The Checklist calls accept either the number or the name.
Requirement / Placement type
-100 Any
0 Contract
1 Permanent
2 Rolling Contract
3 Fixed Term Contract
Charge unit (chargeUnit)
0 Hour
1 Day
2 Week
3 Month
What Requirement rates are per (Requirement/Insert).
Experience job type
0 Contract
1 Permanent
2 Rolling Contract
3 Unknown
4 Education
Social media type
-1 Specified by lookup (SocialMediaLookupType)
0 Facebook
1 LinkedIn
2 Twitter / X
Notes
noteSequence: 0 = Note 1, 100 = Note 2, 200 = Note 3, and so on.
noteTab (on Insert): tab index 0-4.
Flags
DefaultDocument: 0 = no, 1 = set as default CV.
ListId = -1: the user's Favourites list.
ColleagueReturnValue.status: 0-3. Check succeeded.
Errors
 
Status Meaning Body
200 Success. Inserts return the new record Id as a bare number; some actions return an empty body or a status string. varies
400 Invalid input: missing required field, unknown Id, bad lookup code, mandatory field missing, duplicate list entry, etc. Plain-text message
401 Subscription key missing or not recognised -
404 Record not found (some Get / Search / Lookup calls) -
409 Conflict (declared on most entity operations) object
500 Server-side error Plain-text message

 

Error bodies are plain strings, not structured problem objects, so log the full text. Mandatory-field rules are set per client in Colleague, so an insert that works on the demo database can fail on a live one. Read the 400 message and map missing fields. bypassMandatoryCheck only works when the client has enabled the Allow Mandatory Bypass API global setting.

Rate limits and quotas are not published in the API definition. Confirm them with Colleague Support before planning bulk syncs.

Integration patterns
 
1. Job board / careers site
  1. POST /api/Requirement/AdvancedSearch with includeApplyLink: true and filters (status, type), or GET /api/Requirement/Search.
  2. Cache results server-side and refresh on a schedule. For a job detail page, GET /api/Requirement/Get; with a public key it returns only publicly posted jobs and their public fields.
  3. Applications: POST /api/Requirement/SubmitApplication (multipart, CV attached). Colleague queues it to the client's application inbox.
SubmitApplication is asynchronous and returns no Candidate Id. If you need the Id, use the Candidate pattern below.
2. Candidate capture with de-duplication
  1. GET /api/Candidate/Search?EmailAddress=…
  2. No match: PUT /api/Candidate/Insert, which returns the new Id.
    Match: PATCH /api/Candidate/Update with only the changed fields.
  3. POST /api/Candidate/UploadDocument with DefaultDocument=1 for the CV.
  4. Optionally POST /api/Requirement/InsertRequirementCandidate to attach to a job, and PUT /api/History/AddToEntities to log the activity.
3. Client / contact sync (e.g. from another CRM)
  1. GET /api/Company/Search?CompanyName=…, then PUT /api/Company/Insert if not found.
  2. GET /api/Contact/Search?EmailAddress=…, then PUT /api/Contact/Insert with companyId.
  3. Set the owner with PUT /api/Ownership/AddUserOwner.
  4. Store Colleague IDs on your side. There is no external-reference field in the request schemas; a custom field can be used for this if the client sets one up.
4. Activity logging (telephony, email, calendar)
  1. Resolve the person: Candidate/Contact Search by phone or email.
  2. PUT /api/History/AddToEntities with every participant (e.g. Candidate + Contact + Company) in one call.
  3. Read the timeline back with GET /api/History/GetForEntity.
5. Reporting / data extract
  1. GET /api/Field/GetSearchableFields for each entity type to discover columns.
  2. POST …/AdvancedSearch with an explicit columns list. Avoid allColumns: true, which returns large payloads.
  3. Resolve codes to labels with Lookups, and users with User/Get and Teams/GetByUser.
The spec defines no pagination parameters for search, so test result sizes on realistic data.
6. Bootstrap reference data (do this first)
  1. GET /api/Lookup/GetCandidateLookups and GET /api/Lookup/Get (top level, then children)
  2. GET /api/Skill/GetAll
  3. GET /api/Field/GetPublicCustomFields per entity
  4. GET /api/User/Get?ActiveOnly=true
Each client configures Colleague differently, so build mappings per client rather than hard-coding codes.
7. Lead to job (business development)
  1. Capture the opportunity with PUT /api/Lead/Insert, linked to an existing Company / Contact or with typed names.
  2. Track progress with PATCH /api/Lead/Update (status, value, expected date). A closing status sets the Date Closed.
  3. When it becomes a vacancy, PUT /api/Requirement/Insert with leadId; the Lead's title, address and currency fill any gaps.
  4. Keep the job up to date with PATCH /api/Requirement/Update, and attach Candidates with InsertRequirementCandidate.
A Requirement can only be created if the Company's checklist allows it, so check Company checklists first.
8. Compliance / onboarding checklists
  1. GET /api/Checklist/GetTemplates per entity type to map item names to checklistTemplateId.
  2. GET /api/Checklist/Get?IncompleteOnly=true to see what is outstanding on a Candidate or Placement.
  3. Upload evidence with POST /api/Checklist/AttachDocument (needed first for items with requiresDocument).
  4. Complete the item with PATCH /api/Checklist/UpdateItem, setting expiryDate where relevant.
  5. For Placements, add or remove non-default items with Checklist/AddItems / DeleteItems.
Check canComplete first: only user groups allowed to complete an item can do so, and that applies to the API user too.
Gotchas and spec caveats
 

 

  • Advanced Search accepts both POST and PATCH with identical contracts. Use POST.
  • Some reads use PUT (Notes/Get, Skill/GetEntitySkills) and some updates use POST (History/Update, Document/UpdateSocialMediaLink). Check that proxies or WAFs on your side allow these.
  • Legacy field aliases on Insert Candidate: address1/addressLine1, town/city, emailAddress1/emailAddress, website/webAddress, salutation/knownAs, jobType/jobCode. Use the modern names.
  • int32 vs int64 IDs: Candidate/Get, Candidate/GetDocuments, Company/Get, Contact/Get and Requirement/SubmitApplication declare their Id parameter as int32. Elsewhere IDs are int64.
  • Untyped responses: Company/Get, Contact/Get, Lead/Get, Requirement/Get, Placement/Get, Lead, Requirement and Placement searches, Lists, History and Users are typed only as object in the spec. Capture real responses from the demo environment to build your models.
  • Advanced Search results reuse Colleague's full internal entity model, which has 150+ properties, many of them UI-only. Only the columns you request are populated.
  • Candidate Login sends username and password as query parameters. Only call it server-to-server over TLS, and keep these URLs out of your logs.
  • Copy-paste descriptions in the published spec: the Placement Search parameters describe "Requirements", the Lookup responses say "All skills", and DeleteList.ListId is described as a user. This guide restates them correctly.
  • Field names in the new Update calls: the published examples for Lead/Update, Requirement/Update and Placement/Update use display-style names (Lead Title, Job Title, Pay Rate), and custom fields are matched by label. Confirm names with Field/GetSearchableFields and test on the demo database.
  • Checklist deletes use POST (Checklist/DeleteItems, Checklist/RemoveDocument), not DELETE, and DeleteItems is all-or-nothing.
  • Checklist items before they are saved have no checklistItemId. Use checklistTemplateId as the stable key.
  • Field-name casing: query parameters are PascalCase (UserId). The Lookup and Skill calls use camelCase (userId), and JSON bodies are camelCase.
Endpoint reference
 

 

Each operation below lists its parameters, responses and a cURL example. Every operation can also return 400, 401 and 500. Placeholders like {UserId} must be URL-encoded. Lookup codes, user IDs and record IDs in the examples are illustrative only; use the values from your client's database.

Candidate

Create, read, update and search Candidates, plus their CV/documents and work experience.

POST PATCH /api/Candidate/AdvancedSearchAdvanced search for Candidates; returns the selected columns
Also available as PATCH with an identical contract. Valid fieldName values come from /api/Field/GetSearchableFields?EntityType=Candidate.
REQUEST BODY

JSON object: AdvanceSearchCandidateRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Candidates (only the requested columns populated) array<Candidate>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Candidate/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "allColumns": false,
    "columns": [
      "candidateId",
      "forenames",
      "surname",
      "emailAddress",
      "candidateStatus"
    ],
    "includeArchived": false,
    "parameters": [
      {
        "fieldName": "<field from GetSearchableFields>",
        "fieldValue": "Manchester"
      }
    ]
  }'
GET /api/Candidate/GetGet an existing Candidate record
CandidateId is declared as int32 here although IDs elsewhere are int64.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CandidateId int32 yes The Candidate Id
IncludeArchivedRecords boolean   Also include archived records
RESPONSES
Code Meaning Body
200 The Candidate record GetCandidateResponse
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Candidate/Get?UserId={UserId}&CandidateId={CandidateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Candidate/InsertCreate a Candidate record
Lookup-backed fields (title, gender, candidateStatus, candidateType, candidateSource, nationality, country, currencyCode) take lookup codes, not display text.
REQUEST BODY

JSON object: InsertCandidateRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the newly created Candidate int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Candidate/Insert" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "forenames": "Sarah",
    "surname": "Jones",
    "emailAddress": "sarah.jones@example.com",
    "mobileNumber": "07700 900123",
    "candidateStatus": "AVAIL",
    "candidateSource": "WEB",
    "resourcerJobTitle": "Senior Accountant",
    "postcode": "M1 1AA",
    "customFields": [
      {
        "customFieldName": "Right to Work Checked",
        "customFieldValue": true
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "ACCA",
        "lookupParent": "QUALS"
      }
    ]
  }'
PATCH /api/Candidate/UpdateUpdate an existing Candidate record
Supply only the fields to change as {fieldName, fieldValue} pairs in candidateUpdates / customFieldUpdates.
REQUEST BODY

JSON object: UpdateCandidateRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Candidate Id int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Candidate/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "candidateId": 104233,
    "candidateUpdates": [
      {
        "fieldName": "mobileNumber",
        "fieldValue": "07700 900456"
      },
      {
        "fieldName": "candidateStatus",
        "fieldValue": "PLACED"
      }
    ],
    "customFieldUpdates": [
      {
        "fieldName": "Right to Work Checked",
        "fieldValue": true
      }
    ]
  }'
POST /api/Candidate/UploadDocumentUpload a Document to a Candidate record
Metadata goes in the query string; the file is sent as a multipart/form-data part.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
OwnerId int64 yes The Candidate Id the document is uploaded to
DefaultDocument int32 yes 0 = do not set as default document, 1 = set as default
Description string yes Document description
DocumentType string   Document Type lookup code
DocumentText string   Text used for document preview; leave null to extract from the file
REQUEST BODY

multipart/form-data (file)

RESPONSES
Code Meaning Body
200 The Id of the newly uploaded Document int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Candidate/UploadDocument?UserId={UserId}&OwnerId={OwnerId}&DefaultDocument={DefaultDocument}&Description={Description}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -F "file=@./cv.pdf"
GET /api/Candidate/GetDocumentsGet all documents associated with a Candidate record
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CandidateId int32 yes The Candidate Id
IncludeUrls boolean   Also include documents that are just URLs
IncludeUntyped boolean   Also include documents with no assigned type (default false)
RESPONSES
Code Meaning Body
200 The Candidate's documents, each with a downloadLink GetCandidateDocumentsResponse
404 Record not found / invalid Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Candidate/GetDocuments?UserId={UserId}&CandidateId={CandidateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Candidate/GetExperienceGet all Experiences (work history) related to a Candidate
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CandidateId int64 yes Candidate Id
RESPONSES
Code Meaning Body
200 Experience records array<Situation>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Candidate/GetExperience?UserId={UserId}&CandidateId={CandidateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Candidate/InsertExperienceCreate a Candidate Experience record
REQUEST BODY

JSON object: InsertCandidateExperienceRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the new Experience record int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Candidate/InsertExperience" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "candidateId": 0,
    "jobType": 0,
    "jobTitle": "string",
    "companyName": "string",
    "contactName": "string",
    "location": "string",
    "workingCompanyId": 0,
    "owningCompany": "string",
    "startDate": "2026-01-31T09:00:00",
    "endDate": "2026-01-31T09:00:00",
    "chargeRate": 0,
    "otChargeRate": 0,
    "payRate": 0,
    "otPayRate": 0,
    "noticePeriod": 0,
    "notes": "string",
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ]
  }'
PATCH /api/Candidate/UpdateExperienceUpdate an existing Candidate Experience record
REQUEST BODY

JSON object: UpdateCandidateExperienceRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Experience Id int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Candidate/UpdateExperience" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "situationId": 0,
    "experienceUpdates": [
      {
        "fieldName": "string",
        "fieldValue": "value"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ]
  }'
GET /api/Candidate/LoginValidate a Candidate portal login
Security: credentials are passed in the query string. Call this only server-side and make sure URLs are not written to logs.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
Username string yes Candidate username (8-255 characters)
Password string yes Candidate password (8-255 characters)
RESPONSES
Code Meaning Body
200 Result of the login attempt ColleagueReturnValue
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Candidate/Login?UserId={UserId}&Username={Username}&Password={Password}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Company

Client companies.

POST PATCH /api/Company/AdvancedSearchAdvanced search for Companies; returns the selected columns
Also available as PATCH.
REQUEST BODY

JSON object: AdvanceSearchCompanyRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Companies array<Company>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Company/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "allColumns": false,
    "columns": [
      "string"
    ],
    "includeArchived": false,
    "parameters": [
      {
        "fieldName": "string",
        "fieldValue": "string"
      }
    ]
  }'
GET /api/Company/GetGet an existing Company record
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CompanyId int32 yes The Company Id
IncludeArchivedRecords boolean   Also include archived records
RESPONSES
Code Meaning Body
200 The Company record (untyped object in the spec) object
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Company/Get?UserId={UserId}&CompanyId={CompanyId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Company/InsertCreate a Company record
REQUEST BODY

JSON object: InsertCompanyRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the newly created Company int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Company/Insert" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "companyName": "string",
    "parentCompany": 0,
    "industry": "string",
    "companyType": "string",
    "website": "string",
    "companyEmail": "string",
    "telephone": "string",
    "fax": "string",
    "employeeCount": "string",
    "registrationNumber": "string",
    "vatNumber": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressLine3": "string",
    "city": "string",
    "county": "string",
    "postcode": "string",
    "country": "string",
    "addressType": 0,
    "customFields": [
      {
        "customFieldName": "string",
        "customFieldValue": "value"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ],
    "noteTab": 0,
    "notes": "string",
    "createdBy": "string",
    "bypassMandatoryCheck": false
  }'
PATCH /api/Company/UpdateUpdate an existing Company record
REQUEST BODY

JSON object: UpdateCompanyRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Company Id int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Company/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "companyId": 0,
    "companyUpdates": [
      {
        "fieldName": "string",
        "fieldValue": "value"
      }
    ],
    "customFieldUpdates": [
      {
        "fieldName": "string",
        "fieldValue": "value"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ],
    "addSkillsToContacts": false,
    "amendedBy": "string"
  }'
Contact

People at client companies. Every Contact belongs to a Company.

POST PATCH /api/Contact/AdvancedSearchAdvanced search for Contacts; returns the selected columns
Also available as PATCH.
REQUEST BODY

JSON object: AdvanceSearchContactRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Contacts array<Contact>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Contact/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "allColumns": false,
    "columns": [
      "string"
    ],
    "includeArchived": false,
    "parameters": [
      {
        "fieldName": "string",
        "fieldValue": "string"
      }
    ]
  }'
GET /api/Contact/GetGet an existing Contact record
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
ContactId int32 yes The Contact Id
IncludeArchivedRecords boolean   Also include archived records
IncludeLeavers boolean   Also include leavers
RESPONSES
Code Meaning Body
200 The Contact record (untyped object in the spec) object
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Contact/Get?UserId={UserId}&ContactId={ContactId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Contact/InsertCreate a Contact record
A Contact must belong to a Company (companyId is required).
REQUEST BODY

JSON object: InsertContactRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the newly created Contact int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Contact/Insert" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "companyId": 0,
    "addressId": 0,
    "forenames": "string",
    "surname": "string",
    "knownAs": "string",
    "title": "string",
    "jobTitle": "string",
    "department": "string",
    "directNumber": "string",
    "directFax": "string",
    "otherNumber": "string",
    "emailAddress1": "string",
    "emailAddress2": "string",
    "companyWebsite": "string",
    "reportsTo": 0,
    "assistant": 0,
    "startDate": "2026-01-31T09:00:00",
    "endDate": "2026-01-31T09:00:00",
    "contactType": "string",
    "customFields": [
      {
        "customFieldName": "string",
        "customFieldValue": "value"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ],
    "noteTab": 0,
    "notes": "string",
    "copySkillsToCompany": false,
    "copySkillsToOtherContacts": false,
    "copySkillsFromCompany": false,
    "createdBy": "string",
    "bypassMandatoryCheck": false
  }'
PATCH /api/Contact/UpdateUpdate an existing Contact record
REQUEST BODY

JSON object: UpdateContactRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Contact Id int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Contact/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "contactId": 0,
    "contactUpdates": [
      {
        "fieldName": "string",
        "fieldValue": "value"
      }
    ],
    "customFieldUpdates": [
      {
        "fieldName": "string",
        "fieldValue": "value"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "string",
        "lookupParent": "string",
        "lookupPath": "string",
        "skillGrade": "string"
      }
    ],
    "addSkillsToCompany": false,
    "addSkillsToContacts": false,
    "amendedBy": "string"
  }'
Lead

Sales leads (business development opportunities): create, read, update and search. A Lead can be linked to a Company and Contact, and Requirements can be created from it.

POST PATCH /api/Lead/AdvancedSearchAdvanced search for Leads; returns the selected columns
Also available as PATCH with an identical contract. Valid fieldName values come from /api/Field/GetSearchableFields?EntityType=Lead.
REQUEST BODY

JSON object: AdvanceSearchLeadRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Leads (only the requested columns populated) array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Lead/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "allColumns": false,
    "columns": [
      "leadId",
      "leadTitle",
      "companyName",
      "status",
      "potentialValue"
    ],
    "parameters": [
      {
        "fieldName": "<field from GetSearchableFields>",
        "fieldValue": "Open"
      }
    ]
  }'
GET /api/Lead/GetGet an existing Lead record
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
LeadId int64 yes The Lead Id
IncludeArchivedRecords boolean   Also include archived records
RESPONSES
Code Meaning Body
200 The Lead record object
404 No Lead exists with the supplied Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Lead/Get?UserId={UserId}&LeadId={LeadId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Lead/InsertCreate a Lead record
The same rules apply as on the Lead screen. The Company and Contact are optional. A Contact also links its Company, and must be at that Company if both are given. Linked records supply their names; for records not in Colleague, type the names in companyName / contactName. addressId must be one of the Company's addresses, and the client's mandatory Lead fields must be filled. Lookup fields (leadSource, status, currency) accept the description or the code.
REQUEST BODY

JSON object: InsertLeadRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the newly created Lead int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Lead/Insert" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "leadTitle": "New office fit-out",
    "leadSource": "Referral",
    "status": "Open",
    "companyId": 20481,
    "contactId": 55012,
    "currency": "GBP",
    "potentialValue": 15000,
    "expectedDate": "2027-01-31T00:00:00",
    "noteTab": 0,
    "notes": "Met at the regional trade show"
  }'
PATCH /api/Lead/UpdateUpdate an existing Lead record
Supply only the fields to change as {fieldName, fieldValue} pairs in leadUpdates / customFieldUpdates; a blank value clears the field. Company Id and Contact Id link the Lead to existing records (0 unlinks). A Contact must be at the Lead's Company, and unlinking the Company also unlinks the Contact. A status change sets or clears the Date Closed. Mandatory fields cannot be cleared, and archived Leads cannot be changed.
REQUEST BODY

JSON object: UpdateLeadRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The update result string
404 No Lead exists with the supplied Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Lead/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "leadId": 9120,
    "leadUpdates": [
      {
        "fieldName": "Lead Title",
        "fieldValue": "New office fit-out (phase 2)"
      },
      {
        "fieldName": "Potential Value",
        "fieldValue": 22000
      }
    ]
  }'
Requirement

Create, read, update and search jobs / vacancies, plus the Candidates attached to them and inbound applications.

POST PATCH /api/Requirement/AdvancedSearchAdvanced search for Requirements; returns the selected columns
Also available as PATCH. includeApplyLink adds an application link, useful for job boards.
REQUEST BODY

JSON object: AdvanceSearchRequirementRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Requirements array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Requirement/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "includeApplyLink": false,
    "allColumns": false,
    "columns": [
      "string"
    ],
    "splitJobTitle": false,
    "parameters": [
      {
        "fieldName": "string",
        "fieldValue": "string"
      }
    ]
  }'
GET /api/Requirement/GetGet an existing Requirement record
With a public subscription key, only publicly posted Requirements can be retrieved, only their public fields are returned (including custom fields exposed to public), and IncludeArchivedRecords is ignored. Other Requirements return 404.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
RequirementId int64 yes The Requirement Id
IncludeArchivedRecords boolean   Also include archived records (ignored with a public key)
RESPONSES
Code Meaning Body
200 The Requirement record object
404 No Requirement exists with the supplied Id (or it is not publicly posted, with a public key)  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Requirement/Get?UserId={UserId}&RequirementId={RequirementId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Requirement/InsertCreate a Requirement (job) record
The same rules apply as on the Requirement screen. The Contact must be at the Company, and addressId must be one of the Company's addresses. Rates (expChargeRate, expPayRate, IR35 Status…) apply to Contract and Rolling Contract requirements only; salaries (expMinSalary / expMaxSalary) apply to Permanent and Fixed Term Contract only. The client's mandatory fields for the requirement type must be filled, and the Company's checklist must allow a new Requirement. Pass leadId to create the job from a Lead, as Create Requirement on the Lead screen does.
REQUEST BODY

JSON object: InsertRequirementRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The Id of the newly created Requirement int64
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Requirement/Insert" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "contactId": 55012,
    "jobTitle": "Senior Accountant",
    "requirementType": 1,
    "status": "OPEN",
    "currency": "GBP",
    "startDate": "2027-01-04T00:00:00",
    "numberOfPlaces": 1,
    "expMinSalary": 45000,
    "expMaxSalary": 55000,
    "additionalFields": [
      {
        "fieldName": "Hours Per Week",
        "fieldValue": 37.5
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "ACCA",
        "lookupParent": "QUALS"
      }
    ],
    "noteTab": 0,
    "notes": "Hybrid, 3 days in the Manchester office"
  }'
PATCH /api/Requirement/UpdateUpdate an existing Requirement record
Supply only the fields to change as {fieldName, fieldValue} pairs in requirementUpdates / customFieldUpdates; a blank value clears the field. Contact Id (a Contact at the Requirement's Company), Address Id (one of the Company's addresses) and Lead Id (one of the Company's Leads, 0 to unlink) can be changed; the Company cannot. Rate and salary rules are the same as on Insert, and mandatory fields cannot be cleared.
REQUEST BODY

JSON object: UpdateRequirementRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The update result string
404 No Requirement exists with the supplied Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Requirement/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "requirementId": 30117,
    "requirementUpdates": [
      {
        "fieldName": "Job Title",
        "fieldValue": "Senior Developer"
      }
    ],
    "skillsToAdd": [
      {
        "lookupCode": "CSHARP",
        "lookupParent": "SKILLS"
      }
    ]
  }'
GET /api/Requirement/GetRequirementCandidatesList the Candidates attached to a Requirement
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
RequirementId int64 yes The Requirement Id
RESPONSES
Code Meaning Body
200 Associated Candidates array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Requirement/GetRequirementCandidates?UserId={UserId}&RequirementId={RequirementId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
POST /api/Requirement/InsertRequirementCandidateAdd a Candidate to a Requirement (shortlist / send)
Returns 400 if the Candidate is already listed against the Requirement.
REQUEST BODY

JSON object: RequirementCandidateRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Candidate added to Requirement (empty)
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Requirement/InsertRequirementCandidate" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "requirementId": 30117,
    "candidateId": 104233,
    "shortlistImmediately": true,
    "generateNotifications": false,
    "notes": "Strong match"
  }'
POST /api/Requirement/SubmitApplicationSubmit a job application to a Requirement
The application is emailed to the address set in the application email Global Setting and processed asynchronously; it does not return a Candidate Id.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
RequirementId int32 yes The Requirement to apply to
Forename string yes Candidate forename
Surname string yes Candidate surname
EmailAddress string yes Candidate email address
TelephoneNumber string    
Message string   Covering message
isValid boolean   (undocumented)
REQUEST BODY

multipart/form-data (CV file)

RESPONSES
Code Meaning Body
200 Application queued for processing string
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Requirement/SubmitApplication?UserId={UserId}&RequirementId={RequirementId}&Forename={Forename}&Surname={Surname}&EmailAddress={EmailAddress}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -F "file=@./cv.pdf"
Placement

Read, update and search Placements and offers.

POST PATCH /api/Placement/AdvancedSearchAdvanced search for Placements; returns the selected columns
Also available as PATCH.
REQUEST BODY

JSON object: AdvanceSearchPlacementRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Matching Placements array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Placement/AdvancedSearch" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "allColumns": false,
    "columns": [
      "string"
    ],
    "splitJobTitle": false,
    "parameters": [
      {
        "fieldName": "string",
        "fieldValue": "string"
      }
    ]
  }'
GET /api/Placement/GetGet an existing Placement record
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
PlacementId int64 yes The Placement Id
IncludeArchivedRecords boolean   Also include archived records
RESPONSES
Code Meaning Body
200 The Placement record object
404 No Placement exists with the supplied Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Placement/Get?UserId={UserId}&PlacementId={PlacementId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PATCH /api/Placement/UpdateUpdate an existing Placement (or Offer) record
Supply only the fields to change as {fieldName, fieldValue} pairs in placementUpdates / customFieldUpdates; a blank value clears the field. Fields locked on the Placement screen stay locked: the Candidate, Requirement, Company and Placement Type always, the Job Type once an Offer is accepted, most details once the Placement is authorised, and the fee once invoiced. The Margin is recalculated.
REQUEST BODY

JSON object: UpdatePlacementRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The update result string
404 No Placement exists with the supplied Id  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Placement/Update" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "placementId": 7781,
    "placementUpdates": [
      {
        "fieldName": "Pay Rate",
        "fieldValue": 250
      }
    ],
    "customFieldUpdates": [
      {
        "fieldName": "PO Number",
        "fieldValue": "PO-88213"
      }
    ]
  }'
Checklist

Compliance and onboarding checklists (the Checklist tab) on Candidates, Companies, Contacts, Requirements, Placements and Leads: read items, complete and update them, attach documents, and add or remove items on Placements. Checklists are set up in Admin, Checklist Maintenance.

GET /api/Checklist/GetTemplatesGet the checklist items set up for an entity type
Returns the items configured in Admin, Checklist Maintenance. defaultSet items are on every record's checklist; Placements start with the default set only, and other Placement items can be added with AddItems.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType string yes 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead (or the entity name)
RESPONSES
Code Meaning Body
200 The checklist template items array<ChecklistTemplateResponse>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Checklist/GetTemplates?UserId={UserId}&EntityType={EntityType}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Checklist/GetGet a record's checklist
Lists the record's checklist as its Checklist tab does: items saved on the record plus items not yet worked on (for a Candidate, those for its Candidate Type; for a Placement, its default set and any added items). Items not yet worked on have no checklistItemId, so identify items by checklistTemplateId. A record with no checklist returns an empty list.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType string yes The record's entity type: 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead (or the entity name)
EntityId int64 yes The record's Id
IncompleteOnly boolean   Only return items that are not complete
Status string   Only return items with this Checklist Status (CHECKLISTSTATUS description or code), or NoStatus for items without one
RESPONSES
Code Meaning Body
200 The record's checklist items array<ChecklistItemResponse>
404 The record does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Checklist/Get?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PATCH /api/Checklist/UpdateItemUpdate one item on a record's checklist
Mark an item complete (on completionDate, or today) or not complete, or change its completed date, status, notes, sent date or expiry date. Only the values given are changed. The Checklist tab's rules apply: only user groups allowed to complete the item can complete it (see canComplete on Checklist/Get), an item that requires a document needs one attached first, and completing an item without a status sets its completed status. If any value is invalid, nothing is saved and the 400 message gives the reasons.
REQUEST BODY

JSON object: UpdateChecklistItemRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The checklist item's Id int64
404 The record or checklist item does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PATCH "https://coll7openapi.azure-api.net/api/Checklist/UpdateItem" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "entityType": "Candidate",
    "entityId": 104233,
    "checklistTemplateId": 12,
    "isComplete": true,
    "completionDate": "2026-11-12",
    "notes": "Passport seen in person",
    "expiryDate": "2031-03-01"
  }'
POST /api/Checklist/AddItemsAdd checklist items to a Placement
Placements only (entityType 4), as Add Checklist Item on the Placement does. A Placement's checklist starts with the default set; add any other Placement item from Checklist/GetTemplates, then update it with Checklist/UpdateItem.
REQUEST BODY

JSON object: AddChecklistItemsRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The items were added string
404 The record does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Checklist/AddItems" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "entityType": "4",
    "entityId": 7781,
    "checklistTemplateIds": [
      31,
      34
    ]
  }'
POST /api/Checklist/DeleteItemsDelete items from a Placement's checklist
Placements only, as Delete Checklist Item on the Placement does. Items in the default set, and items already worked on (completed, notes, sent / expiry date or a document), cannot be deleted. If any requested item cannot be deleted, none are, and the 400 message gives the reasons.
REQUEST BODY

JSON object: DeleteChecklistItemsRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The items were deleted string
404 The record does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Checklist/DeleteItems" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "entityType": "4",
    "entityId": 7781,
    "checklistTemplateIds": [
      34
    ]
  }'
POST /api/Checklist/AttachDocumentAttach a document to a checklist item
Works like the Checklist tab's upload. The file is stored as a checklist document of the record; a document already on the item moves to the record's own documents. Items that require a document can then be completed. Identify the item by ChecklistTemplateId or ChecklistItemId.
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType string yes The record's entity type: 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead (or the entity name)
EntityId int64 yes The record's Id
ChecklistTemplateId int64   The item, by its ChecklistTemplateId. Either this or ChecklistItemId.
ChecklistItemId int64   The item, by its ChecklistItemId. Either this or ChecklistTemplateId.
REQUEST BODY

multipart/form-data (FileInfo: the file)

RESPONSES
Code Meaning Body
200 The new document's Id int64
404 The record or checklist item does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Checklist/AttachDocument?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}&ChecklistTemplateId={ChecklistTemplateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -F "FileInfo=@./passport.pdf"
POST /api/Checklist/RemoveDocumentRemove a checklist item's document
Needs the Delete Documents permission (and View Secure Document Types for a secure document type). The document is deleted, unless it is in use elsewhere, in which case it is only removed from the item.
REQUEST BODY

JSON object: ChecklistItemRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The document was removed string
404 The record or checklist item does not exist  
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Checklist/RemoveDocument" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "entityType": "Candidate",
    "entityId": 104233,
    "checklistTemplateId": 12
  }'
Document

File downloads and social media links (stored as documents on Candidates, Companies and Contacts).

GET /api/Document/DownloadDownload a specific Document
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
DocumentId int64 yes The Document Id
RESPONSES
Code Meaning Body
200 The file FileContentResult
404 Record not found / invalid Id  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Document/Download?UserId={UserId}&DocumentId={DocumentId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Document/DownloadLatestCandidateDocumentDownload the latest Document for a Candidate
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CandidateId int64 yes The Candidate Id
RESPONSES
Code Meaning Body
200 The latest document file
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Document/DownloadLatestCandidateDocument?UserId={UserId}&CandidateId={CandidateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Document/GetLatestCandidateDocumentInfoGet metadata for a Candidate's latest Document
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
CandidateId int64 yes The Candidate Id
RESPONSES
Code Meaning Body
200 Info for the latest document object
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Document/GetLatestCandidateDocumentInfo?UserId={UserId}&CandidateId={CandidateId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
POST /api/Document/UpdateSocialMediaLinkUpdate a social media link
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 Candidate, 1 Company, 2 Contact
EntityId int64 yes The entity Id
DocumentId int64   Specific link to update; if omitted the latest link of the matching type is updated
SocialMediaType int32   -1 by lookup, 0 Facebook, 1 LinkedIn, 2 Twitter
SocialMediaLookupType string   Lookup type when SocialMediaType = -1
SocialMediaUrl string   New URL
Description string   New description
RESPONSES
Code Meaning Body
200 Link updated (empty)
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/Document/UpdateSocialMediaLink?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Notes

Free-text note tabs on records.

GET /api/Notes/GetForEntityGet Notes for an entity
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead
EntityId int64 yes The entity Id
NoteSequence int32   Note sequence (0 = Note 1, 100 = Note 2 ...); omit for all notes
FetchAsHTML boolean   Return note text as HTML
RESPONSES
Code Meaning Body
200 The entity's notes array<Note>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Notes/GetForEntity?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Notes/GetGet Notes by Note Id
A read operation that uses PUT so the Id array can be sent in the body. Use when an entity's notes are not the default set.
REQUEST BODY

JSON object: GetNotesRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 The requested notes array<Note>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Notes/Get" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "noteIds": [
      0
    ],
    "noteSequence": 0,
    "fetchAsHTML": false
  }'
PUT /api/Notes/InsertUpdateNoteForEntityInsert or update a Note on an entity
REQUEST BODY

JSON object: UpdateEntityNoteRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Note inserted / updated (empty)
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Notes/InsertUpdateNoteForEntity" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "entityType": 0,
    "entityId": 104233,
    "noteSequence": 0,
    "noteContent": "Prefers hybrid working."
  }'
History

The activity timeline (calls, emails, meetings, status changes).

GET /api/History/GetForEntityGet recent History (activity) items for an entity
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 - Candidate, 1 - Company, 2 - Contact, 3 - Requirement, 4 - Placement
EntityId int64 yes The entity Id
Top int32   Maximum number of items
HistoryTypes string   History type code filter
RESPONSES
Code Meaning Body
200 History items array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/History/GetForEntity?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/History/AddToEntitiesAdd one History item to multiple participants
Log a single activity (call, email, meeting) against a Candidate, Contact and Company at once.
REQUEST BODY

JSON object: AddHistoryRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Success message containing the new History Id string
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/History/AddToEntities" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "jsmith",
    "historyText": "Discussed Senior Accountant role",
    "historyCode": "<history code>",
    "historyDate": "2026-10-14T10:30:00",
    "participants": [
      {
        "entityType": 0,
        "entityId": 104233
      },
      {
        "entityType": 2,
        "entityId": 5521
      },
      {
        "entityType": 1,
        "entityId": 812
      }
    ]
  }'
POST /api/History/UpdateUpdate an existing History item
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
HistoryId int64 yes The History Id
HistoryCode string   History code
HistoryUserId string   Owning user
HistoryDate date-time   Date/time of the history
HistoryText string   New text
RESPONSES
Code Meaning Body
200 Result array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X POST "https://coll7openapi.azure-api.net/api/History/Update?UserId={UserId}&HistoryId={HistoryId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
List

User-owned record lists (including Favourites).

GET /api/List/GetListsGet all Lists belonging to a user
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The calling Colleague 7 User Id
ListsUser string   User whose lists to return (defaults to UserId)
RESPONSES
Code Meaning Body
200 The user's Lists array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/List/GetLists?UserId={UserId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/List/GetListContentsGet all records in a List
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The calling Colleague 7 User Id
ListId int64 yes The List Id (-1 = Favourites)
ListsUser string   List owner (only needed for Favourites)
RESPONSES
Code Meaning Body
200 Records in the List array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/List/GetListContents?UserId={UserId}&ListId={ListId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/List/InsertListCreate a List for a user
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The user creating the list
ListName string yes List name (must be unique)
ListsUser string   Owner of the list (defaults to UserId)
ListSharedWith array<int64>   Report Team / Report User Ids to share with
RESPONSES
Code Meaning Body
200 Success status string
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/List/InsertList?UserId={UserId}&ListName={ListName}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/List/InsertListRecordAdd a record to a List
QUERY PARAMETERS
Name Type Req. Description
UserId string yes Calling user; shown as 'created by'
ListId int64 yes The List
EntityType int32 yes 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement/Offer, 9 Interview
EntityId int64 yes The record Id
ListsUser string   List owner (only needed for Favourites)
Notes string   Notes on the list entry
RESPONSES
Code Meaning Body
200 Success status array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/List/InsertListRecord?UserId={UserId}&ListId={ListId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
DELETE /api/List/DeleteListDelete a user's List
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The calling Colleague 7 User Id
ListId int64 yes The List to delete
RESPONSES
Code Meaning Body
200 Success status string
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X DELETE "https://coll7openapi.azure-api.net/api/List/DeleteList?UserId={UserId}&ListId={ListId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
DELETE /api/List/DeleteListRecordRemove a record from a List
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The calling Colleague 7 User Id
ListId int64 yes The List
EntityType int32 yes 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement/Offer, 9 Interview
EntityId int64 yes The record Id
ListsUser string   List owner
RESPONSES
Code Meaning Body
200 Success status string
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X DELETE "https://coll7openapi.azure-api.net/api/List/DeleteListRecord?UserId={UserId}&ListId={ListId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Ownership

Record ownership by users and reporting teams.

GET /api/Ownership/ListList the owners of an entity
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 - Candidate, 1 - Company, 2 - Contact, 3 - Requirement, 4 - Placement
EntityId int64 yes The entity Id
RESPONSES
Code Meaning Body
200 Owners string
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Ownership/List?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Ownership/AddUserOwnerAdd a User as an owner of an entity
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 - Candidate, 1 - Company, 2 - Contact, 3 - Requirement, 4 - Placement
EntityId int64 yes The entity Id
OwningUserId string yes User Id to assign ownership to
RESPONSES
Code Meaning Body
200 Ownership added (empty)
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Ownership/AddUserOwner?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}&OwningUserId={OwningUserId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Ownership/AddReportOwnerAdd a Report User or Team as an owner of an entity
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
EntityType int32 yes 0 - Candidate, 1 - Company, 2 - Contact, 3 - Requirement, 4 - Placement
EntityId int64 yes The entity Id
OwningReportMemberId int64 yes Report User Id (user or team)
RESPONSES
Code Meaning Body
200 Ownership added (empty)
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Ownership/AddReportOwner?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}&OwningReportMemberId={OwningReportMemberId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Lookup

Reference codes behind drop-down fields.

GET /api/Lookup/GetGet lookups beneath a parent (top level if no parent)
QUERY PARAMETERS
Name Type Req. Description
userId string yes The Colleague 7 User Id
parentLookupCode string   Parent lookup code, e.g. REQSTATUS
filterAllowSelection boolean   Only selectable lookups
RESPONSES
Code Meaning Body
200 Lookups (hierarchical) GetLookupsResponse
404 Record not found / invalid Id  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Lookup/Get?userId={userId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Lookup/GetCandidateLookupsGet the lookups in use on Candidate records
QUERY PARAMETERS
Name Type Req. Description
userId string yes The Colleague 7 User Id
RESPONSES
Code Meaning Body
200 Standard and custom lookups GetCandidateLookupsResponse
404 Record not found / invalid Id  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Lookup/GetCandidateLookups?userId={userId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Skill

The skills taxonomy and skills on records.

GET /api/Skill/GetAllGet the full skills tree
QUERY PARAMETERS
Name Type Req. Description
userId string yes The Colleague 7 User Id
RESPONSES
Code Meaning Body
200 All skills GetAllSkillsResponse
404 Record not found / invalid Id  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Skill/GetAll?userId={userId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
PUT /api/Skill/GetEntitySkillsGet the skills on one or more entities
A read operation that uses PUT. Supports Candidates (0) and Requirements (3).
REQUEST BODY

JSON object: GetEntitySkillsRequest (see schema for all fields)

RESPONSES
Code Meaning Body
200 Skills array<Skill>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X PUT "https://coll7openapi.azure-api.net/api/Skill/GetEntitySkills" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "entityType": 0,
    "entityIds": [
      0
    ]
  }'
Field

Field metadata for building searches and setting custom fields.

GET /api/Field/GetSearchableFieldsGet the searchable fields for an entity type
Use the result to build parameters and columns for Advanced Search.
QUERY PARAMETERS
Name Type Req. Description
UserId string   The User Id
EntityType string   Candidate, Company, Contact, Requirement, Placement or Lead (as text)
RESPONSES
Code Meaning Body
200 Searchable fields array<object>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Field/GetSearchableFields" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
GET /api/Field/GetPublicCustomFieldsGet the public custom fields for an entity type
Use these names in customFields / customFieldUpdates.
QUERY PARAMETERS
Name Type Req. Description
UserId string   The User Id
EntityType string   Entity type name
RESPONSES
Code Meaning Body
200 Custom field definitions array<object>
409 Conflict  
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Field/GetPublicCustomFields" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
User

Colleague users.

GET /api/User/GetList users
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
LicencedOnly boolean   Licensed users only
ActiveOnly boolean   Active users only
RESPONSES
Code Meaning Body
200 Users array<object>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/User/Get?UserId={UserId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Teams

Reporting teams.

GET /api/Teams/GetByUserGet the Report Teams a user belongs to or manages
QUERY PARAMETERS
Name Type Req. Description
UserId string yes The Colleague 7 User Id
RequestUserId string yes User whose teams to return
RESPONSES
Code Meaning Body
200 Report teams array<ReportUsers>
400 / 401 / 500 Standard errors (see Errors) string
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Teams/GetByUser?UserId={UserId}&RequestUserId={RequestUserId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
Schemas
 
Request bodies
InsertCandidateRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
forenames string  
surname string  
knownAs string  
salutation string Legacy alias of knownAs
title string Title lookup code
gender string Gender lookup code
married boolean  
emailAddress string  
emailAddress1 string Legacy alias of emailAddress
emailAddress2 string  
mobileNumber string  
directNumber string  
directFax string  
otherNumber string  
telephoneNumber string  
faxNumber string  
webAddress string  
website string Legacy alias of webAddress
candidateStatus string Candidate Status lookup code
candidateType string Candidate Type lookup code
candidateSource string Candidate Source lookup code
nationality string Nationality lookup code
jobCode string Preferred job title (lookup)
jobType string Legacy alias of jobCode
resourcerJobTitle string Free-text current job title
previousJobTitles string  
dateOfBirth date-time dd MMM yyyy
dateAvailable date-time dd MMM yyyy
currentSalary int32  
wantedSalary int32  
currentPay int32  
wantedPay int32  
noticePeriod int32  
salaryBreakdown string  
currencyCode string Currency lookup code
addressLine1 string (legacy alias: address1)
addressLine2 string (legacy alias: address2)
addressLine3 string (legacy alias: address3)
city string (legacy alias: town)
county string  
postcode string  
country string Country lookup code
noteTab int32 Note tab to write notes to (0-4)
notes string  
customFields array<CustomFieldToAdd> Custom fields to set
skillsToAdd array<SkillToAdd> Skills to add
username string Candidate portal login; requires password
password string Candidate portal login; requires username
createdBy string Attribute creation to another user (defaults to userId)
bypassMandatoryCheck boolean Ignore mandatory-field errors; requires the 'Allow Mandatory Bypass' API global setting
UpdateCandidateRequest
Field Type Notes
userId REQUIRED string  
candidateId REQUIRED int64  
candidateUpdates array<PatchDto> Standard fields to update
customFieldUpdates array<PatchDto> Custom fields to update
skillsToAdd array<SkillToAdd> Skills to add
amendedBy string Attribute the change to another user
InsertCandidateExperienceRequest
Field Type Notes
userId REQUIRED string  
candidateId REQUIRED int64 Owning Candidate
jobType REQUIRED int32 0 Contract, 1 Permanent, 2 Rolling Contract, 3 Unknown, 4 Education
jobTitle REQUIRED string  
companyName string  
contactName string  
location string  
workingCompanyId int64  
owningCompany string  
startDate date-time  
endDate date-time  
chargeRate double  
otChargeRate double  
payRate double  
otPayRate double  
noticePeriod int32  
notes string  
skillsToAdd array<SkillToAdd>  
UpdateCandidateExperienceRequest
Field Type Notes
userId REQUIRED string  
situationId REQUIRED int64 The Experience Id
experienceUpdates array<PatchDto> Fields to update
skillsToAdd array<SkillToAdd>  
InsertCompanyRequest
Field Type Notes
userId REQUIRED string  
companyName REQUIRED string  
parentCompany int64 Parent Company Id
industry string  
companyType string  
website string  
companyEmail string  
telephone string  
fax string  
employeeCount string  
registrationNumber string  
vatNumber string  
addressLine1 string  
addressLine2 string  
addressLine3 string  
city string  
county string  
postcode string  
country string  
addressType int32  
customFields array<CustomFieldToAdd>  
skillsToAdd array<SkillToAdd>  
noteTab int32 0-4
notes string  
createdBy string  
bypassMandatoryCheck boolean Requires 'Allow Mandatory Bypass'
UpdateCompanyRequest
Field Type Notes
userId REQUIRED string  
companyId REQUIRED int64  
companyUpdates array<PatchDto>  
customFieldUpdates array<PatchDto>  
skillsToAdd array<SkillToAdd>  
addSkillsToContacts boolean Also add the skills to the Company's Contacts
amendedBy string  
InsertContactRequest
Field Type Notes
userId REQUIRED string  
companyId REQUIRED int64 Company the Contact works for
addressId int64 Company address to use
forenames REQUIRED string  
surname REQUIRED string  
knownAs string  
title string  
jobTitle string  
department string  
directNumber string  
directFax string  
otherNumber string  
emailAddress1 string  
emailAddress2 string  
companyWebsite string  
reportsTo int64 Contact Id
assistant int64 Contact Id
startDate date-time  
endDate date-time  
contactType string  
customFields array<CustomFieldToAdd>  
skillsToAdd array<SkillToAdd>  
noteTab int32 0-4
notes string  
copySkillsToCompany boolean  
copySkillsToOtherContacts boolean  
copySkillsFromCompany boolean  
createdBy string  
bypassMandatoryCheck boolean Requires 'Allow Mandatory Bypass'
UpdateContactRequest
Field Type Notes
userId REQUIRED string  
contactId REQUIRED int64  
contactUpdates array<PatchDto>  
customFieldUpdates array<PatchDto>  
skillsToAdd array<SkillToAdd>  
addSkillsToCompany boolean  
addSkillsToContacts boolean  
amendedBy string  
InsertLeadRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
leadTitle string  
leadSource string Lead Source (LEADSOURCE) description or code. Defaults to the default source.
status string Lead Status (LEADSTATUS) description or code. Defaults to the default status. A closing status sets the Date Closed.
companyId int64 Optional. An existing Company to link to; its name is used as the Company Name.
contactId int64 Optional. An existing Contact to link to. The Lead is linked to the Contact's Company, and the Contact's telephone number and email address are used where none are given.
companyName string The company name when the Lead is not linked to a Company record
contactName string The contact name when the Lead is not linked to a Contact record
addressId int64 One of the Company's addresses. Defaults to the Contact's address.
location string  
contactTelephoneNumber string  
contactEmailAddress string  
currency string Currency (CURRENCY) description or code. Defaults to the default currency.
potentialValue double  
expectedDate date-time  
additionalFields array<PatchDto> Any other Lead fields by name (see Field/GetSearchableFields?EntityType=Lead)
customFields array<CustomFieldToAdd> Custom fields to set
noteTab int32 Note tab for notes (0-4)
notes string  
createdBy string Attribute the record to another user
UpdateLeadRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
leadId REQUIRED int64  
leadUpdates array<PatchDto> Fields to update by name, e.g. Lead Title. A blank value clears the field. Company Id / Contact Id link existing records (0 unlinks); Address Id must be one of the Company's addresses; Company Name and Contact Name can only be typed when the Lead is not linked.
customFieldUpdates array<PatchDto> Custom fields to update, by label. A blank value clears the field.
amendedBy string Attribute the change to another user
AdvanceSearchCandidateRequest
Field Type Notes
userId REQUIRED string  
allColumns boolean Return every column
columns array<string> Columns to return
includeArchived boolean  
parameters array<SearchValue> Search criteria
AdvanceSearchCompanyRequest
Field Type Notes
userId REQUIRED string  
allColumns boolean  
columns array<string>  
includeArchived boolean  
parameters array<SearchValue>  
AdvanceSearchContactRequest
Field Type Notes
userId REQUIRED string  
allColumns boolean  
columns array<string>  
includeArchived boolean  
parameters array<SearchValue>  
AdvanceSearchLeadRequest
Field Type Notes
userId REQUIRED string  
allColumns boolean  
columns array<string>  
parameters array<SearchValue>  
AdvanceSearchRequirementRequest
Field Type Notes
userId REQUIRED string  
includeApplyLink boolean Include an application link per Requirement
allColumns boolean  
columns array<string>  
splitJobTitle boolean  
parameters array<SearchValue>  
AdvanceSearchPlacementRequest
Field Type Notes
userId REQUIRED string  
allColumns boolean  
columns array<string>  
splitJobTitle boolean  
parameters array<SearchValue>  
InsertRequirementRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
contactId int64 The hiring Contact. The Requirement belongs to the Contact's Company. Defaults to the Lead's Contact when leadId is given.
leadId int64 Optional. The Lead the Requirement comes from. It must be linked to the Requirement's Company; its title, address and currency are used where none are given.
companyId int64 Optional. If given, it must be the Contact's Company.
addressId int64 One of the Company's addresses. Defaults to the Contact's address.
jobTitle string  
requirementType int32 0 Contract, 1 Permanent, 2 Rolling Contract, 3 Fixed Term Contract. Defaults to the user's default job type.
status string Requirement Status (REQSTATUS) description or code. Defaults to the default status.
currency string Currency (CURRENCY) description or code. Defaults to the default currency.
startDate date-time  
numberOfPlaces int32 Defaults to 1
expMinSalary / expMaxSalary double Permanent and Fixed Term Contract only
expChargeRate / expPayRate double Contract and Rolling Contract only
chargeUnit int32 What the rates are per: 0 Hour, 1 Day, 2 Week, 3 Month. Defaults to the system default.
pickedUpBy string User who picked the job up (user id, name or email). Defaults to userId, picked up today.
additionalFields array<PatchDto> Any other Requirement fields by name (see Field/GetSearchableFields), e.g. Hours Per Week
customFields array<CustomFieldToAdd> Custom fields to set
requirementTemplateId int64 A Requirement Template (one of the Company's) to apply: it fills in anything not given and adds its rates, as on the screen
skillsToAdd array<SkillToAdd> Skills to add
noteTab int32 Note tab for notes (0-4)
notes string  
createdBy string Attribute the record to another user
UpdateRequirementRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
requirementId REQUIRED int64  
requirementUpdates array<PatchDto> Fields to update by name, e.g. Job Title. A blank value clears the field. Contact Id, Address Id and Lead Id (0 unlinks) can be changed; the Company cannot.
customFieldUpdates array<PatchDto> Custom fields to update, by label. A blank value clears the field.
skillsToAdd array<SkillToAdd> Skills to add
amendedBy string Attribute the change to another user
UpdatePlacementRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
placementId REQUIRED int64  
placementUpdates array<PatchDto> Fields to update by name, e.g. Pay Rate. A blank value clears the field. Fields locked on the screen stay locked; Margin is calculated.
customFieldUpdates array<PatchDto> Custom fields to update, by label. A blank value clears the field.
amendedBy string Attribute the change to another user
RequirementCandidateRequest
Field Type Notes
userId REQUIRED string  
requirementId REQUIRED int64  
candidateId REQUIRED int64  
overrideCandidateSource string Candidate Source lookup code
shortlistImmediately boolean  
generateNotifications boolean  
statusCode string Shortlist status code
sentBy string  
chargeRate double  
payRate double  
salary double  
notes string  
dateSent date-time  
rank double  
UpdateChecklistItemRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
entityType REQUIRED string The record's entity type: 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead (or the entity name)
entityId REQUIRED int64 The record's Id
checklistTemplateId int64 The item, by ChecklistTemplateId (as returned by Checklist/Get). Either this or checklistItemId.
checklistItemId int64 The item, by ChecklistItemId (only items already saved on the record have one)
isComplete boolean true marks complete (on completionDate, or today); false marks not complete and clears the date. Omit to leave as is.
completionDate string e.g. 2026-11-12. Completes the item, or changes the date of a completed item.
completedBy string User id, name or email. Defaults to userId.
status string Checklist Status (CHECKLISTSTATUS) description or code; blank clears it
notes string Blank clears them
sentDate string e.g. 2026-11-12; blank clears it
expiryDate string e.g. 2027-11-12; blank clears it. Also set on the item's document.
AddChecklistItemsRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
entityType REQUIRED string Placements (4) only
entityId REQUIRED int64 The Placement Id
checklistTemplateIds REQUIRED array<int64> The items to add (see Checklist/GetTemplates)
DeleteChecklistItemsRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
entityType REQUIRED string Placements (4) only
entityId REQUIRED int64 The Placement Id
checklistTemplateIds array<int64> Items to delete, by ChecklistTemplateId
checklistItemIds array<int64> Items to delete, by ChecklistItemId
ChecklistItemRequest
Field Type Notes
userId REQUIRED string The Colleague 7 User Id
entityType REQUIRED string The record's entity type: 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead (or the entity name)
entityId REQUIRED int64 The record's Id
checklistTemplateId int64 The item, by ChecklistTemplateId. Either this or checklistItemId.
checklistItemId int64 The item, by ChecklistItemId
AddHistoryRequest
Field Type Notes
userId REQUIRED string  
historyText REQUIRED string  
historyCode REQUIRED string History type code
historyDate REQUIRED date-time  
participants REQUIRED array<EntityId> Entities the history item is attached to
GetNotesRequest
Field Type Notes
userId REQUIRED string  
noteIds REQUIRED array<int64>  
noteSequence int32 Omit for all notes
fetchAsHTML boolean  
UpdateEntityNoteRequest
Field Type Notes
userId REQUIRED string  
entityType REQUIRED int32 0 Candidate, 1 Company, 2 Contact, 3 Requirement, 4 Placement, 25 Lead
entityId REQUIRED int64  
noteSequence REQUIRED int32 0 = Note 1, 100 = Note 2, 200 = Note 3 ...
noteContent REQUIRED string  
GetEntitySkillsRequest
Field Type Notes
userId REQUIRED string  
entityType REQUIRED int32 0 Candidate, 3 Requirement
entityIds REQUIRED array<int64>  
Shared building blocks
PatchDto
Field Type Notes
fieldName string Field to change
fieldValue any New value
CustomFieldToAdd
Field Type Notes
customFieldName string From Field/GetPublicCustomFields
customFieldValue any  
SkillToAdd
Field Type Notes
lookupCode string  
lookupParent string  
lookupPath string  
skillGrade string  
SearchValue
Field Type Notes
fieldName string From Field/GetSearchableFields
fieldValue string  
EntityId
Field Type Notes
entityType REQUIRED int32 Entity type code
entityId REQUIRED int64  
Response models
GetCandidateResponse
Field Type Notes
candidateId int64  
title string  
forenames string  
surname string  
knownAs string  
gender string  
married string  
dateOfBirth date-time  
nationality string  
emailAddress string  
emailAddress2 string  
webAddress string  
candidateStatus string  
candidateType string  
candidateSource string  
dateAvailable date-time  
jobCode string  
resourcerJobTitle string  
currentPay / requiredPay / wantedPay double  
currentSalary / wantedSalary double  
salaryBreakdown string  
noticePeriod int32  
consentRequested / responseReceived date-time GDPR consent dates
consentGiven string  
directNumber / directFax / mobileNumber / otherNumber string  
mailshotStatus string  
currencyCode string  
addressLine1-3, city, county, postcode, country string  
telephoneNumber / faxNumber / addressDesc string  
notes array<{name,text}>  
customFields array<{name,value}>  
skills array<Skill>  
GetCandidateDocumentsResponse
Field Type Notes
documents array<Document> documentId, defaultDocument, documentName, description, documentType, dateUploaded, uploadedBy, dateAmended, amendedBy, downloadLink
Situation
Field Type Notes
situationId int64 Experience Id
candidateId int64  
jobTitle string  
jobType / jobTypeDescription int32 / string  
companyId / companyName int64 / string  
contactId / contactName int64 / string  
startDate / endDate date-time  
salary / chargeRate / payRate / overtimeChargeRate / overtimePayRate double  
noticePeriod / noticePeriodUOM    
placedByUs / placedBy    
placementId and placement* fields   Populated when the experience came from a Colleague placement
location / notes string  
dateCreated / createdBy / dateAmended / amendedBy    
Note
Field Type Notes
noteId int64  
sequenceId int32  
noteText string  
dateCreated / createdBy / dateAmended / amendedBy string  
valueHeader string Note tab heading
isMandatory / activeFlag int32  
Skill
Field Type Notes
ownerId int64  
lookupCode string  
description string  
lookupParent string  
lookupPath string  
children array<Skill> Nested skills
Lookup
Field Type Notes
lookupCode string  
description string  
lookupParent string  
allowSelection int32  
children array<Lookup>  
GetLookupsResponse
Field Type Notes
lookups array<Lookup>  
GetCandidateLookupsResponse
Field Type Notes
lookups array<Lookup>  
customLookups array<Lookup>  
GetAllSkillsResponse
Field Type Notes
skills array<Skill>  
ColleagueReturnValue
Field Type Notes
status int32 0 | 1 | 2 | 3
succeeded boolean  
description string  
stringListData array<string>  
longPlaceholder / intPlaceholder1 / intPlaceholder2 / stringPlaceholder1   Call-specific return values
ReportUsers
Field Type Notes
reportUserId int64  
parentUserId int64  
reportGroupCode string  
userId string  
username string  
userType int64  
isManager string  
reportGroupType int32  
activeUser / licencedUser int32  
text string  
ChecklistItemResponse
Field Type Notes
checklistItemId int64 The saved item's Id; null until the item is first saved
checklistTemplateId int64 The item's stable identifier on the record
activity string The item's name
sequenceNo int64  
isComplete boolean  
completionDate date-time  
completedBy string  
statusCode / status string Checklist Status code and description
notes string  
sentDate / expiryDate date-time  
requiresDocument boolean A document must be attached before the item can be completed
documentId int64 The attached document, if any
canComplete boolean The API user's user group may complete this item
ChecklistTemplateResponse
Field Type Notes
checklistTemplateId int64  
activity string The item's name
sequenceNo int32  
defaultSet boolean Part of every record's checklist (Placements start with the default set only)
requiresDocument boolean  
Candidate (Advanced Search result; key fields)

candidateId, title, forenames, surname, knownAs, fullName, gender, dateOfBirth, nationality, emailAddress, emailAddress2, mobileNumber, directNumber, otherNumber, webAddress, candidateStatus(+Description), candidateType(+Description), candidateSource(+Description), jobCode(+Description), resourcerJobTitle, currentJobTitle, currentEmployer(Id), currentManager(Id), dateAvailable, currentSalary, wantedSalary, currentPay, wantedPay, noticePeriod, currencyCode, addressLine1-3, city, county, postcode, country, liveRequirements, forwardInterviews, totalNumberofPlacements, consentRequested, responseReceived, consentGiven, mailshotStatus, latestDocumentId, ownerId, lastContacted, lastContactedBy, dateCreated, createdBy, dateAmended, amendedBy, archivedDate, notes[], skills[], documents[], history[], customFieldsJson, socialMediaFieldsJson

Company (Advanced Search result; key fields)

companyId, companyName, parentCompanyId, parentCompany, industryCode, companyType, employeeCount, webAddress, companyEmail, registrationNumber, vatNumber, accountReference, telephoneNumber, addressLine1-3, city, county, postcode, country, liveRequirements, forwardInterviews, totalNumberofPlacements, invoiceCompany(Id), invoiceContact(Id), paymentTerms, ownerId, lastContacted, dateCreated, createdBy, dateAmended, amendedBy, archivedDate, notes[], skills[], documents[], history[], customFieldsJson

Contact (Advanced Search result; key fields)

contactId, companyId, companyName, title, forenames, surname, knownAs, fullName, jobTitle, department, contactType, emailAddress, emailAddress2, directNumber, mobileNumber, otherNumber, reportsTo(Id), assistant(Id), startDate, endDate, liveRequirements, totalPlacements, consentGiven, mailshotStatus, movedToCompany(Id), previousCompany(Id), ownerId, lastContacted, dateCreated, createdBy, dateAmended, amendedBy, archivedDate, notes[], skills[], documents[], history[], customFieldsJson

Endpoint index
 
Area Verb Path Purpose
Candidate GET /api/Candidate/Search Search for existing Candidate records with the supplied criteria
Candidate POST PATCH /api/Candidate/AdvancedSearch Advanced search for Candidates; returns the selected columns
Candidate GET /api/Candidate/Get Get an existing Candidate record
Candidate PUT /api/Candidate/Insert Create a Candidate record
Candidate PATCH /api/Candidate/Update Update an existing Candidate record
Candidate POST /api/Candidate/UploadDocument Upload a Document to a Candidate record
Candidate GET /api/Candidate/GetDocuments Get all documents associated with a Candidate record
Candidate GET /api/Candidate/GetExperience Get all Experiences (work history) related to a Candidate
Candidate PUT /api/Candidate/InsertExperience Create a Candidate Experience record
Candidate PATCH /api/Candidate/UpdateExperience Update an existing Candidate Experience record
Candidate GET /api/Candidate/Login Validate a Candidate portal login
Company GET /api/Company/Search Search for existing Company records
Company POST PATCH /api/Company/AdvancedSearch Advanced search for Companies; returns the selected columns
Company GET /api/Company/Get Get an existing Company record
Company PUT /api/Company/Insert Create a Company record
Company PATCH /api/Company/Update Update an existing Company record
Contact GET /api/Contact/Search Search for existing Contact records
Contact POST PATCH /api/Contact/AdvancedSearch Advanced search for Contacts; returns the selected columns
Contact GET /api/Contact/Get Get an existing Contact record
Contact PUT /api/Contact/Insert Create a Contact record
Contact PATCH /api/Contact/Update Update an existing Contact record
Lead GET /api/Lead/Search Search for existing Lead records
Lead POST PATCH /api/Lead/AdvancedSearch Advanced search for Leads; returns the selected columns
Lead GET /api/Lead/Get Get an existing Lead record
Lead PUT /api/Lead/Insert Create a Lead record
Lead PATCH /api/Lead/Update Update an existing Lead record
Requirement GET /api/Requirement/Search Search for existing Requirement (job) records
Requirement POST PATCH /api/Requirement/AdvancedSearch Advanced search for Requirements; returns the selected columns
Requirement GET /api/Requirement/Get Get an existing Requirement record
Requirement PUT /api/Requirement/Insert Create a Requirement (job) record
Requirement PATCH /api/Requirement/Update Update an existing Requirement record
Requirement GET /api/Requirement/GetRequirementCandidates List the Candidates attached to a Requirement
Requirement POST /api/Requirement/InsertRequirementCandidate Add a Candidate to a Requirement (shortlist / send)
Requirement POST /api/Requirement/SubmitApplication Submit a job application to a Requirement
Placement GET /api/Placement/Search Search for existing Placement records
Placement POST PATCH /api/Placement/AdvancedSearch Advanced search for Placements; returns the selected columns
Placement GET /api/Placement/Get Get an existing Placement record
Placement PATCH /api/Placement/Update Update an existing Placement (or Offer) record
Checklist GET /api/Checklist/GetTemplates Get the checklist items set up for an entity type
Checklist GET /api/Checklist/Get Get a record's checklist
Checklist PATCH /api/Checklist/UpdateItem Update one item on a record's checklist
Checklist POST /api/Checklist/AddItems Add checklist items to a Placement
Checklist POST /api/Checklist/DeleteItems Delete items from a Placement's checklist
Checklist POST /api/Checklist/AttachDocument Attach a document to a checklist item
Checklist POST /api/Checklist/RemoveDocument Remove a checklist item's document
Document GET /api/Document/Download Download a specific Document
Document GET /api/Document/DownloadLatestCandidateDocument Download the latest Document for a Candidate
Document GET /api/Document/GetLatestCandidateDocumentInfo Get metadata for a Candidate's latest Document
Document GET /api/Document/GetSocialMediaLinks Get the social media links for an entity
Document PUT /api/Document/InsertSocialMediaLink Add a social media link to an entity
Document POST /api/Document/UpdateSocialMediaLink Update a social media link
Document DELETE /api/Document/DeleteSocialMediaLink Delete a social media link
Notes GET /api/Notes/GetForEntity Get Notes for an entity
Notes PUT /api/Notes/Get Get Notes by Note Id
Notes PUT /api/Notes/InsertUpdateNoteForEntity Insert or update a Note on an entity
History GET /api/History/GetForEntity Get recent History (activity) items for an entity
History PUT /api/History/AddToEntities Add one History item to multiple participants
History POST /api/History/Update Update an existing History item
List GET /api/List/GetLists Get all Lists belonging to a user
List GET /api/List/GetListContents Get all records in a List
List PUT /api/List/InsertList Create a List for a user
List PUT /api/List/InsertListRecord Add a record to a List
List DELETE /api/List/DeleteList Delete a user's List
List DELETE /api/List/DeleteListRecord Remove a record from a List
Ownership GET /api/Ownership/List List the owners of an entity
Ownership PUT /api/Ownership/AddUserOwner Add a User as an owner of an entity
Ownership PUT /api/Ownership/AddReportOwner Add a Report User or Team as an owner of an entity
Lookup GET /api/Lookup/Get Get lookups beneath a parent (top level if no parent)
Lookup GET /api/Lookup/GetCandidateLookups Get the lookups in use on Candidate records
Skill GET /api/Skill/GetAll Get the full skills tree
Skill PUT /api/Skill/GetEntitySkills Get the skills on one or more entities
Field GET /api/Field/GetSearchableFields Get the searchable fields for an entity type
Field GET /api/Field/GetPublicCustomFields Get the public custom fields for an entity type
User GET /api/User/Get List users
Teams GET /api/Teams/GetByUser Get the Report Teams a user belongs to or manages
Compiled from the Colleague 7 Open API definition (OpenAPI 3.0.1, version 1.0) published on the Azure API Management developer portal, and the Colleague 7 help centre. Retrieved 14 October 2026; updated 19 November 2026 for the Lead, Checklist, Requirement and Placement additions. The live definition is authoritative; download it from the developer portal (Open API 3 JSON/YAML) for code generation.