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.
81
operations (incl. dual-verb searches)
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).
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.
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 2 53. 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.
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.
| 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.
1. Job board / careers site
POST /api/Requirement/AdvancedSearch with includeApplyLink: true and filters (status, type), or GET /api/Requirement/Search.
- 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.
- 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
GET /api/Candidate/Search?EmailAddress=…
- No match:
PUT /api/Candidate/Insert, which returns the new Id.
Match: PATCH /api/Candidate/Update with only the changed fields.
POST /api/Candidate/UploadDocument with DefaultDocument=1 for the CV.
- 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)
GET /api/Company/Search?CompanyName=…, then PUT /api/Company/Insert if not found.
GET /api/Contact/Search?EmailAddress=…, then PUT /api/Contact/Insert with companyId.
- Set the owner with
PUT /api/Ownership/AddUserOwner.
- 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)
- Resolve the person: Candidate/Contact Search by phone or email.
PUT /api/History/AddToEntities with every participant (e.g. Candidate + Contact + Company) in one call.
- Read the timeline back with
GET /api/History/GetForEntity.
5. Reporting / data extract
GET /api/Field/GetSearchableFields for each entity type to discover columns.
POST …/AdvancedSearch with an explicit columns list. Avoid allColumns: true, which returns large payloads.
- 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)
GET /api/Lookup/GetCandidateLookups and GET /api/Lookup/Get (top level, then children)
GET /api/Skill/GetAll
GET /api/Field/GetPublicCustomFields per entity
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)
- Capture the opportunity with
PUT /api/Lead/Insert, linked to an existing Company / Contact or with typed names.
- Track progress with
PATCH /api/Lead/Update (status, value, expected date). A closing status sets the Date Closed.
- When it becomes a vacancy,
PUT /api/Requirement/Insert with leadId; the Lead's title, address and currency fill any gaps.
- 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
GET /api/Checklist/GetTemplates per entity type to map item names to checklistTemplateId.
GET /api/Checklist/Get?IncompleteOnly=true to see what is outstanding on a Candidate or Placement.
- Upload evidence with
POST /api/Checklist/AttachDocument (needed first for items with requiresDocument).
- Complete the item with
PATCH /api/Checklist/UpdateItem, setting expiryDate where relevant.
- 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.
- 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.
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.
GET /api/Candidate/SearchSearch for existing Candidate records with the supplied criteria
Returns IDs only. Call /api/Candidate/Get for each ID, or use Advanced Search to return columns in one call.
QUERY PARAMETERS
| Name |
Type |
Req. |
Description |
UserId |
string |
yes |
The Colleague 7 User Id |
Forenames |
string |
|
Candidates whose forenames begin with this term |
Surname |
string |
|
Candidates whose surname begins with this term |
EmailAddress |
string |
|
Candidates where any email address contains this term |
TelephoneNumber |
string |
|
Candidates where any telephone number contains this term |
IncludeArchivedRecords |
boolean |
|
Also include archived records |
RESPONSES
| Code |
Meaning |
Body |
| 200 |
The Candidate Ids of all found Candidates |
array<int64> |
| 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/Search?UserId={UserId}" \
-H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
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
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.
GET /api/Company/SearchSearch for existing Company records
QUERY PARAMETERS
| Name |
Type |
Req. |
Description |
UserId |
string |
yes |
The Colleague 7 User Id |
CompanyName |
string |
|
The beginning of the Company name |
TelephoneNumber |
string |
|
Companies where any address phone number contains this term |
IncludeArchivedRecords |
boolean |
|
Also include archived records |
RESPONSES
| Code |
Meaning |
Body |
| 200 |
The Company Ids of all found Companies |
array<int64> |
| 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/Company/Search?UserId={UserId}" \
-H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
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"
}'
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.
GET /api/Lead/SearchSearch for existing Lead records
Set IdsOnly=true to return Lead IDs only; by default full details are returned. Status and LeadSource accept the lookup description or code.
QUERY PARAMETERS
| Name |
Type |
Req. |
Description |
UserId |
string |
yes |
The Colleague 7 User Id |
AllLeads |
boolean |
|
Return all available Leads |
LeadTitle |
string |
|
Leads whose title contains this term |
CompanyName |
string |
|
Leads whose company name contains this term |
ContactName |
string |
|
Leads whose contact name contains this term |
CompanyId |
int64 |
|
Leads linked to this Company |
ContactId |
int64 |
|
Leads linked to this Contact |
Status |
string |
|
Lead Status (LEADSTATUS lookup description or code) |
LeadSource |
string |
|
Lead Source (LEADSOURCE lookup description or code) |
CreatedAfter |
date-time |
|
Created on or after this date/time |
CreatedBefore |
date-time |
|
Created before this date/time |
LeadId |
int64 |
|
Fetch this Lead only (all other criteria are ignored) |
IdsOnly |
boolean |
|
Return only Lead IDs (default returns full details) |
RESPONSES
| Code |
Meaning |
Body |
| 200 |
Matching Leads |
array<object> |
| 400 / 401 / 500 |
Standard errors (see Errors) |
string |
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Lead/Search?UserId={UserId}" \
-H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
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.
GET /api/Requirement/SearchSearch for existing Requirement (job) records
QUERY PARAMETERS
| Name |
Type |
Req. |
Description |
UserId |
string |
yes |
The Colleague 7 User Id |
AllRequirements |
boolean |
|
Return all available requirements |
CompanyName |
string |
|
Requirements for Companies containing this term |
ContactName |
string |
|
Requirements for Contacts containing this term |
JobTitle |
string |
|
Requirements whose job title contains this term |
SplitJobTitle |
boolean |
|
Split the job title on spaces, e.g. 'C# Developer' also matches 'Junior Developer, C#' |
Status |
string |
|
Requirement Status lookup code (REQSTATUS lookup) |
Type |
int32 |
|
-100 Any, 0 Contract, 1 Permanent, 2 Rolling Contract, 3 Fixed Term Contract |
PickedUpAfter |
date-time |
|
Picked up on or after this date/time |
PickedUpBefore |
date-time |
|
Picked up before this date/time |
RequirementId |
int64 |
|
Fetch this Requirement only (all other criteria are ignored) |
IdsOnly |
boolean |
|
Return only Requirement IDs (default returns full details) |
RESPONSES
| Code |
Meaning |
Body |
| 200 |
Matching Requirements |
array<object> |
| 400 / 401 / 500 |
Standard errors (see Errors) |
string |
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Requirement/Search?UserId={UserId}" \
-H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
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.
GET /api/Placement/SearchSearch for existing Placement records
The published parameter descriptions for this call were copied from Requirement Search; they are restated here for Placements.
QUERY PARAMETERS
| Name |
Type |
Req. |
Description |
UserId |
string |
yes |
The Colleague 7 User Id |
AllPlacements |
boolean |
|
Return all available placements |
CompanyName |
string |
|
Placements for Companies containing this term |
ContactName |
string |
|
Placements for Contacts containing this term |
JobTitle |
string |
|
Job title contains this term |
SplitJobTitle |
boolean |
|
Split the job title search term on spaces |
Status |
string |
|
Status lookup code |
Type |
int32 |
|
-100 Any, 0 Contract, 1 Permanent, 2 Rolling Contract, 3 Fixed Term Contract |
PickedUpAfter |
date-time |
|
On or after this date/time |
PickedUpBefore |
date-time |
|
Before this date/time |
PlacementId |
int64 |
|
Fetch this Placement only (all other criteria are ignored) |
IdsOnly |
boolean |
|
Return only IDs |
RESPONSES
| Code |
Meaning |
Body |
| 200 |
Matching Placements |
array<object> |
| 400 / 401 / 500 |
Standard errors (see Errors) |
string |
EXAMPLE
curl -X GET "https://coll7openapi.azure-api.net/api/Placement/Search?UserId={UserId}" \
-H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"
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
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
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"
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 |
|
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> |
|
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
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.
|