- Update an existing Candidate
Updates an existing Candidate.
Attempts to update a field that cannot be updated will return a 400 error stating "... cannot be updated”. For example, attempting to update an SSN will return 400 stating "Candidate SSN can not be updated because it has reports”.
Updating geo_ids will replace all existing Geos. To keep existing geos, include their IDs in the update request. geo_ids cannot be updated if the candidate's work location is outside the US. Only fields with null values can be updated after a Report has been ordered for a Candidate with the exception of the following fields:
- phone
- previous_driver_license_number
- previous_driver_license_state
- copy_requested
- custom_id
- geo_ids
Updating metadata with an empty value (null or empty object) will delete existing metadata. Individual keys may also be set and unset.
- Adding a new key-value pair will maintain all existing key-value pairs.
- Providing a new value for an existing key will update the old value to the new value.
- Providing an empty value for an existing key will remove that key from the metadata object.
- When all keys in the metadata object have empty values, the object will be deleted.
Candidate’s first name.
Candidate’s middle name. This field is required if no_middle_name is false.
Required if no middle_name is provided. true if the candidate has no middle name.
Candidate’s mother’s maiden name.
Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.
Candidate’s driver license state of issue. Format: ISO 3166-2:US.
State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.
If true, the candidate has asked to receive a copy of their report.
Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.
The adjudication for the Candidate’s most recently created Report.
Candidate's postal address.
{ "name": "John Alfred Smith", "street": "123 Main Street", "street2": "APT A", "city": "San Francisco", "state": "CA", "zipcode": "94108" }
Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to job_req_id, application_id, or branch_id. Keys must be 40 characters or less. Values must be 500 characters or less. For example: { "job_req_id": "12345" }
- Mock serverhttps://docs.checkr.com/_mock/apis/openapi/candidates/{id}
- Staginghttps://api.checkr-staging.com/v1/candidates/{id}
curl -i -X POST \
-u '<username>:<password>' \
'https://docs.checkr.com/_mock/apis/openapi/candidates/{id}' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/v1/candidates/e44aa283528e6fde7d542194",
"first_name": "John",
"middle_name": "Alfred",
"no_middle_name": false,
"last_name": "Smith",
"mother_maiden_name": "Jones",
"email": "john.smith@gmail.com",
"phone": 5555555555,
"zipcode": 90401,
"dob": "1970-01-22",
"ssn": "XXX-XX-4645",
"driver_license_number": "F2111655",
"driver_license_state": "CA",
"previous_driver_license_number": "F1501739",
"previous_driver_license_state": "MD",
"copy_requested": false,
"custom_id": "string",
"geo_ids": [
"79f943e212cce7de21c054a8"
],
"adjudication": "engaged",
"postal_address": {
"name": "John Alfred Smith",
"street": "123 Main Street",
"street2": "APT A",
"city": "San Francisco",
"state": "CA",
"zipcode": "94108"
},
"metadata": {}
}'Candidate was successfully updated
URI of the resource.
Candidate’s first name.
Candidate’s middle name. This field is required if no_middle_name is false.
Required if no middle_name is provided. true if the candidate has no middle name.
Candidate’s mother’s maiden name.
Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.
Candidate’s driver license state of issue. Format: ISO 3166-2:US.
State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.
If true, the candidate has asked to receive a copy of their report.
Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.
The adjudication for the Candidate’s most recently created Report.
Candidate's postal address.
{ "name": "John Alfred Smith", "street": "123 Main Street", "street2": "APT A", "city": "San Francisco", "state": "CA", "zipcode": "94108" }
Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to job_req_id, application_id, or branch_id. Keys must be 40 characters or less. Values must be 500 characters or less. For example: { "job_req_id": "12345" }
{ "id": "e44aa283528e6fde7d542194", "object": "candidate", "uri": "/v1/candidates/e44aa283528e6fde7d542194", "first_name": "John", "middle_name": "Alfred", "no_middle_name": false, "last_name": "Smith", "mother_maiden_name": "Jones", "email": "john.smith@gmail.com", "phone": 5555555555, "zipcode": 90401, "dob": "1970-01-22", "ssn": "XXX-XX-4645", "driver_license_number": "F2111655", "driver_license_state": "CA", "previous_driver_license_number": "F1501739", "previous_driver_license_state": "MD", "copy_requested": false, "custom_id": "string", "report_ids": [ "532e71cfe88a1d4e8d00000d" ], "geo_ids": [ "79f943e212cce7de21c054a8" ], "adjudication": "engaged", "postal_address": { "name": "John Alfred Smith", "street": "123 Main Street", "street2": "APT A", "city": "San Francisco", "state": "CA", "zipcode": "94108" }, "metadata": {} }