Information Direct
Documentation

API reference

REST API for programmatic background check ordering, status retrieval, and webhook-driven workflows. OAuth 2.0 bearer tokens, JSON request/response, idempotency keys, and HMAC-signed webhooks.

Base URL and versioning

Production base URL: https://api.informationdirect.us. Sandbox base URL: https://api-sandbox.informationdirect.us. All requests are versioned by URL path - current version is v1. We add backward-compatible changes without bumping the version; breaking changes get a new version with a 12-month deprecation overlap.

Authentication

The API uses OAuth 2.0 with client credentials. Request a token at POST /oauth/token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=orders.write orders.read webhooks.write

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders.write orders.read webhooks.write"
}

Include the token on every request: Authorization: Bearer eyJhbGciOi.... Tokens expire in one hour. Your SDK should auto-refresh on 401 responses; our first-party SDKs (Python, Node.js, Java, .NET, PHP, Ruby) do this by default.

Credentials and scopes

Obtain client credentials from your account manager or by opening a ticket from the portal. Scopes available:

  • orders.read - list and retrieve orders.
  • orders.write - create orders and modify in-progress orders.
  • reports.read - retrieve completed report data and PDFs.
  • webhooks.write - register and modify webhooks.
  • batches.write - create and retrieve batch orders.

Create an order

POST /v1/orders
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Idempotency-Key: req-2026-0187

{
  "package": "plus",
  "applicant": {
    "first_name": "Jordan",
    "middle_name": "A",
    "last_name": "Rivera",
    "dob": "1987-06-14",
    "email": "jordan@example.com",
    "phone": "+13235550177",
    "ssn": "123-45-6789"
  },
  "external_id": "REQ-2026-0187",
  "metadata": { "requisition": "R-417", "role": "Warehouse Associate" }
}

Response (201):

{
  "id": "ord_01HY7R3K8V2NQW",
  "status": "pending_consent",
  "package": "plus",
  "created_at": "2026-04-22T14:05:18Z",
  "links": {
    "applicant_consent": "https://clients.informationdirect.us/consent/abc123",
    "portal_view": "https://clients.informationdirect.us/orders/ord_01HY7R3K8V2NQW"
  }
}

Include Idempotency-Key on all POST requests. If you retry with the same key within 24 hours, you get the original response - no duplicate orders.

Retrieve an order

GET /v1/orders/ord_01HY7R3K8V2NQW
Authorization: Bearer eyJhbGciOi...

Response includes status, component-level findings (if complete), and report-access links.

List orders

GET /v1/orders?status=complete&created_after=2026-04-01&limit=50
Authorization: Bearer eyJhbGciOi...

Supports cursor pagination via next_cursor. Filter by status, created_after, created_before, external_id, and package.

Batch orders

POST /v1/orders/batch
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "default_package": "plus",
  "orders": [
    { "applicant": { "first_name": "Jordan", "last_name": "Rivera",
      "dob": "1987-06-14", "email": "jordan@example.com" },
      "external_id": "REQ-0187" },
    { "applicant": { "first_name": "Priya", "last_name": "Desai",
      "dob": "1992-03-02", "email": "priya@example.com" },
      "package": "premium", "external_id": "REQ-0188" }
  ]
}

Returns a batch_id plus an array of order IDs. Per-order errors are reported without failing the whole batch.

Reports

GET /v1/reports/ord_01HY7R3K8V2NQW
Authorization: Bearer eyJhbGciOi...

Returns machine-readable findings organized by component - criminal records, verifications, credit, MVR, etc. Each finding has a source line, date, jurisdiction, and disposition.

GET /v1/reports/ord_01HY7R3K8V2NQW/pdf
Authorization: Bearer eyJhbGciOi...

Returns a binary PDF of the report, identical to the portal export.

Webhooks

Register a webhook to receive state transitions:

POST /v1/webhooks
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "url": "https://yourapp.example.com/webhooks/infodirect",
  "events": ["order.consent_signed", "order.component_complete",
             "order.report_complete", "order.dispute_opened"],
  "secret": "whsec_..."
}

Every delivery includes an X-InfoDirect-Signature header: t=<timestamp>,v1=<hmac_sha256>. Verify server-side before processing - never trust the payload alone. Our SDKs include verification helpers.

Event types

  • order.created - order accepted, invitation pending
  • order.consent_signed - applicant signed disclosure and authorization
  • order.component_complete - a single component (e.g., county criminal) finished
  • order.report_complete - all components complete; final report available
  • order.dispute_opened - applicant opened a dispute on a finding
  • order.dispute_resolved - reinvestigation concluded
  • order.adverse_action_pre - pre-adverse action notice sent
  • order.adverse_action_final - final adverse action issued
  • order.canceled - order canceled before completion

Rate limits

Defaults:

  • 1,000 requests per minute per access token.
  • 500 order creations per minute.
  • 50 batch creations per hour.

Exceeding these returns 429 Too Many Requests with a Retry-After header. Enterprise accounts can request increased limits.

Errors

Errors follow a consistent shape:

{
  "error": {
    "type": "validation_error",
    "message": "applicant.dob is required and must be a valid date",
    "field": "applicant.dob",
    "request_id": "req_01HY7R3KA9"
  }
}

Include the request_id when contacting support - it's how we find your request in logs.

Common types: validation_error, authentication_error, permission_error, rate_limit_error, not_found, idempotency_error, api_error (retriable).

SDKs

First-party SDKs wrap auth, retries, webhook verification, and typed response models:

  • Python - pip install informationdirect
  • Node.js - npm install @informationdirect/node
  • Java - Maven coordinates on apidocs
  • .NET - NuGet InformationDirect
  • PHP - composer require informationdirect/php
  • Ruby - gem install informationdirect

Sandbox environment

Test credentials and sandbox base URL are available in the portal under Account / API keys / Sandbox. The sandbox simulates the full order lifecycle with configurable delays, canned findings, and webhook delivery. No real applicants are contacted in sandbox; consent emails route to a test inbox.

Need beta access?

The public API is in limited beta. To request credentials and production access, contact your account manager or email api@informationdirect.us. Turnaround on beta requests is typically two business days.

Was this helpful? Tell us what's missing
Create Account