Getting Started with the Experian Integration API

The relay Experian Integration API provides external partners and integrators with secure access to consumer credit reports, identity verification, and screening services. This guide will walk you through making your first API call.

Prerequisites

Before you begin, ensure you have:

1. API Key (SSO Token): Obtain your API key from relay during your onboarding process. This key is required for all API requests.

2. UAT Environment Access: All testing should be performed against the UAT environment:

   https://api.preprod.ir.app

3. Test Consumer Data: Use the Test Consumers page to find sandbox test identities with SSNs, addresses, and KBA answers.

4. Error Code Reference: Familiarize yourself with the Error Codes reference for troubleshooting.

warning

Never use production API keys in development or test environments. Keep your API keys secure and do not commit them to version control.

Step 1: Authentication

All API requests require authentication using the X-API-KEY header with your SSO token.

Example: Check Authentication Status

curl -X GET "https://api.preprod.ir.app/api/experian/agents/{agentId}/auth/status" \
  -H "X-API-KEY: your-sso-token-here"

Success Response (200 OK):

{
  "errors": [],
  "payload": { "...": "Experian authentication-status response" }
}

Authentication Failure (403 Forbidden):

{
  "payload": null,
  "errors": [
    {
      "errorCode": 324,
      "errorOnField": null,
      "errorMessage": "Invalid client secret."
    }
  ]
}

tip

If you receive a 403 error with code 324, verify that your API key is correct and included in the X-API-KEY header.

Prefer working in Postman? Open the Relay API collection — every request below is pre-configured with X-API-KEY auth and a ready-made UAT environment; fork it, set your apiKey variable, and run.

Step 2: Register a Test Consumer

To pull a consumer's credit report, you first need to register them in the system. Let's use Joseph Calandi's test data from the Test Consumers page.

curl -X POST "https://api.preprod.ir.app/api/experian/renters/{renterId}" \
  -H "X-API-KEY: your-sso-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Joseph",
    "lastName": "Calandi",
    "ssn": "666317315",
    "dob": "06061970",
    "currentAddress": "386 17TH AVE NE APT 15",
    "currentCity": "HICKORY",
    "currentState": "NC",
    "currentZip": "28601",
    "phoneNumber": "9494308868",
    "email": "joseph.calandi@example.com",
    "ipAddress": "69.162.81.156",
    "jscPayload": "sample-jsc-device-fingerprint-payload",
    "hdimPayload": "sample-hdim-payload"
  }'

Expected fields are firstName, lastName, currentAddress, currentCity, currentState, currentZip, ipAddress, jscPayload, and hdimPayload. These are not all validated by the API itself — missing values surface as Experian verification failures rather than a clean 400 — so always supply them. dob uses MMDDYYYY format. The jscPayload/hdimPayload values above are short stand-ins accepted in UAT — the full relay-provided test payloads are on the Test JSC & HDIM Payloads page. See the Add Renter reference for the full field list.

Success Response (200 OK):

The payload is the Experian passive-user response passed through unchanged. When identity verification is required it contains the KBA questions or OTP challenge along with session identifiers:

{
  "errors": [],
  "payload": { "...": "Experian response — KBA/OTP challenge or registration result" }
}

info

When the registration response indicates KBA is required, the consumer must complete Knowledge-Based Authentication before you can retrieve their report.

Step 3: Handle KBA Authentication

After registering a consumer, the API returns Knowledge-Based Authentication (KBA) questions. The consumer must answer these questions correctly to verify their identity.

KBA Questions Format:

{
  "sessionId": "kba-session-789",
  "questions": [
    {
      "id": 1,
      "text": "Using your date of birth, please select your astrological sun sign.",
      "answers": [
        { "id": "A", "text": "Aries" },
        { "id": "B", "text": "Gemini" },
        { "id": "C", "text": "Leo" },
        { "id": "D", "text": "None of the above" }
      ]
    },
    {
      "id": 2,
      "text": "I was born within a year or on the year of the date below.",
      "answers": [
        { "id": "A", "text": "1968" },
        { "id": "B", "text": "1970" },
        { "id": "C", "text": "1972" },
        { "id": "D", "text": "None of the above" }
      ]
    }
  ]
}

Submit KBA Answers:

curl -X POST "https://api.preprod.ir.app/api/experian/renters/{renterId}/kba" \
  -H "X-API-KEY: your-sso-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "kbaAnswers": [
      { "answer": 2 },
      { "answer": 2 }
    ]
  }'

