Talent & Contingent Workforce · Talent
Contingent Candidates
The database, which in a staffing business is the asset. Right to work and its expiry are columns rather than notes, because a contractor whose permission runs out mid-assignment is the most expensive mistake in this module.
/api/ats/candidatesPublished as /api/v1/candidatesDownload specification (OpenAPI 3.1) Screen: Contingent Candidates
Overview
| Package | Talent & Contingent Workforce |
|---|---|
| Authentication | Bearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key |
| Authorization | The caller's roles must hold Talent & Contingent Workforce › Contingent Candidates on the Roles screen: display for GET, add for POST, change for PUT, delete for DELETE; an action needs the grant of the button that runs it on the screen. |
| Table | ats.candidates · kept per company (and organisational unit where it has one) |
| Record | Created, changed and (where the screen allows) deleted; key id |
| Rules | The same as the screen: validation, numbering, approvals, posting, the company the caller belongs to, and the audit trail. |
API reference
21 operations. Open one for its parameters, bodies, responses and a sample request.
GET/api/ats/candidatesList contingent candidates
Query parameters
| Name | Description | Example |
|---|---|---|
limit | Rows per page (50 by default, at most 200) | limit=100 |
offset | Rows to skip | offset=200 |
q | Free-text search over the search columns | q=acme |
sort | column:asc or column:desc, several separated by commas | sort=created_at:desc |
filter | A JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sorted | filter={"col":"status","op":"eq","value":"open"} |
<field>=<value> | Shorthand for "field is value" |
Response 200
{
"rows": [
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"location_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"candidate_no": "CAN-000001",
"first_name": "Example",
"last_name": "Example",
"preferred_name": "Example",
"name_local": "Example",
"email": "someone@example.com",
"phone": "+1 555 0100",
"mobile": "+1 555 0100",
"address": "text",
"city": "text",
"state": "text"
}
],
"count": 1
}Sample request
curl "https://demo.tranxact.ai/api/ats/candidates?limit=20" \
-H "Authorization: Bearer $TOKEN"GET/api/ats/candidates/{id}Read one candidates
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"location_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"candidate_no": "CAN-000001",
"first_name": "Example",
"last_name": "Example",
"preferred_name": "Example",
"name_local": "Example",
"email": "someone@example.com",
"phone": "+1 555 0100",
"mobile": "+1 555 0100",
"address": "text",
"city": "text",
"state": "text"
}404 when no record with that id is visible to the caller.
Sample request
curl "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidatesCreate a candidates
Request body
The record as JSON. Fields marked Yes are required.
| Field | Type | Required | Description |
|---|---|---|---|
location_id | uuid | No | Office |
first_name | text | Yes | First name |
last_name | text | Yes | Last name |
preferred_name | text | No | Preferred name |
name_local | text | No | Local name |
email | text | No | |
phone | text | No | Phone |
mobile | text | No | Mobile |
address | text | No | Address |
city | text | No | City |
state | text | No | State or province |
country | text | No | Country |
postal_code | text | No | Postal code |
current_title | text | No | Current title |
current_employer | text | No | Current employer |
total_experience_years | numeric | No | Experience (years) |
education_level | text | No | Education |
linkedin_url | text | No | |
source | text | No | Source |
source_detail | text | No | Source detail |
referred_by | text | No | Referred by |
owner_recruiter_id | uuid | No | Owning recruiter |
work_authorization | text | No | Right to work |
work_auth_expires_on | date | No | Right to work expires — Watched by the compliance sweep. Blank means it does not expire — not that nobody checked. |
employment_preference | text | No | Prefers to work as |
supplier_id | uuid | No | Through supplier — For a corp-to-corp candidate: the company they come through, and the one that gets paid. |
willing_to_relocate | boolean | No | Will relocate |
willing_remote | boolean | No | Will work remotely |
availability_date | date | No | Available from |
notice_period_days | integer | No | Notice period (days) |
currency | text | No | Currency |
rate_unit | text | No | Rate unit Allowed: hour day week month year fixed |
desired_pay_rate | numeric | No | Wants (rate) |
desired_salary | numeric | No | Wants (salary) |
status | text | No | Status |
rating | integer | No | Rating |
resume_summary | text | No | Summary |
notes | text | No | Notes |
employee_id | uuid | No | Employee record — Set when a contractor converts, or when an existing employee is also a candidate. |
student_id | uuid | No | Student record — A placement against this candidate writes back to the student’s own career record. |
user_id | uuid | No | Portal sign-in |
consent_given_on | date | No | Consent given — "We have had their CV since 2019" is not a lawful basis for holding it. |
consent_source | text | No | Consent source |
do_not_contact | boolean | No | Do not contact |
is_active | boolean | No | Active |
Sample body
{
"first_name": "Example",
"last_name": "Example",
"location_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"preferred_name": "Example",
"name_local": "Example",
"email": "someone@example.com"
}Response 201
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"location_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"candidate_no": "CAN-000001",
"first_name": "Example",
"last_name": "Example",
"preferred_name": "Example",
"name_local": "Example",
"email": "someone@example.com",
"phone": "+1 555 0100",
"mobile": "+1 555 0100",
"address": "text",
"city": "text",
"state": "text"
}Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"first_name":"Example","last_name":"Example","location_id":"3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73","preferred_name":"Example","name_local":"Example","email":"someone@example.com"}'PUT/api/ats/candidates/{id}Change a candidates
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
Only the fields to change; fields left out keep their value.
| Field | Type | Required | Description |
|---|---|---|---|
location_id | uuid | No | Office |
first_name | text | Yes | First name |
last_name | text | Yes | Last name |
preferred_name | text | No | Preferred name |
name_local | text | No | Local name |
email | text | No | |
phone | text | No | Phone |
mobile | text | No | Mobile |
address | text | No | Address |
city | text | No | City |
state | text | No | State or province |
country | text | No | Country |
postal_code | text | No | Postal code |
current_title | text | No | Current title |
current_employer | text | No | Current employer |
total_experience_years | numeric | No | Experience (years) |
education_level | text | No | Education |
linkedin_url | text | No | |
source | text | No | Source |
source_detail | text | No | Source detail |
referred_by | text | No | Referred by |
owner_recruiter_id | uuid | No | Owning recruiter |
work_authorization | text | No | Right to work |
work_auth_expires_on | date | No | Right to work expires — Watched by the compliance sweep. Blank means it does not expire — not that nobody checked. |
employment_preference | text | No | Prefers to work as |
supplier_id | uuid | No | Through supplier — For a corp-to-corp candidate: the company they come through, and the one that gets paid. |
willing_to_relocate | boolean | No | Will relocate |
willing_remote | boolean | No | Will work remotely |
availability_date | date | No | Available from |
notice_period_days | integer | No | Notice period (days) |
currency | text | No | Currency |
rate_unit | text | No | Rate unit Allowed: hour day week month year fixed |
desired_pay_rate | numeric | No | Wants (rate) |
desired_salary | numeric | No | Wants (salary) |
status | text | No | Status |
rating | integer | No | Rating |
resume_summary | text | No | Summary |
notes | text | No | Notes |
employee_id | uuid | No | Employee record — Set when a contractor converts, or when an existing employee is also a candidate. |
student_id | uuid | No | Student record — A placement against this candidate writes back to the student’s own career record. |
user_id | uuid | No | Portal sign-in |
consent_given_on | date | No | Consent given — "We have had their CV since 2019" is not a lawful basis for holding it. |
consent_source | text | No | Consent source |
do_not_contact | boolean | No | Do not contact |
is_active | boolean | No | Active |
Sample body
{
"first_name": "Example",
"last_name": "Example"
}Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"location_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"candidate_no": "CAN-000001",
"first_name": "Example",
"last_name": "Example",
"preferred_name": "Example",
"name_local": "Example",
"email": "someone@example.com",
"phone": "+1 555 0100",
"mobile": "+1 555 0100",
"address": "text",
"city": "text",
"state": "text"
}Sample request
curl -X PUT "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"first_name":"Example","last_name":"Example"}'DELETE/api/ats/candidates/{id}Delete a candidates
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{ "deleted": true }Many documents are cancelled or reversed instead; the API refuses a delete the screen would refuse.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/{id}/copyCopy
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
overrides, preview, withLinesResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copy" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"overrides":"value","preview":"value","withLines":"value"}'GET/api/ats/candidates/{parentId}/skillsSkills
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/skills" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/{parentId}/skillsSkills
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/skills" \
-H "Authorization: Bearer $TOKEN"PUT/api/ats/candidates/{parentId}/skills/{lineId}Skills
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X PUT "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/skills/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"DELETE/api/ats/candidates/{parentId}/skills/{lineId}Skills
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/skills/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"GET/api/ats/candidates/{parentId}/employmentEmployment
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/employment" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/{parentId}/employmentEmployment
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/employment" \
-H "Authorization: Bearer $TOKEN"PUT/api/ats/candidates/{parentId}/employment/{lineId}Employment
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X PUT "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/employment/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"DELETE/api/ats/candidates/{parentId}/employment/{lineId}Employment
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/employment/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"GET/api/ats/candidates/{parentId}/documentsDocuments
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/documents" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/{parentId}/documentsDocuments
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/documents" \
-H "Authorization: Bearer $TOKEN"PUT/api/ats/candidates/{parentId}/documents/{lineId}Documents
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X PUT "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/documents/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"DELETE/api/ats/candidates/{parentId}/documents/{lineId}Documents
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/documents/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/{id}/summariseSummarise
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
jobOrderId, resumeTextResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/summarise" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jobOrderId":"value","resumeText":"value"}'GET/api/ats/candidates/{id}/previewPreview
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/ats/candidates/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/preview" \
-H "Authorization: Bearer $TOKEN"POST/api/ats/candidates/from-student/{id}From student
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
recruiterIdResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/ats/candidates/from-student/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"recruiterId":"value"}'Data model
Every field of a candidates, as the API returns it. Field names are the JSON keys; any of them can be filtered and sorted on a list.
| Field | Type | Access | Description |
|---|---|---|---|
id | uuid | read only | Id |
org_id | uuid | read only | Org id |
org_unit_id | uuid | read only | Org unit id |
location_id | uuid | read, write | Office |
candidate_no | text | read only | Candidate no |
first_name | text | read, write | First name |
last_name | text | read, write | Last name |
preferred_name | text | read, write | Preferred name |
name_local | text | read, write | Local name |
email | text | read, write | |
phone | text | read, write | Phone |
mobile | text | read, write | Mobile |
address | text | read, write | Address |
city | text | read, write | City |
state | text | read, write | State or province |
country | text | read, write | Country |
postal_code | text | read, write | Postal code |
current_title | text | read, write | Current title |
current_employer | text | read, write | Current employer |
total_experience_years | numeric | read, write | Experience (years) |
education_level | text | read, write | Education |
linkedin_url | text | read, write | |
source | text | read, write | Source |
source_detail | text | read, write | Source detail |
referred_by | text | read, write | Referred by |
owner_recruiter_id | uuid | read, write | Owning recruiter |
work_authorization | text | read, write | Right to work |
work_auth_expires_on | date | read, write | Right to work expires — Watched by the compliance sweep. Blank means it does not expire — not that nobody checked. |
employment_preference | text | read, write | Prefers to work as |
supplier_id | uuid | read, write | Through supplier — For a corp-to-corp candidate: the company they come through, and the one that gets paid. |
willing_to_relocate | boolean | read, write | Will relocate |
willing_remote | boolean | read, write | Will work remotely |
availability_date | date | read, write | Available from |
notice_period_days | integer | read, write | Notice period (days) |
currency | text | read, write | Currency |
rate_unit | text | read, write | Rate unit Allowed: hour day week month year fixed |
desired_pay_rate | numeric | read, write | Wants (rate) |
desired_salary | numeric | read, write | Wants (salary) |
status | text | read, write | Status |
rating | integer | read, write | Rating |
resume_summary | text | read, write | Summary |
notes | text | read, write | Notes |
employee_id | uuid | read, write | Employee record — Set when a contractor converts, or when an existing employee is also a candidate. |
student_id | uuid | read, write | Student record — A placement against this candidate writes back to the student’s own career record. |
user_id | uuid | read, write | Portal sign-in |
consent_given_on | date | read, write | Consent given — "We have had their CV since 2019" is not a lawful basis for holding it. |
consent_source | text | read, write | Consent source |
do_not_contact | boolean | read, write | Do not contact |
last_contacted_at | timestamp with time zone | read only | Last contacted at |
is_active | boolean | read, write | Active |
created_at | timestamp with time zone | read only | Created at |
created_by | uuid | read only | Created by |
updated_at | timestamp with time zone | read only | Updated at |
updated_by | uuid | read only | Updated by |
xf_text_1 | text | read only | Xf text 1 |
xf_text_2 | text | read only | Xf text 2 |
xf_text_3 | text | read only | Xf text 3 |
xf_text_4 | text | read only | Xf text 4 |
xf_text_5 | text | read only | Xf text 5 |
xf_num_1 | numeric | read only | Xf num 1 |
xf_num_2 | numeric | read only | Xf num 2 |
xf_num_3 | numeric | read only | Xf num 3 |
xf_date_1 | date | read only | Xf date 1 |
xf_date_2 | date | read only | Xf date 2 |
Errors
| Status | Meaning |
|---|---|
| 400 | The request could not be read: a filter that is not JSON, a bad parameter |
| 401 | No credential, or it is wrong, revoked or expired |
| 403 | The caller's roles do not hold Talent & Contingent Workforce › Contingent Candidates for this verb, or the address or origin is not allowed |
| 404 | No record with that id is visible to the caller |
| 409 | A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else |
| 422 | Refused by the same validation as the screen; the error names the field and why |
Every error is JSON: {"error": "a sentence saying what was wrong"}, with field where it applies.