Table of contents
Content Active
Content inactive

A background check API integration connects your ATS or HRMS to your verification provider, so a candidate's details flow across on their own, checks start without anyone retyping a form, and the status and final report come back into the system your HR team already lives in. With SpringVerify, that happens in one of two ways: a ready-made connector for tools like Keka, Darwinbox and Greenhouse, or our REST API, where your developer creates the candidate, sends consent, tracks status and pulls the report.

If you hire in India and verification still runs on spreadsheets and email, SpringVerify is built for exactly your problem: checks start from the HR tool you already use, and the report comes back to it. Below is how it works, what it takes, and which route fits you.

In summary

  • Check for a ready-made connector first. If your HR tool is one of the 100+ SpringVerify connects to, you can start checks from inside it with no API to build.
  • Build on the API when you need your own triggers or screens. SpringVerify's India API covers the whole journey in five calls: packages, add candidate, submit details, get status, get report.
  • Consent is a separate step, not a side effect. A case can be accepted and still sit at "Consent missing" until consent is in.
  • "Completed" does not mean "cleared". Read the report before you decide, and map status codes, not labels.
  • Test the messy cases in sandbox (missing consent, duplicate candidates, missed webhooks) before you switch to production.

What is a background check API integration?

A background check API integration is a link between your hiring software and your verification provider that lets the two systems talk without a person in the middle. An API (application programming interface) is simply a set of agreed requests one system can send another, like "add this candidate" or "what's the status of case 33447?".

Picture the week without one. A recruiter closes 30 offers. Someone copies each candidate's name, phone and joining date from the ATS into the verification portal. Every few days a hiring manager asks "is the BGV done?", and someone logs in, checks, and pastes the answer into an email. It's slow, and every copy-paste is a chance to mistype a PAN number.

With an integration, the offer approval in your ATS starts the check. The candidate gets a link, gives consent and uploads documents. The status updates itself in your HR tool, and the report lands next to the employee record.

What it does not do is speed up the checks themselves. A previous employer who takes a week to reply still takes a week. The integration removes the waiting around the checks: the data entry, the forwarding and the chasing.

hassle-free-bgv-get-started-now-banner-1

Do you need to build an API, or is there a ready-made integration?

Check for a ready-made connector first. If SpringVerify already connects to your ATS or HRMS, you install it and start checks from screens your team already uses, with no developer and no code. Build on the API only when no connector exists or you need behaviour a connector doesn't give you.

SpringVerify connects with 100+ HRIS, ATS and HRMS platforms, and our integrations page lists them by name, from Keka, Darwinbox, greytHR, Zoho Recruit and Zimyo to Greenhouse and Lever. Three of the most common:

Your HR toolHow checks startWhere results landDeveloper needed?
KekaPick SpringVerify and a package on Keka's onboarding screen, click Initiate. Keka documents pre-fill the candidate's formReport pushed back to Keka, opened with the Review buttonNo. The Keka page says it plainly: "No API to build"
DarwinboxFrom Recruitment (pre-offer), Onboarding (after acceptance), or bothInterim reports as each check completes; final report in the onboarding formNo. Your Darwinbox account team sets it up once
GreenhouseWhen an offer is approved or a candidate is hiredResults return to GreenhouseNo custom build: it uses the ready-made connector
Anything else, or your own platformWhenever your system calls our APIWherever your developer shows itYes, a developer builds and maintains it

So the honest answer to "do we need engineers?" is: not if you're on a supported tool, and yes if you're building your own flow. You want the API if you run your own hiring platform (a gig or staffing marketplace that onboards workers at sign-up, say), need a trigger only your system knows about, or want verification inside your own screens. Not sure which you are? The SpringVerify API integration page is the place to start, and our team can tell you in one call.

How does a background check API integration work, step by step?

SpringVerify's India API follows five steps: read your configuration, create the candidate, submit their details, track status, then download the report. It's a REST API that sends and receives JSON (a plain-text data format), with standard HTTP response codes, and the full reference is public in our India BGV API documentation.

StepCallWhat it does for you
1GET /external/v1/candidate/packagesTells your system which packages, required fields, tags and consent model your company has
2POST /external/v1/candidate/addCreates the candidate and returns a candidate_id. The case starts at Awaiting Input
3POST /external/v2/candidate/submit-bgvSends the candidate's identity, employment, education and address details and documents (skip this if the candidate fills the form)
4GET /external/v1/candidate/detailsReturns the overall status and each check's status
5GET /external/v1/candidate/report/pdfDownloads the finished report

