Overview
To retrieve a list of candidate GUIDs in a given specified date range criteria based on one of the three events, created, updated or deleted. Once the list of GUIDs that match the criteria is returned, subsequent calls to Match APIs - Fetch (Multiple) Candidate details by GUID (REST, JSON) can get one or more full candidate details.
Prerequisites
- Feature, track_candidate_last_changes, is required to track Updates and Deletes
- Modules
- Source&CRM - ON
- Privileges
- Source&CRM - API User
- OAUTH token following the Authorization call
Path
https://api.talemetry.com/match/v1/people/ids
Request Header
| Key | Value |
| Authorization | your token prefixed with OAUTH, e.g.,
OAUTH TGC-1733155440r2C2BC952A8F9A34CF9 |
| Accept | application/json |
Request Parameters
| Field | Type | Required | Description | Sample Value |
| DateTimeRange | No | The From, To, and Event fields must be specified if included. | ||
| From | DateTime | Yes* | Start of the date range. Supports ISO 8601 date format. |
2011-08-29T17:00:00Z
|
| To | DateTime | Yes* |
End of the date range. Supports ISO 8601 date format. You must specify at least one of From and To. |
2025-05-05T16:25:19Z
|
| Event | string | Yes* |
Describes the event that happened to the candidate in the specified date range. Supported event: created, updated, or deleted. The feature track_candidate_last_changes must be on to start tracking updated and deleted events. The following updates to the candidate's data are tracked: contacts, experience, education, job applications, consent, profile added, resume updated, audience type changes, lifecycle changed, tag (added or removed), note (added, updated, or removed), custom or standard field (added, updated, or removed) |
created
updated deleted
|
| ExcludeSources | array | No |
This allows you to exclude candidates with a profile from any specified source. The check is performed on all candidate profiles and is not limited to the primary source. Accepts profile source value codes used in CRM |
peoplesoft_ats talent_community |
| ExcludeLifeCycles | array | No |
Allows to exclude candidates with a specified Life Cycle state. Accepts Life Cycle value codes configured in CRM |
current_contingent |
| PageSize | Number | No [Default=100, Supported 1 to 100] |
Pagination results on page. |
1 |
| Cursor | Yes, if more than one page of results is produced |
If the request produces more results than the page size, the <Cursor> field is included in the response. The cursor should be included in the next request to get the next page of results. |
9027dea-4f36-11ef-87e6-e26115c7a29
|
Sample Request
{
"GetCandidateIds": {
"DateTimeRange": {
"From": "2011-08-29T17:00:00Z",
"To": "2025-05-05T16:25:19Z",
"Event": "created"
},
"ExcludeSources": ["peoplesoft", "hiredesk"],
"ExcludeLifeCycles": ["current_contingent", "current_employee"],
"PageSize": "1"
"Cursor": "90272dea-4f36-11ef-87e6-e26b115c7a29"
}
}
Sample Response: Created or Deleted (Success)
A successful response returns a JSON object containing the result and a list of candidates:
{
"result": {
"message": "OK",
"Candidates": [
{
"guid": "0290bb50-7113-11ef-9c70-b6a35a531041"
},
{
"guid": "02929ef4-8bce-11ef-b7ce-b24f8d2e4b83"
},
{
"guid": "02a2867e-8bd4-11ef-8d67-6e6c098cfdc9"
},
{
"guid": "02ac422c-7121-11ef-9c70-b6a35a531041"
},
{
"guid": "0547f9c0-7056-11ef-a9b7-eae6e862e267"
}
],
"Cursor": "0547f9c0-7056-11ef-a9b7-eae6e862e267"
}
}
Sample Response: Updated (Success)
A successful response returns a JSON object containing the result, a list of candidates, and a list of the tracked changes:
{
"result": {
"message": "OK",
"Candidates": [
{
"guid": "902b3f8e-8bd6-11ef-b7ce-b24f8d2e4b83",
"changes": [
"details",
"resume",
"lifecycle",
"audience",
"tag"
]
},
{
"guid": "902f4bfe-8bdd-11ef-b7ce-b24f8d2e4b83",
"changes": [
"details",
"resume",
"lifecycle",
"custom_field"
]
},
{
"guid": "93eb488a-8bd6-11ef-b7ce-b24f8d2e4b83",
"changes": [
"details",
"lifecycle",
"audience",
"note"
]
}
],
"Cursor": "93eb488a-8bd6-11ef-b7ce-b24f8d2e4b83"
}
}
Changes Include:
-
details- Material update to the candidate’s data, i.e. changes to the contacts, work and education history, consent, job applications, new profile added -
resume- Primary resume updated -
lifecycle- Lifecycle State updated -
audience- Audience Type updated -
tag- Tags are updated -
note- Notes are updated -
custom_field- Custom or standard fields are updated