{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"ee2531c6-69e1-4e09-9cef-992830303f8e","name":"Zinc Partner API","description":"Zinc partner API: A Rest API used to integrate the Zinc background checking service into partner systems. This API is intended to allow partners to start background check requests for mutual customers. The API allows partners to view packages created by the customer, start a background check request for a candidate and receive the results of the background check request.\n\n> All responses sent will use a JSON structure \n  \n\nPotential integration requests can be sent to [integrations@zincwork.com](https://mailto:integrations@zincwork.com).\n\n# Screening process\n\n- Start a new background check request via the `/checks` endpoint\n    \n- Please note that CV Check requires enablement by Zinc before use\n    \n- Zinc contacts the candidate using the contact information provided\n    \n- The candidate creates an account with Zinc and submits the required information to complete the requested background checks\n    \n- Zinc process the data and conducts the checks\n    \n- All updates in the process are returned in the `/results` endpoint or sent back to the webhook URL registered for that candidate\n    \n\n# Getting started\n\nContact the Zinc team to get access to our sandbox test environment and provision your development account to use for development and testing.\n\nIf the webhook approach is being used, the Zinc team will send the signing token to be used to authenticate API calls made to your API when a background check is complete.\n\nAPI keys can be created using the same sandbox account and can be used to start testing your integration.\n\nCV Check is an optional capability. To enable it, contact [integrations@zincwork.com](https://mailto:integrations@zincwork.com).\n\n# Authentication\n\nAll calls to the Partner API are authenticated by passing an API key in the Authorisation header. The API key used must be connected to a valid customer account on Zinc in order to associate the request with the customer account.  \nCustomers can create new API keys on the Zinc platform. API keys can be created [here](https://help.zincwork.com/article/a7ed573f-how-to-generate-an-api-key-for-your-ats?co%5B%E2%80%A6%5Dky7yrc&slug=a7ed573f-how-to-generate-an-api-key-for-your-ats). More detailed instructions can be found on the Zinc knowledge base.\n\nAuthentication is performed by passing the API key in the Authorization header.\n\n> You must replace API_KEY with your own API key. \n  \n\n```\nGET https://api.zincwork.com/partner/v2/packages HTTP/1.1\nAuthorization: Bearer API_KEY\n\n ```\n\nThe Zinc API uses the customer API key to authenticate API calls. Customers can create a new API key on the Zinc platform. [Manage your API keys.](https://zincwork.com/company/general)\n\n# Webhooks\n\nZinc supports webhooks for receiving updates about the results of background checks initiated through the Zinc Partner API. To use webhooks, follow these steps:\n\n1. Contact Zinc for a unique signing token to be used for verifying the webhook signature. See the section below titled **Verifying Webhook Signature** for more information.\n    \n2. Include callback URL in the request body of the `checks` endpoint (`resultsCallbackURL`).\n    \n\n**Verifying Webhook Signature**\n\nVerifying a webhook signature is a way to ensure that the data sent to your app is from a trusted source. This involves checking the signature sent with the webhook data against the signature your app has generated. If the signatures match, then the data is from a trusted source.\n\nTo compare signatures, you need a signing token that is unique to your application (ask Zinc to generate one for you) and the payload of the webhook. With these two pieces of information, you can use the HMAC-SHA256 cryptographic algorithm to calculate the signature. The calculated signature must match the signature sent in the webhook request's header. If they match, then you can be sure that the webhook was sent from the application that generated the signing token. Finally, you can safely process the webhook.\n\nTo verify our webhook signature in Node.js, use the following example:\n\n``` javascript\nconst crypto = require('crypto');\nconst signature = req.headers['x-zinc-webhook-signature'];\nconst expectedSignature = crypto.createHmac('sha256', 'YOUR-WEBHOOK-SIGNING-TOKEN').update(JSON.stringify(req.body)).digest('hex');\nif (signature !== expectedSignature) {\n  throw new Error('Signature does not match');\n}\n\n ```\n\n## Webhook Payload Overview\n\nZinc POSTs a signed JSON body to your `resultsCallbackURL` when a delivery is triggered for that request. Each payload includes `id`, a coarse `status`, and a granular `statusV2` aligned with Zinc’s request lifecycle. Use `statusV2` for precision and `status` for coarse handling. Allowed values and the mapping between them are listed below.\n\n### Understanding Webhook Status Fields\n\nEach webhook body includes two request-level status fields:\n\n- `status` - Coarse status for broad lifecycle grouping (same values you may already integrate against). Several internal states share the same `status`\n    \n- `statusV2` - Granular status aligned with Zinc’s internal request lifecycle. Use this when you need to distinguish states that share the same coarse `status` (for example, different kinds of “in progress” or who needs to act next)\n    \n\nYou should treat `statusV2` as the source of truth for the precise state, and `status` for coarse filtering or legacy logic.\n\nFour different `statusV2` values map to `pending`. If you only switch on `status`, you cannot tell them apart.\n\n| `statusV2` (granular) | `status` (coarse) |\n| --- | --- |\n| `requested` | `pending` |\n| `paused` | `pending` |\n| `awaiting-candidate` | `pending` |\n| `attention-needed` | `pending` |\n| `in-progress` | `partially-completed` |\n| `ready-for-review` | `action-required` |\n| `all-clear` | `completed` |\n| `reviewed` | `reviewed` |\n| `cancelled` | `cancelled` |\n\n### Webhook Payload Schema\n\nThe following JSON is an illustrative schema of the webhook body. Field presence depends on request state. `id`, `status`, and `statusV2` are always present.\n\n``` json\n{\n  \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n  \"status\": \"completed\",\n  \"statusV2\": \"all-clear\",\n  \"result\": \"clear\",\n  \"reportUrl\": \"https://…/candidate/<id>\",\n  \"checks\": [\n    {\n      \"name\": \"Address check for Jane Doe\",\n      \"status\": \"clear\",\n      \"checkType\": \"address-check\"\n    }\n  ]\n}\n\n ```\n\n### Payload Fields\n\nThe table below describes the top-level fields most commonly used in webhook payloads. Whether optional fields appear depends on coarse `status` and populated check data.\n\n| **Field** | **Type** | **Required** | **Description** |\n| --- | --- | --- | --- |\n| `id` | string | Yes | Unique background check request ID. |\n| `status` | string (enum) | Yes | Coarse lifecycle state. See mapping table above. |\n| `statusV2` | string (enum) | Yes | Granular request state. Use this to distinguish states that share the same status; see mapping table above. |\n| `result` | string (enum) | Conditional | Values: `clear` or `consider`. The final outcome of the request. Present only when `status` is `completed`, `reviewed`, or `action-required`. |\n| `reportUrl` | string | Conditional | Direct link to the full background check report. Present only once all checks are available (not for `pending` or `cancelled`). |\n| `checks` | array | Conditional | Array of individual checks with their statuses. Present only when request has progressed beyond `pending`. |\n\n### Coarse Request Status Values and Definitions\n\n| **Status** | **Description** |\n| --- | --- |\n| pending | Request is not finished; work is still in progress or waiting on someone (candidate, recruiter, or Zinc). |\n| partially-completed | At least one check has progressed, but the request is not in a final outcome state yet. |\n| action-required | Recruiter-side action is required before the request can continue (e.g. ready for review / manual step). |\n| reviewed | Request has been manually reviewed. |\n| completed | All checks are complete from a screening perspective. |\n| cancelled | Request was cancelled and will not complete. |\n\n### Granular Request Status Values and Definitions (`statusV2`)\n\n| statusV2 | Definition |\n| --- | --- |\n| `requested` | Request created; candidate has been notified. |\n| `paused` | Request is paused (progress intentionally stopped until resumed). |\n| `in-progress` | Candidate (or workflow) is actively progressing checks. |\n| `awaiting-candidate` | Candidate action is required before checks can continue. |\n| `attention-needed` | Recruiter action is required before checks can continue. |\n| `ready-for-review` | Screening outcome is ready for recruiter to review. |\n| `all-clear` | Checks have completed with an overall clear outcome. |\n| `reviewed` | Recruiter has completed review of the outcome. |\n| `cancelled` | Request has been cancelled. |\n\n### checks Array (per-check summary)\n\nWhen present, `checks` is an array of per-check summaries for the request. Each element describes one check (for example an address check or a reference).\n\n| **Field** | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | string | Yes | Human-readable label for the check (for example “Address check for Jane Doe”). |\n| `status` | enum | Yes | Outcome or progress for this check (for example clear, consider, pending). |\n| `type` | string | No | Machine-readable check discriminator (for example address-check, reference-check, right-to-work-check). |\n| `checkType` | string | No | Education checks only: finer category (for example degree, certificate). Omit for non-education checks. |\n\n## Example Webhook Events\n\n### 1\\. Initial delivery (request created)\n\n``` json\n{\n  \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n  \"status\": \"pending\",\n  \"statusV2\": \"requested\"\n}\n\n ```\n\n### 2\\. In progress update (some checks completed)\n\n``` json\n{\n  \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n  \"status\": \"partially-completed\",\n  \"statusV2\": \"in-progress\",\n  \"checks\": [\n    {\n      \"name\": \"Address check for Jane Doe\",\n      \"status\": \"clear\",\n      \"type\": \"address-check\"\n    },\n    {\n      \"name\": \"Reference from manager at Acme Ltd\",\n      \"status\": \"pending\",\n      \"type\": \"reference-check\"\n    }\n  ]\n}\n\n ```\n\n### 3\\. Final result (all checks complete)\n\n``` json\n{\n  \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n  \"status\": \"completed\",\n  \"statusV2\": \"all-clear\",\n  \"result\": \"clear\",\n  \"reportUrl\": \"https://app.zinc.work/candidate/a1b2c3d4e5f6789012345678901234ab\",\n  \"checks\": [\n    {\n      \"name\": \"Address check for Jane Doe\",\n      \"status\": \"clear\",\n      \"type\": \"address-check\"\n    },\n    {\n      \"name\": \"Right to work check for Jane Doe\",\n      \"status\": \"clear\",\n      \"type\": \"right-to-work-check\"\n    }\n  ]\n}\n\n ```\n\n### 4\\. After manual review (`reviewed`)\n\n``` json\n{\n  \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n  \"status\": \"reviewed\",\n  \"statusV2\": \"reviewed\",\n  \"result\": \"consider\",\n  \"reportUrl\": \"https://app.zinc.work/recruitment/request/req_123\",\n  \"checks\": [\n    {\n      \"name\": \"Address check for John Smith\",\n      \"status\": \"consider\",\n      \"type\": \"address-check\"\n    }\n  ]\n}\n\n ```\n\n### 5\\. Attention needed - action sits with the recruiter\n\nUse this when the request is blocked until someone on the hiring side (recruiter) does something. Coarse `status` stays `pending`; `statusV2` carries the precision.\n\n``` json\n{\n  \"id\": \"a1b2c3d4e5f6789012345678901234ab\",\n  \"status\": \"pending\",\n  \"statusV2\": \"attention-needed\"\n}\n\n ```\n\n### 6\\. Awaiting candidate — action sits with the candidate\n\nUse this when the request is blocked until the candidate completes a step (for example submitting information or continuing the flow). Coarse `status` stays `pending`; `statusV2` carries the precision.\n\n``` json\n{\n  \"id\": \"a1b2c3d4e5f6789012345678901234ab\",\n  \"status\": \"pending\",\n  \"statusV2\": \"awaiting-candidate\"\n}\n\n ```\n\n# Error Payloads\n\nError payloads from the Partner API follow the following pattern.\n\n| **Field** | **Type** | **Description** |\n| --- | --- | --- |\n| `statusCode` | `number` | Zinc specific error code. This is used to debug issues with the API. |\n| `message` | `string` | Message with more information about the error. |\n\n# Glossary\n\n**Check** - there are many different types of background checks - criminal checks, education checks, right-to-work (RTW) checks.\n\n**Candidate** - the person for whom the background checks are conducted on.\n\n**Package** - multiple checks can be grouped together into a single package. Every package has a name.\n\n**Request** - a request represents the actual running of the background checks on a candidate. Every request must be started from a package; thus the package's ID is required to start a request on any candidate.\n\n**API key** - This is the customer's secret API key. They can retrieve this on their company page within Zinc. This is used to authenticate the customer within our system. Please reach out to your Zinc contact for any support with this.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"44615268","team":602632,"collectionId":"ee2531c6-69e1-4e09-9cef-992830303f8e","publishedId":"2sB2qZF3RB","public":true,"publicUrl":"https://docs.zincwork.com","privateUrl":"https://go.postman.co/documentation/44615268-ee2531c6-69e1-4e09-9cef-992830303f8e","customColor":{"top-bar":"f8f4f0","right-sidebar":"303030","highlight":"00c7a4"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"00c7a4"}},{"name":"light","logo":null,"colors":{"top-bar":"f8f4f0","right-sidebar":"303030","highlight":"00c7a4"}}]}},"version":"8.10.1","publishDate":"2025-05-21T10:43:36.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/2ce3c45086ae9714c475df0e0bca75851bd3ae241067f072f68e974dfa5e25c8","favicon":"https://res.cloudinary.com/postman/image/upload/v1669152838/team/mx0ubotblpu9ayqfkxnc.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.zincwork.com/view/metadata/2sB2qZF3RB"}