Webhooks sit alongside step 4: instead of your system asking, we tell it when a case finishes. If you're in HR, read the prose below and hand the code blocks to your tech team.

How do you authenticate with the SpringVerify API?

Every request carries a bearer token in its Authorization header. The token identifies your company, so you never send a company ID, and no IP allow-listing is needed. Ask your SpringVerify contact for a sandbox host and token to start.

EnvironmentHost
Sandbox (testing)https://api-acceptance-2-sa.in.springverify.com
Production (live)https://api-sa.in.springverify.com

Your developer's first call reads your setup:

bashcurl --request GET \ 'https://api-acceptance-2-sa.in.springverify.com/external/v1/candidate/packages' \ --header 'Authorization: Bearer <YOUR_SANDBOX_TOKEN>' \ --header 'Content-Type: application/json'

The response lists every package your company can order (each with a subtype_id and a config block saying exactly what it checks), the required_fields your account insists on, your tags and custom fields, and your consent_type.

Two rules save a lot of grief later. The token is long-lived, so keep it on your server, never in browser code or a shared sheet. And a token belongs to one environment: package, tag and custom-field IDs differ between sandbox and production, so when you go live, switch the host and the token, then read your packages again. Never copy IDs across.

How do you create a candidate and start the checks?

Send POST /external/v1/candidate/add with the candidate's details and the subtype_id of the package you want. You get back a candidate_id to store against the record in your ATS. The one big choice is who fills in the verification form.

  • "invite": true: the candidate gets our form and fills it in themselves. Email is required on this path. This is the easiest start, and it suits most HR teams.
  • "invite": false: your system already holds the details and documents and sends them with the submit call. This is the usual path for a deep integration.

Here's an invitation-path request. The subtype_id and contact details are placeholders; use the values from your own packages call.

json{ "candidate": { "name": "Test Candidate", "email": "test.candidate@example.com", "phone": "<10-digit Indian mobile, no +91>", "employee_id": "ATS-1042", "invite": true, "meta_data": { "requisition_id": "REQ-1042", "source": "ats" } }, "package": { "subtype_id": <SUBTYPE_ID_FROM_PACKAGES> }}

The meta_data object is yours to use. We store it and echo it back on the details call and in webhooks, so your system can match every update to the right requisition without a lookup.

On the submit path, your developer sends POST /external/v2/candidate/submit-bgv with keyed sections like identity.identity_1, employment.employment_1 and address.current, with documents as hosted URLs or inline base64. Court checks are built from the addresses you submit. The contract is strict on purpose: an unknown field is rejected, every error comes back at once naming the exact field, and nothing is saved unless the whole payload passes. That strictness keeps bad data out of your reports.

One thing to know before you build: the add call is not idempotent. That means sending it twice can create a problem rather than being harmlessly ignored. A repeat of the same email, phone or employee ID returns 409, so store the candidate_id the first time, and after a timeout, check whether the case exists before you send it again.

How is candidate consent handled in an API integration?

Consent is its own step, and your integration has to treat it that way. Your packages response tells you which of two consent models your company uses, and that decides what you send. A submission can be accepted and still be held at Consent missing (overall_status_code 11) until consent is supplied.

Your consent_typeWhat your system sendsWhat HR should keep
CONSENT_LETTERA URL to the candidate's signed consent document, as candidate.consent on add or consent.doc_url on submitEvidence of what the candidate agreed to, and when
UNDERTAKING_LETTERis_consent_undertaking_letter: true on add, with one company-wide undertaking on fileYour own record of how candidates were informed and agreed

The consent document is the one file that is URL-only; it has no base64 option. If you can't host it safely, ask us to move your company to the undertaking model.

Why this matters beyond the API: India's Digital Personal Data Protection Act, 2023 makes consent and notice central to processing personal data. Under the government's notification G.S.R. 843(E), dated 13 November 2025, the core provisions, including the consent and notice duties, apply eighteen months after publication, which is 13 May 2027. An integration that records consent cleanly now is one less thing to fix then. For a specific case, take legal advice.

