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\nAll responses sent will use a JSON structure
\n
Potential integration requests can be sent to integrations@zincwork.com.
\nStart a new background check request via the /checks endpoint
Please note that CV Check requires enablement by Zinc before use
\nZinc contacts the candidate using the contact information provided
\nThe candidate creates an account with Zinc and submits the required information to complete the requested background checks
\nZinc process the data and conducts the checks
\nAll updates in the process are returned in the /results endpoint or sent back to the webhook URL registered for that candidate
Contact the Zinc team to get access to our sandbox test environment and provision your development account to use for development and testing.
\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.
\nAPI keys can be created using the same sandbox account and can be used to start testing your integration.
\nCV Check is an optional capability. To enable it, contact integrations@zincwork.com.
\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.
Customers can create new API keys on the Zinc platform. API keys can be created here. More detailed instructions can be found on the Zinc knowledge base.
Authentication is performed by passing the API key in the Authorization header.
\n\n\nYou must replace API_KEY with your own API key.
\n
GET https://api.zincwork.com/partner/v2/packages HTTP/1.1\nAuthorization: Bearer API_KEY\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.
\nZinc supports webhooks for receiving updates about the results of background checks initiated through the Zinc Partner API. To use webhooks, follow these steps:
\nContact 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.
\nInclude callback URL in the request body of the checks endpoint (resultsCallbackURL).
Verifying Webhook Signature
\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.
\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.
\nTo verify our webhook signature in Node.js, use the following example:
\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\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.
Each webhook body includes two request-level status fields:
\nstatus - Coarse status for broad lifecycle grouping (same values you may already integrate against). Several internal states share the same status
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)
You should treat statusV2 as the source of truth for the precise state, and status for coarse filtering or legacy logic.
Four different statusV2 values map to pending. If you only switch on status, you cannot tell them apart.
The following JSON is an illustrative schema of the webhook body. Field presence depends on request state. id, status, and statusV2 are always present.
{\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\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.
statusV2)When 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 \"id\": \"BACKGROUND_CHECK_REQUEST_ID\",\n \"status\": \"pending\",\n \"statusV2\": \"requested\"\n}\n\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 \"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\nreviewed){\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\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 \"id\": \"a1b2c3d4e5f6789012345678901234ab\",\n \"status\": \"pending\",\n \"statusV2\": \"attention-needed\"\n}\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 \"id\": \"a1b2c3d4e5f6789012345678901234ab\",\n \"status\": \"pending\",\n \"statusV2\": \"awaiting-candidate\"\n}\n\nError payloads from the Partner API follow the following pattern.
\nCheck - there are many different types of background checks - criminal checks, education checks, right-to-work (RTW) checks.
\nCandidate - the person for whom the background checks are conducted on.
\nPackage - multiple checks can be grouped together into a single package. Every package has a name.
\nRequest - 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.
\nAPI 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.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Screening process","slug":"screening-process"},{"content":"Getting started","slug":"getting-started"},{"content":"Authentication","slug":"authentication"},{"content":"Webhooks","slug":"webhooks"},{"content":"Error Payloads","slug":"error-payloads"},{"content":"Glossary","slug":"glossary"}],"owner":"44615268","collectionId":"ee2531c6-69e1-4e09-9cef-992830303f8e","publishedId":"2sB2qZF3RB","public":true,"customColor":{"top-bar":"f8f4f0","right-sidebar":"303030","highlight":"00c7a4"},"publishDate":"2025-05-21T10:43:36.000Z"},"item":[{"name":"Packages","id":"7369cc4b-0cad-4b3d-8f94-a5b36504b63c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":"https://api.zincwork.com/partner/v2/packages","description":"Returns a list of customer packages.
\nEach package contains a unique ID, the name of the package, and an includesCvCheck field indicating whether the package includes a CV check.
Error codes
\n","urlObject":{"protocol":"https","path":["partner","v2","packages"],"host":["api","zincwork","com"],"query":[],"variable":[]}},"response":[{"id":"34b0a7fc-0e73-49e7-a8e0-267ceb77a711","name":"Packages","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":"https://api.zincwork.com/partner/v2/packages"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": \"PACKAGE_ID_1\",\n \"name\": \"References only\"\n },\n {\n \"id\": \"PACKAGE_ID_2\",\n \"name\": \"Criminal check\"\n },\n {\n \"id\": \"PACKAGE_ID_3\",\n \"name\": \"Financial services\"\n }\n]"}],"_postman_id":"7369cc4b-0cad-4b3d-8f94-a5b36504b63c"},{"name":"Checks (pre-configured package)","id":"00c59705-9ee2-432f-a973-c3a514c0674c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"body":{"mode":"raw","raw":"{\n \"candidate\": {\n \"email\": \"test@zincwork.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Smith\"\n },\n \"package\": \"PACKAGE_ID\"\n\n}","options":{"raw":{"language":"json"}}},"url":"https://api.zincwork.com/partner/v2/checks","description":"POST endpoint to start background check requests with an exisiting pre-configured package in Zinc
\nRequest payload
\nResponse payload
\nError codes
\nVerifying webhook signature
\nZinc signs its requests to your system with a unique signing token and the request payload. You can access the webhook signature via the x-zinc-webhook-signature header. To receive your token, kindly reach out to Zinc. Please note that it is crucial to maintain the confidentiality of this token within your system.
POST endpoint to start background check requests with Zinc with no pre-configured package
\nRequest payload
\nPackage specification
\nTo create a Request without needing a pre-configured package, a package specification can be used instead. All fields in the package specification are optional, but at least one check type must be enabled (with a true value).
Response payload
\nError codes
\nVerifying webhook signature
\nZinc signs its requests to your system with a unique signing token and the request payload. You can access the webhook signature via the x-zinc-webhook-signature header. To receive your token, kindly reach out to Zinc. Please note that it is crucial to maintain the confidentiality of this token within your system.
Returns current status and results of a background check request
\nQuery Parameters
\nResponse payload
\nCheck result
\nError codes
\n","urlObject":{"protocol":"https","path":["partner","v2","results"],"host":["api","zincwork","com"],"query":[{"key":"id","value":"REQUEST_ID"}],"variable":[]}},"response":[{"id":"c2379010-a62c-4bd8-b896-c117c523fabd","name":"Completed Request","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/results?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","results"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"id\": \"REQUEST_ID\",\n \"status\": \"completed\",\n \"result\": \"clear\",\n \"reportUrl\": \"https://app.zincwork.com/candidate/REPORT_ID\",\n \"checks\": [\n {\n \"name\": \"Criminal check in England & Wales\",\n \"type\": \"criminal-check\",\n \"status\": \"consider\"\n },\n {\n \"name\": \"Reference from Senior Developer at Google\",\n \"type\": \"reference-check\",\n \"status\": \"clear\"\n },\n {\n \"name\": \"Qualification check (Academic) from University of Portugal\",\n \"type\": \"education-check\",\n \"status\": \"clear\"\n }\n ]\n}"},{"id":"e08f48e1-5a27-4fc3-990a-97dc4a8c53cc","name":"Not started Request","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/results?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","results"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"id\": \"REQUEST_ID\",\n \"status\": \"not-started\"\n}"},{"id":"933633af-2c3e-49d8-bf5b-88bff2789bc0","name":"Pending Request","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/results?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","results"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"id\": \"REQUEST_ID\",\n \"status\": \"pending\"\n}"}],"_postman_id":"22cbd887-4a39-43b7-80a6-d7bd49dec324"},{"name":"Report","id":"924fa2d1-dca4-4c24-9815-952c86b775c9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":"https://api.zincwork.com/partner/v2/report?id=REQUEST_ID","description":"Returns the PDF report of the completed background check. Result is sent back in Base64 format.
\nQuery Parameters
\nResponse payload
\nError codes
\n","urlObject":{"protocol":"https","path":["partner","v2","report"],"host":["api","zincwork","com"],"query":[{"key":"id","value":"REQUEST_ID"}],"variable":[]}},"response":[{"id":"374e5fc2-0a48-46e3-b3b1-6ba46a24ce7f","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/report?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","report"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"base64data\": \"xxxxx\",\n \"filename\": \"John-Smith-report.pdf\"\n}"},{"id":"b2b64314-4e1d-4db8-b9fc-57788581b25e","name":"Not found","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/report?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","report"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"base64data\": \"xxxxx\",\n \"filename\": \"John-Smith-report.pdf\"\n}"}],"_postman_id":"924fa2d1-dca4-4c24-9815-952c86b775c9"},{"name":"Cancel Request","id":"98b3fb6a-bbf0-4590-8d5e-31659c0a3357","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{API_KEY}}","type":"text"}],"url":"https://api.zincwork.com/partner/v2/delete?id={{REQUEST_ID}}","description":"Cancels a background check request created via Partner API. When a request is cancelled, its status is updated to cancelled and all associated references are cancelled. If a resultsCallbackURL was provided in the POST /checks request, a webhook notification will be sent to that URL with the updated status.
API Key via Bearer token
\nStatus: 204 No Content
The Search endpoint lets you look up background check requests by candidate email(s) or by request ID. Results are limited to the company linked to your API key.
\nSend your Partner API key as a Bearer token in the Authorization header:
\nAuthorization: Bearer API_KEY
Method: GETSend exactly one of:
\nYou must provide either emails or id, but not both.
\nGET https://api.zincwork.com/partner/v2/search?emails=jane.doe@example.com,other@example.com
\nGET https://api.zincwork.com/partner/v2/search?id=a1b2c3d4e5f6789012345678abcdef01
\nOn success the API returns 200 OK with a JSON body.
Each element of results is one matching request with full details (candidate, checks, metadata, report URL). When searching by emails, if no requests match, the API still returns 200 with \"results\": []. When searching by id, if the request is not found or you do not have access, the API returns an error (see Error codes below).
\nCheck types include: reference-check, criminal-check, education-check, address-check, adverse-media-check, document-check, financial-check, pep-check, right-to-work-check, sanctions-check, credit-check, self-certification-check, directorship-check, social-media-check, fca-check, cifas-check, cv-check.
\nErrors use the same structure as other Partner API endpoints:
\nNote: When searching by emails, no matches return 200 with \"results\": []. 404 is only used when searching by id and the request is not found or not accessible.
\n","urlObject":{"protocol":"https","path":["partner","v2","search"],"host":["api","zincwork","com"],"query":[{"key":"emails","value":"jane.doe@example.com,other@example.com"}],"variable":[]}},"response":[{"id":"92d9e84e-e629-409a-87dd-9e2703612184","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/search?emails=jane.doe@example.com,other@example.com","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","search"],"query":[{"key":"emails","value":"jane.doe@example.com,other@example.com"}]}},"status":"No Content","code":204,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"results\": [\n {\n \"id\": \"a1b2c3d4e5f6789012345678abcdef01\",\n \"status\": \"completed\",\n \"statusV2\": \"all-clear\",\n \"result\": \"clear\",\n \"reportUrl\": \"https://app.zincwork.com/candidate/a1b2c3d4e5f6789012345678abcdef01\",\n \"metadata\": {\n \"package\": {\n \"id\": \"a1b2c3d4e5f6789012345678abcdef02\",\n \"name\": \"DBS Enhanced\"\n },\n \"recruiter\": {\n \"id\": \"a1b2c3d4e5f6789012345678abcdef03\",\n \"email\": \"recruiter@example.com\"\n }\n },\n \"candidate\": {\n \"id\": \"a1b2c3d4e5f6789012345678abcdef04\",\n \"email\": \"jane.doe@example.com\",\n \"previousEmail\": \"jane.doe.previous@example.com\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\"\n },\n \"checks\": [\n {\n \"type\": \"criminal-check\",\n \"status\": \"completed\",\n \"name\": \"Criminal check in England & Wales\",\n \"report\": {\n \"country\": \"England & Wales\",\n \"completedAt\": \"2024-06-15T11:29:00.000Z\",\n \"checkCode\": \"00123456\",\n \"dbsLevel\": \"enhanced\"\n }\n },\n {\n \"type\": \"address-check\",\n \"status\": \"completed\",\n \"name\": \"Address check for Jane Doe\"\n },\n {\n \"type\": \"right-to-work-check\",\n \"status\": \"completed\",\n \"name\": \"Right to work check for Jane Doe\",\n \"report\": {\n \"documentType\": \"passport\",\n \"expiryDate\": \"2025-12-31\",\n \"shareCode\": \"ABC123XY\",\n \"nationality\": \"GB\",\n \"details\": \"British citizen - indefinite leave\",\n \"conditions\": \"No restrictions on work\",\n \"restrictions\": null\n }\n }\n ]\n }\n ]\n}"},{"id":"495d4667-5780-4d2b-bf4d-bc8efa8670af","name":"Not found","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer API_KEY","type":"text"}],"url":{"raw":"https://api.zincwork.com/partner/v2/report?id=REQUEST_ID","protocol":"https","host":["api","zincwork","com"],"path":["partner","v2","report"],"query":[{"key":"id","value":"REQUEST_ID"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"a02aaccc-5b46-40ee-a5f3-c5e1ebae0098"},{"name":"Mark Request as Reviewed","id":"79f8da71-8cbb-4b07-85be-6e147048cca7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer API_KEY"}],"body":{"mode":"raw","raw":"{\n \"id\": \"REQUEST_ID\"\n}"},"url":"https://api.zincwork.com/partner/v2/request/reviewed","description":"Mark Request as Reviewed
\nhttps://api.zincwork.com/partner/v2/request/reviewed
Updates the status of a background check request from action-required to reviewed.
This endpoint is available in both Partner API v1 and v2.
This endpoint requires Bearer token authentication using your API key.
\nAuthorization: Bearer API_KEY
curl --location 'https://api.zincwork.com/partner/v2/request/reviewed' \n--header 'Authorization: Bearer API_KEY' \n--header 'Content-Type: application/json' \n--data-raw '{\n \"id\": \"abcd1234\"\n}'\n\n{\n\"id\": \"your-request-id\"\n}\n\n{\n \"message\": \"Status updated to reviewed\"\n}\n\n