Developer Center›Guides›Consumer Disputes

Handling Consumer Disputes via the API

Consumer disputes must be handled within strict FCRA timelines. This guide covers the API endpoints, compliance codes, and documentation practices you need for dispute management.

1. FCRA Timeline Requirements

Warning

Missing the 30-day investigation deadline is an FCRA violation. Repeated violations can result in regulatory action and statutory damages of $100-$1,000 per consumer.

The Fair Credit Reporting Act (FCRA) imposes strict deadlines on how data furnishers must handle consumer disputes:

Direct Disputes (consumer contacts you directly)

• 30 days to investigate and respond
• Clock starts when you receive the dispute
• Must report results to all bureaus you furnished to

Indirect Disputes (consumer disputes via a bureau)

• 30 days to investigate (extendable to 45 days if the consumer provides additional information)
• Clock starts when the bureau forwards the dispute (ACDV)
• Must respond to the bureau with investigation results

After Investigation

• 5 business days to notify the consumer of results (direct disputes)
• Correct or delete inaccurate information immediately
• Update all bureaus within the next reporting cycle

2. Using the Disputes API

The Disputes API provides endpoints for creating, tracking, and resolving consumer disputes programmatically.

Create a Dispute

POST /v1/disputes
Content-Type: application/json
Authorization: Bearer live_sk_abc123def456

{
  "recordId": "rec_abc123",
  "source": "direct",
  "consumerStatement": "I was never 30 days late in November 2024",
  "disputedFields": ["accountStatus", "paymentHistoryProfile"],
  "receivedDate": "2025-01-10",
  "consumerContact": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

// Response (201 Created)
{
  "disputeId": "dsp_xyz789",
  "status": "open",
  "deadline": "2025-02-09",
  "daysRemaining": 30,
  "createdAt": "2025-01-10T14:30:00Z"
}

List Disputes

GET /v1/disputes?status=open&sort=deadline
Authorization: Bearer live_sk_abc123def456

// Response (200 OK)
{
  "disputes": [
    {
      "disputeId": "dsp_xyz789",
      "recordId": "rec_abc123",
      "status": "open",
      "source": "direct",
      "deadline": "2025-02-09",
      "daysRemaining": 12,
      "createdAt": "2025-01-10T14:30:00Z"
    },
    ...
  ],
  "total": 5,
  "page": 1
}

Resolve a Dispute

PATCH /v1/disputes/dsp_xyz789
Content-Type: application/json
Authorization: Bearer live_sk_abc123def456

{
  "status": "resolved",
  "resolution": "corrected",
  "resolutionDetails": "Payment history corrected for November 2024",
  "corrections": {
    "accountStatus": "11",
    "paymentHistoryProfile": "000100000000000000000000"
  },
  "investigationNotes": "Bank records confirmed payment received on time"
}

// Response (200 OK)
{
  "disputeId": "dsp_xyz789",
  "status": "resolved",
  "resolution": "corrected",
  "resolvedAt": "2025-01-25T09:15:00Z",
  "bureauNotificationStatus": "pending"
}

3. Compliance Condition Code XB

Compliance Condition Code XB (Field 39) indicates that an account is currently in dispute. This code must be set when a consumer files a dispute and cleared when the investigation is complete.

// When a dispute is received, set XB on the record
PATCH /v1/records/rec_abc123
{
  "complianceConditionCode": "XB"
}

// The XB code tells credit bureaus:
// - Account information is being disputed by the consumer
// - Investigation is in progress
// - Score models may treat the account differently during dispute

// When the investigation is complete, clear the code
PATCH /v1/records/rec_abc123
{
  "complianceConditionCode": ""
}
// Or if correcting the record, apply corrections and clear XB simultaneously

When to Use XB

• Set XB the same day you receive the dispute
• Keep XB active during the entire investigation period
• Remove XB when the investigation concludes and results are reported
• If the consumer disputes again, set XB again immediately

4. Dispute Lifecycle States

Every dispute progresses through a defined lifecycle. Your system must track these states and take appropriate action at each transition.

open

Dispute received. Set Compliance Condition Code XB on the record. 30-day clock starts.

investigating

Investigation in progress. Review consumer claims against your records. Gather supporting documentation.

resolved

Investigation complete. Possible resolutions:

corrected — Data was inaccurate; record updated
verified — Data confirmed accurate; no changes made
deleted — Record removed entirely

5. Webhook Integration for Dispute Notifications

Configure webhooks to receive real-time notifications about dispute events. This is critical for meeting FCRA deadlines — you cannot afford to miss an incoming dispute.

// Webhook payload: dispute.received
POST https://your-app.com/webhooks/metro2
Content-Type: application/json
X-Metro2-Signature: sha256=abc123...

{
  "event": "dispute.received",
  "data": {
    "disputeId": "dsp_xyz789",
    "recordId": "rec_abc123",
    "source": "bureau",
    "bureau": "equifax",
    "disputedFields": ["accountStatus", "paymentHistoryProfile"],
    "deadline": "2025-02-09",
    "receivedAt": "2025-01-10T14:30:00Z"
  }
}

// Webhook payload: dispute.deadline_approaching
{
  "event": "dispute.deadline_approaching",
  "data": {
    "disputeId": "dsp_xyz789",
    "daysRemaining": 5,
    "deadline": "2025-02-09"
  }
}

Available Dispute Webhook Events

dispute.received — New dispute received (start the clock)
dispute.deadline_approaching — 5 days before deadline
dispute.resolved — Dispute resolution submitted
dispute.overdue — Deadline has passed without resolution

6. Documentation Best Practices for CFPB Readiness

The Consumer Financial Protection Bureau (CFPB) can audit your dispute handling process at any time. Maintain thorough documentation for every dispute.

What to Document

• Date and method the dispute was received
• Consumer's specific claims (what they say is wrong)
• All records reviewed during the investigation
• Source documents used to verify information
• Investigation findings and reasoning
• Actions taken (corrections, deletions, or verification)
• Date the consumer was notified of results
• Date corrections were reported to bureaus

Retention Requirements

• Keep all dispute records for a minimum of 5 years
• Store the original consumer communication
• Maintain an audit trail of all status changes
• The Disputes API automatically timestamps and logs all actions

// Retrieve full dispute audit trail
GET /v1/disputes/dsp_xyz789/audit-trail
Authorization: Bearer live_sk_abc123def456

// Response
{
  "disputeId": "dsp_xyz789",
  "events": [
    {
      "timestamp": "2025-01-10T14:30:00Z",
      "action": "dispute_created",
      "details": "Direct dispute received from consumer"
    },
    {
      "timestamp": "2025-01-10T14:30:01Z",
      "action": "compliance_code_set",
      "details": "XB set on record rec_abc123"
    },
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "action": "status_changed",
      "details": "Status changed to investigating"
    },
    {
      "timestamp": "2025-01-25T09:15:00Z",
      "action": "dispute_resolved",
      "details": "Resolved as corrected. Payment history updated."
    },
    {
      "timestamp": "2025-01-25T09:15:01Z",
      "action": "compliance_code_cleared",
      "details": "XB removed from record rec_abc123"
    },
    {
      "timestamp": "2025-01-25T09:20:00Z",
      "action": "consumer_notified",
      "details": "Results sent to john@example.com"
    }
  ]
}