How do you track status: polling or webhooks?

Use both. Webhooks tell you when a case finishes, and a regular status check through the details endpoint catches anything a webhook missed. To ask for status, your developer calls:

bashcurl --request GET \ 'https://api-acceptance-2-sa.in.springverify.com/external/v1/candidate/details?candidate_id=<CANDIDATE_ID>&include_check_status=1' \ --header 'Authorization: Bearer <YOUR_SANDBOX_TOKEN>'

Map the numeric codes, never the display labels. Each overall status should mean something specific to HR:

CodeStatusWhat your HR tool should do
0, 4In progress, ProcessingShow "verification underway"
3Awaiting InputShow what the candidate still needs to submit
11Consent missingSend it to whoever owns consent
9On HoldAssign someone to resolve it
12Insufficient fundsSend it to your account owner, not the candidate
1CompletedOpen the report for review
6Completed with exceptionFlag for a reviewer before any decision
8, 10Closed, CancelledRecord the outcome; don't mark as cleared

A case is finished at 1, 6, 8 or 10. Those codes tell your system to stop polling. They don't all mean the candidate passed. Each check also has its own status, such as Verified, Unable to Verify, Insufficiency, Inconclusive, or Minor and Major Discrepancy, and those are what a reviewer reads.

Webhooks. When a case reaches a final status, we can POST to your system. Setup is on our side: you send us your callback URL, the authentication you want (basic, bearer, an API-key header or an HMAC signature over the raw body, sent by default in X-SpringVerify-Signature) and any static headers, and we configure it. The payload looks like this (shortened):

json{ "event": "completed", "candidate_id": 33447, "overall_status": "Completed", "overall_status_code": 1, "employee_id": "EMP-1001", "report_url": "<signed link that expires>", "completed_date": "2026-07-29T11:04:22.000Z", "meta_data": { "requisition_id": "REQ-1" }}

Four rules from our documentation keep this reliable:

  1. Reply 200, 201, 202 or 204. Anything else is retried on the next cycle.
  2. Never answer 401 or 403 for a temporary glitch. Those responses disable your endpoint until setup is run again.
  3. Make processing idempotent. Key on candidate_id plus overall_status_code, so a repeat delivery doesn't trigger a repeat action.
  4. Download the report promptly. The report_url is a signed link that expires, so save the file to your approved storage rather than keeping the link.

Pushes are batched on a schedule rather than fired the instant a status changes, so run a periodic sweep against the details endpoint as a safety net. Once a case is final, GET /external/v1/candidate/report/pdf?candidate_id=<CANDIDATE_ID> returns the PDF, or base64 JSON if you add report_type=base_64.

How long does a background check API integration take?

With a ready-made connector, setup is closer to an install than a project: Keka is installed from its marketplace, and Darwinbox is set up once with your Darwinbox account team. A custom API build depends on your developer, your stack and how much you show inside your own screens, so scope it with your tech team rather than trusting anyone's headline number.

The bigger question is usually how fast the checks finish once they start, because that's what your joining dates hang on. These are SpringVerify's published figures:

WhatPublished figureSource
Basic checksUnder 60 secondsSpringVerify homepage (3 Nov 2026)
All verifications80% completed within 48 hoursSpringVerify homepage (3 Nov 2026)
Employment verificationMost take 5 to 6 working days, depending on how quickly past employers' HR respondsEmployment verification page
Digital address verificationUsually 24 to 48 hoursAddress verification page
Official university verificationTypically 15 to 90 daysEducation verification page

An integration makes those clocks start the minute an offer is approved, instead of whenever someone gets round to the portal. If you want the wider case for taking the manual steps out, read our guide to background screening automation.

What should HR and engineering test before going live?

Test the awkward journeys, not just the happy one. A clean candidate who sails through proves very little. Run these in sandbox with HR and your developer in the same room:

TestWhat good looks like
Wrong or expired tokenA 401 your tech owner sees straight away
Missing required fieldThe 400 names the field, and it's fixed before resending
Same candidate added twiceThe 409 is matched to the existing case, not a new one
No consent suppliedHR sees "Consent missing", not "verification started"
Document URL that doesn't loadThe failure shows up and gets corrected
Webhook delivered twiceNothing happens twice
Webhook never arrivesThe status sweep catches the final result
Completed with exceptionA reviewer sees the exception before any hiring decision
Switch to productionNew host, new token, packages read again

