Background check API for platforms, staffing agencies and small businesses
Order screening from the system you already use, and get status updates and finished reports sent straight back to it.
Short answer
Can our platform order background checks directly through an API?
Yes. SafestHires accepts background check orders sent as XML over HTTPS straight from your own platform, applicant tracking system or app — no webhook needs to be built first. Add the optional postBackInfo block to each order (Order Entry manual, section 3.5) and status updates and finished results are posted to the web address you choose. You can also pull results for any order by its order number. Both manuals are free to download, and there are no integration or platform fees.
How the API works, in three steps
- Send the order. Your system posts an XML order over HTTPS. Each post can carry 1 to 50 orders, though one order per post makes errors easier to find.
- Tell us where to send updates. Add the optional postBackInfo block (section 3.5) with your web address and an ID. Basic or token sign-in is supported for the address you give us.
- Receive or pull results. Status and results are posted back as XML, or a PDF of the completed report. You can also pull results for an order by its order number.
Choose which updates you receive
With postBackInfo you pick the updates you want. Leave the choice out and you receive all of them. Options include:
- Each search finishing (ICR)
- The whole order finishing (OCR)
- Waiting on the candidate (IPC), or the candidate's invitation expiring (EXP)
- The order being cancelled or deleted (DEL)
- A PDF of the completed report only (PDF)
Who uses it
Platforms that hire independent contractors
Marketplaces and gig apps can start a check the moment a contractor signs up, invite the contractor by text or email to add their own details, and update the contractor's profile when the order finishes. See our contractor background check guides.
Who pays the initial and later charges?
The contractor pays the package and applicable initial court access fees when placing the order. Later county-court verification of records revealed by the Nationwide Criminal Database Search, plus applicable access fees for that verification, is billed monthly to the requesting organization. We cannot charge the contractor’s card a second time.
For planning, SafestHires estimates that about 5% of orders reveal a record in the Nationwide Criminal Database Search—about five orders in 100 on average. This is a company estimate, not a guaranteed rate; an order can reveal more than one record.
Tell contractors about possible initial court access fees before payment. Fees vary by jurisdiction and can reach $100 in the published county schedule. Use the access-fee lookup for the places being searched; later verification access fees are paid by the organization.
Estimate both sides with the contractor screening cost planner and explore the contractor onboarding workflow map. Service prices come from the pricing calculator; jurisdiction fees come from the access-fee lookup. Confirm your per-record verification price in a written quote.
Companies that hire drivers
Driver checks such as motor vehicle records, commercial driver's license verification and FMCSA crash and inspection history can be ordered through the same connection, along with drug screens. See our transportation screening page.
Staffing agencies
Agencies can order from inside the candidate record and, with the right permissions, place orders on behalf of separate client accounts using the order_on_behalf_of block (section 3.4). See our staffing screening page.
Small businesses
Most small businesses do not need the API — they order on our website or through one of the 70+ ready-made integrations. If you run your own hiring software, the API is available at no extra cost. See small business background checks.
Download the manuals
Both manuals are free and need no agreement to review. Forward them to your developer or software vendor. The Order Entry manual includes sample code in C#, Visual Basic and Ruby.
Before you connect
- Your system must support SNI and modern encryption; very old setups, such as Java 6 or Windows XP, may not connect.
- Use TEST mode until your orders and postbacks work as expected.
- Need help? Contact our integrations team and we'll coordinate with your developers.
Contractor marketplace integration center
Order entry, contractor payment and report delivery are separate events. Confirm payment setup for your account; the example order fragments below do not collect payment or authorize a screening.
Your platform initiates the order
Submit the configured search scope directly. No webhook is needed to initiate the order.
Contractor completes the invitation
The individual supplies information and authorization and pays the package plus initial access fees through the configured screening flow.
Your system receives status and results
Use a receiving address for postbacks, or pull results by order number. Later county verification and its access fees remain on the organization's monthly invoice.
Example: choose status and completion postbacks
Fictional XML fragment inside an order's placeOrder block, following Order Entry §3.5. URL and guID are required when this block is included. Authentication, account credentials, subject information and search elements are omitted; this is not a complete request.
<postBackInfo> <URL>https://marketplace.example/screening/results</URL> <guID>fictional-order-100</guID> <postback_types>IPC::EXP::ICR::OCR</postback_types> </postBackInfo>
Example: completed-results envelope
Fictional envelope fragment based on the XML Results completeOrder structure. Actual messages also contain order, subject and product information; use the full manual for parsing and acknowledgement.
<ScreeningResults>
<completeOrder number="fictional-order-100" remote_number="427722"
isactive="Y" archived="N" reviewed="N" reference_number="">
<!-- Subject and screening-product results omitted from this fragment. -->
</completeOrder>
</ScreeningResults>Example: request results for a known order
Place this fragment inside the authenticated XML request documented in XML Results §1.6. The order number is fictional; do not put account credentials into public client code.
<getOrderResults orderID="427722" />
Implementation acceptance checklist
- Confirm ordering account, allowed products, contractor-payment setup and where reports may be delivered before testing.
- Validate order XML in TEST mode; then review persisted DRAFT orders with the screening team before coordinated PROD use.
- Confirm each order has a correlation identifier and the requested search list; keep credentials and personal information out of browser code and logs.
- Exercise invitation-waiting (IPC), invitation-expired (EXP), component-complete (ICR) and order-complete (OCR) cases with fictional inputs.
- Validate result receipt and acknowledgement against the XML Results manual; test duplicate deliveries and reconcile by order identifiers.
- Assign an owner for expired invitations and delivery failures. Do not treat payment or an individual completed search as a completed report or engagement decision.
- Keep monthly later-verification invoices separate from the contractor's initial payment; never design a second charge to their card.
What should happen when an invitation expires?
EXP identifies an expired invitation in the documented postback types. Your organization should assign a review owner and confirm its next step; this guide does not promise automatic reinvitation, refunds or a new order.
Does a completed payment mean screening is complete?
No. Keep payment, search completion, finished report delivery and the organization's decision as separate states.
Order Entry XML manual · §3.5 · Receiving Results via XML manual · Interactive onboarding workflow · Program builder
Background check API questions
Do we need to build a webhook before we can order?
No. Your system sends the order directly to our platform. If you want status and results sent back automatically, include the postBackInfo block with the order and give us the full web address to post to. Without it, you can pull results for an order by its order number.
Can we test before sending live orders?
Yes. Every order carries a mode of PROD, DRAFT or TEST, and it defaults to TEST when no mode is given, so you can check your connection before placing live orders.
Can a platform place orders on behalf of its clients or contractors' companies?
Yes, when the ordering account has permission. The order_on_behalf_of block (section 3.4) names the ordering account and user. If the logged-in account lacks parent privileges, the order is rejected with an error explaining why.
Can the candidate fill in their own information?
Yes. An order can send the candidate an invitation by email, text message or both, and the postback can tell you when the order is waiting on the candidate and when an invitation expires.
Which searches can be ordered through the API?
The Order Entry manual covers the searches we offer, including county and statewide criminal, national criminal, federal court, sex offender registry, motor vehicle records, commercial driver's license verification, FMCSA crash and inspection history, drug screens, employment and education verification, and SSN verification.
Does the API cost extra?
No. There are no integration fees, platform fees or seat licenses. You pay per check, and the manuals are free to download and share with your developers.
