Introduction

Welcome to the Safe Hiring worldwide API. You can use our API to access all background check and identity verification functionalities, allowing you to integrate powerful screening capabilities directly into your ATS, HRIS, or custom platform.

The API is organized around REST, uses standard HTTP response codes, and returns JSON-encoded responses.

Authentication

Safe Hiring worldwide uses API keys to allow access to the API. You can view your API keys in your dashboard settings.

Your API key carries many privileges, so be sure to keep it secret! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Authorization: Bearer sk_live_4eC39HqLyjWDarjtT1zdp7dc
Content-Type: application/json

Candidates

Create a candidate object to initiate a background check. The candidate will receive an email notification to consent to the verification process.

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+15551234567",
  "dob": "1990-05-15",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "tags": ["engineering","senior"]
}

{
  "id": "cand_abc123xyz",
  "object": "candidate",
  "created_at": 1698765432,
  "status": "pending_consent"
}

Screenings

Once a candidate is created, request a specific type of screening package (e.g., Criminal, Education, Employment).

{
  "candidate_id": "cand_abc123xyz",
  "package_id": "pkg_standard_us",
  "fast_track": true
}

Check Status

Poll this endpoint to check the progress of a background check. We also recommend setting up webhooks for real-time updates.

{
  "id": "scr_xyz789",
  "status": "clear",// "clear", "consider", or "pending"
  "completed_at": 1698770000,
  "reports": [
    {
      "type": "criminal_search",
      "status": "complete",
      "result": "No Records Found"
    }
  ]
}

Errors

Safe Hiring uses conventional HTTP response codes to indicate the success or failure of an API request.