Dispute Management API

The Dispute Management API enables users to submit and track disputes regarding inaccurate or incorrect information in their background check reports. This guide provides comprehensive information on implementing dispute workflows in your application.

Key Concepts

Automatic Data Population

Consumer information is automatically extracted from the order's applicant data when creating a dispute. This ensures data consistency and eliminates manual entry errors. The following fields are auto-populated:

• Consumer Name - Constructed from the applicant's name record
• Contact Information - Email and phone number from applicant data
• Identity Verification - Last 4 digits of SSN and date of birth

Dispute Lifecycle

Disputes follow a structured lifecycle with three distinct states:

1. OPEN - Dispute has been submitted and awaits review
2. IN_PROGRESS - Dispute is under active investigation
3. RESOLVED - Dispute has been closed with a resolution

API Endpoints

Submit a Dispute

Create a new dispute for a specific background check order.

Endpoint - Submit Dispute

POST /v1/disputes

Request Body

{
  "orderId": "string (required)",
  "specificItem": "string (optional)",
  "reason": "enum (required)",
  "description": "string (optional)"
}

Parameters

Example Request

curl -X POST https://api.example.com/v1/disputes \
  -H "apiKey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "0bb0f6f8-459f-482a-952e-7caf029517f6",
    "specificItem": "Criminal record from 2015",
    "reason": "INACCURATE_RECORDS",
    "description": "The conviction date shown is incorrect"
  }'

Update Dispute Status

Transition a dispute to a different state in its lifecycle.

Endpoint - Update Dispute Status

PATCH /v1/disputes/{disputeId}/status

Path Parameters

Request Body

{
  "status": "enum (required)"
}

Parameters

Example Request

curl -X PATCH https://api.example.com/v1/disputes/9d3e5f7a-8b2c-4a1e-9f6d-7c8b5a4e3d2f/status \
  -H "apiKey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_PROGRESS"
  }'

Retrieve Dispute Details

Get complete information about a specific dispute.

Endpoint Get Dispute Details

GET /v1/disputes/{disputeId}

Path Parameters

Example Request

curl -X GET https://api.example.com/v1/disputes/9d3e5f7a-8b2c-4a1e-9f6d-7c8b5a4e3d2f \
  -H "apiKey: your-api-key"

List Disputes by Order

Retrieve all disputes associated with a specific order, sorted by creation date (most recent first).

Endpoint - List Disputes by Order

GET /v1/disputes/order/{orderId}

Path Parameters

Example Request

curl -X GET https://api.example.com/v1/disputes/order/0bb0f6f8-459f-482a-952e-7caf029517f6 \
  -H "apiKey: your-api-key"

Reference Data

Dispute Statuses

Dispute Reasons