400, 401, 404, 409, 413 and 422 should never be retried unchanged. 429 and 5xx errors are temporary, so retry them with backoff. Keep tokens, identity documents, consent files and reports out of ordinary application logs.

Why HR teams choose SpringVerify for API integration

HR teams pick SpringVerify because verification stops being a side job for someone on the team. The proof:

Your team stops retyping candidate data. Start checks from Keka, Darwinbox, Greenhouse or 100+ other HR platforms, or from your own system through the API. On Keka, the documents already on file pre-fill the candidate's form, so candidates only complete what's missing.

You stop chasing status by email. Statuses flow back to your HR tool, and on Darwinbox, interim reports arrive as each check completes. Sameer Wahie, Founder of Swageazy, put it this way on our customer stories page: "Everything is digital and automated. But I still get up-to-date progress on every candidate verification without contacting a representative."

Offers turn into joining dates faster. On top of the published turnarounds above, our customer stories page shows HackerEarth reports 94% of checks completed within two weeks, OnJuno 93%, Sprinto 88.36% and Blue Ridge Global 86%, and MobStac's story is headlined "MobStac leveraged SpringVerify to reduce hiring time by 50%".

Your developer builds against a clear contract. One token, a sandbox, five documented calls, and the edge cases written down before you hit them.

Every check through one integration. 20+ background checks, from ID, address, employment and education to court records and police clearance certificates, so you aren't wiring up a vendor per check.

Candidate data stays protected. SpringVerify holds ISO/IEC 27001:2022 and SOC 2 Type II certification, listed on our security page.

And it's simple for the people using it. Asmita P, Senior HR Generalist at HackerEarth, wrote in a G2 review shown on our site: "All you have to do is add the candidate and it takes care of the rest. From running checks to real-time updates, flags, and reminders - SpringVerify does the job like a breeze."

Is SpringVerify right for your API integration?

SpringVerify is a strong fit if you hire in India, want checks to start from your ATS or HRMS, and want the status and report back in that same tool. It suits you especially well if you're on a supported platform such as Keka, Darwinbox or Greenhouse, or if you have a developer who can build against a documented REST API.

Not the right fit if:

  • You want a custom-built flow but have no one to own it. An API integration needs a developer to build it and someone to maintain it. If that's you, use a ready-made connector or our dashboard instead.
  • You need a push for every small status change. Our webhooks fire on final statuses, batched on a schedule. Intermediate updates come from the details call.
  • You expect the API to make past employers reply faster. It removes your delays, not theirs. Employment checks still mostly take 5 to 6 working days.
  • You're screening tenants or checking yourself as a consumer. SpringVerify is built for employers.

Frequently asked questions

Do I need a developer to integrate background checks with my HRMS?

Not if your HRMS has a ready-made SpringVerify connector, such as Keka or Darwinbox; you install it and start checks from your usual screens. A custom API integration does need a developer to build and maintain it.

Can candidates fill in their own verification form?

Yes. Create the candidate with "invite": true and they get SpringVerify's form to complete themselves. Email is required on that path. Use "invite": false if your system sends their details instead.

Are SpringVerify webhooks real-time?

They are scheduled, not instant. When a case reaches a final status, we push it to your endpoint on the next batch. Pair webhooks with a periodic status check through the details endpoint.

Does a "Completed" status mean the candidate is cleared?

No. Completed means the case has finished. Your reviewer still reads the report and each check's result, and Completed with exception, Closed and Cancelled are final too. The hiring decision stays with you.

Is there a sandbox for testing?

Yes. SpringVerify gives you a sandbox host and token. Package and field IDs differ in production, so read your packages again when you go live.

SV-BGV-get-started-now-banner

What's the next step?

Bring three things to a call with us: the name of your ATS or HRMS, the hiring stage where you want checks to start, and the checks each role needs. We'll tell you whether a ready-made connector covers it or the API is the better route, and walk a sandbox candidate from creation to final report with your HR and tech leads watching. Book your SpringVerify demo.

Hire with Confidence
Verify candidates in 24–72 hours
Ready to Hire With Confidence?
See how candidate data flows seamlessly and verification starts instantly with SpringVerify.
Schedule a Demo