Colleague API Developer Guide

Authentication, conventions and every published operation.

API Portal API Developer Guide API Access API Field Directory Support Team

ON THIS PAGE

Overview Authentication Conventions Reference codes Errors Integration patterns Gotchas Schemas Endpoint index

ENDPOINTS

Candidate Company Contact Requirement Placement Document Notes History List Ownership Lookup Skill Field User Teams

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.

endpoints

operations (incl. dual-verb searches)

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
Requirement	A job / vacancy	-	via search	Attach candidates	Simple + Advanced
Placement	A placement or offer	-	via search	-	Simple + Advanced

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

The API cannot create or update Requirements or Placements, and it has no delete operations for core records. The only deletes are for lists, list entries and social media links. Plan any job or placement sync as read-only from Colleague.

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) 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.

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⁵³. 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. 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)

Field/GetSearchableFields and GetPublicCustomFields take the entity name as text instead.

Requirement / Placement type

-100	Any
0	Contract
1	Permanent
2	Rolling Contract
3	Fixed Term Contract

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

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.
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.

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, 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-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.

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

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.

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"
  }'

Contact

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

GET /api/Contact/SearchSearch for existing Contact records

QUERY PARAMETERS

Name	Type	Req.	Description
`UserId`	string	yes	The Colleague 7 User Id
`Forenames`	string		Contacts whose forenames begin with this term
`Surname`	string		Contacts whose surname begins with this term
`EmailAddress`	string		Contacts where any email address contains this term
`TelephoneNumber`	string		Contacts where any phone number contains this term
`IncludeArchivedRecords`	boolean		Also include archived records
`IncludeLeaverRecords`	boolean		Also include leavers

RESPONSES

Code	Meaning	Body
200	The Contact Ids of all found Contacts	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/Contact/Search?UserId={UserId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"

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"
  }'

Requirement

Jobs / vacancies, 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/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

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"
      }
    ]
  }'

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"

GET /api/Document/GetSocialMediaLinksGet the social media links 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
`EntityId`	int64	yes	The entity Id
`SocialMediaType`	int32		-1 by lookup, 0 Facebook, 1 LinkedIn, 2 Twitter
`SocialMediaLookupType`	string		Lookup type when SocialMediaType = -1; send -1 and blank to return all links

RESPONSES

Code	Meaning	Body
200	Social media links	array<object>
400 / 401 / 500	Standard errors (see Errors)	string

EXAMPLE

curl -X GET "https://coll7openapi.azure-api.net/api/Document/GetSocialMediaLinks?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}" \
  -H "Ocp-Apim-Subscription-Key: $COLLEAGUE_API_KEY"

PUT /api/Document/InsertSocialMediaLinkAdd a social media link to 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
`EntityId`	int64	yes	The entity Id
`SocialMediaType`	int32	yes	-1 by lookup, 0 Facebook, 1 LinkedIn, 2 Twitter
`SocialMediaUrl`	string	yes	The URL
`Description`	string	yes	Link description
`SocialMediaLookupType`	string		Lookup type when SocialMediaType = -1

RESPONSES

Code	Meaning	Body
200	Link added	(empty)
400 / 401 / 500	Standard errors (see Errors)	string

EXAMPLE

curl -X PUT "https://coll7openapi.azure-api.net/api/Document/InsertSocialMediaLink?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}&SocialMediaType={SocialMediaType}&SocialMediaUrl={SocialMediaUrl}&Description={Description}" \
  -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"

DELETE /api/Document/DeleteSocialMediaLinkDelete 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
`SocialMediaType`	int32	yes	-1 by lookup, 0 Facebook, 1 LinkedIn, 2 Twitter
`DocumentId`	int64		Specific link to delete; if omitted the latest link of the type is deleted
`SocialMediaLookupType`	string		Lookup type when SocialMediaType = -1

RESPONSES

Code	Meaning	Body
200	Link deleted	(empty)
400 / 401 / 500	Standard errors (see Errors)	string

EXAMPLE

curl -X DELETE "https://coll7openapi.azure-api.net/api/Document/DeleteSocialMediaLink?UserId={UserId}&EntityType={EntityType}&EntityId={EntityId}&SocialMediaType={SocialMediaType}" \
  -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
`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 or Contact (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

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>

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>

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

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
`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

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
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/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
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. The live definition is authoritative; download it from the developer portal (Open API 3 JSON/YAML) for code generation.