Each entry in kbaAnswers is the selected choice for the corresponding question, in the order the questions were presented. The answer value is the integer position of the chosen option (e.g. 2 selects the second option).

tip

The Test Consumers page contains all correct KBA answers for each test identity. If a question or answer is not listed, select "None of the above".

KBA Success Response (200 OK):

The endpoint returns the Experian passive-user response unchanged. userAuthenticated is the field to check — a UserToken is issued once identity is confirmed.

{
  "payload": {
    "success": true,
    "userAuthenticated": true,
    "UserToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.EXAMPLE",
    "authSession": "a7f3c81e-2d54-4b9a-8c07-1e6b5d3f2a90",
    "otpEnabled": false,
    "kiqEnabled": true,
    "clientReferenceId": "rnt_9f31c0",
    "kba": null,
    "crossCoreFullResponse": null
  },
  "errors": []
}

KBA Failure (422 Unprocessable Entity):

Incorrect answers return 422 with the Experian step-up payload. After repeated failures the user is temporarily blocked and subsequent calls return 423 Locked.

errors is empty on a 422

A 422 response body is structurally identical to a 200 — errors is [] in both cases, and the difference is in userAuthenticated. Branch on the HTTP status code, never on errors.length.

Step 4: Retrieve the Report

Once the consumer passes KBA authentication, you can retrieve their credit report.

The report is returned as rendered HTML by default for partner clients. Add ?format=json to receive the structured JSON payload instead.

# Rendered HTML (default for partner clients)
curl -X GET "https://api.preprod.ir.app/api/experian/renters/{renterId}/report" \
  -H "X-API-KEY: your-sso-token-here"

# Structured JSON
curl -X GET "https://api.preprod.ir.app/api/experian/renters/{renterId}/report?format=json" \
  -H "X-API-KEY: your-sso-token-here"

Success Response (200 OK):

With ?format=json, the response uses the standard envelope; the payload is the structured Experian credit report passed through unchanged:

{
  "errors": [],
  "payload": { "...": "Experian credit report (trade lines, public records, inquiries, scores)" }
}

Without format=json, partner clients receive the rendered HTML report (Content-Type: text/html) instead.

Use GET /renters/{renterId}/report-expiry to check the report's tokenExpiration timestamp.

warning

Reports expire 30 days after they are generated. After expiration, report requests return 400 Bad Request with error code 138 (errorOnField: "tokenExpiration", "Report has expired").

Prepaid accounts

If your account is on the prepaid credit billing model and its balance is exhausted, this request returns 402 Payment Required with error code PAYMENT_REQUIRED before a report is generated. Do not retry — service resumes automatically once credits are added. See the Billing section for details.

Step 5: Handle Errors

When errors occur, the API returns structured error responses with error codes, HTTP status codes, and descriptive messages. Refer to the Error Codes reference for a complete list.

Common Error Codes

Error Code	HTTP Status	Message	Resolution
138	400	Required field missing / Report has expired	Supply the field named in errorOnField; for an expired report, re-register and pull a fresh report
324	403	Invalid client secret.	API key is missing or invalid. Check your X-API-KEY header
278 / 293	404	Not found	Verify the renter/agent/organization identifier
292	409	Already registered	The user is already registered — continue with authentication or report retrieval
285	402	Payment required (Consumer API only)	The renter has not completed their per-transaction Stripe Checkout payment. Direct them to complete payment, then retry. Unrelated to your organization's relay billing
PAYMENT_REQUIRED	402	Your credit balance is $0	Your organization's prepaid credit balance is exhausted. Add credits to resume; do not retry. See Billing
300	423	User blocked	Too many failed KBA/OTP attempts. Wait for the unblock time included in the message
—	422	Incorrect KBA/OTP	Answers were incorrect (Experian step-up payload returned). Check test consumer data

info

When contacting relay support about an error, include the error code, HTTP status, and any PID error code from the response.

Next Steps

Now that you've made your first API call, explore the full API documentation:

• Consumer API - Renter registration, authentication, and report retrieval (see sidebar)
• IRO End User API - Individual agent operations and report sharing (see sidebar)
• PMC End User API - PMC organization operations and report management (see sidebar)
• Error Codes - Complete error code reference with causes and resolutions
• Test Consumers - Full list of sandbox test identities with KBA answers

Support

If you encounter issues or have questions about integrating with the Experian Integration API, contact relay integration support for assistance.

---

Ready to dive deeper? Check out the API reference sections in the sidebar for detailed endpoint documentation.