> ## Documentation Index
> Fetch the complete documentation index at: https://docs.debt-wise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🤝 Equifax Authentication

> Implement the Equifax identity verification and authentication flow, then retrieve a user's credit report.

We use Equifax to get information about a user's outstanding loans, loan history, and credit score. This document will help you implement an identity verification and authentication flow, after which you can retrieve a user's credit report.

## Preparation

Before you begin, you should create a user. Please use the test data below to emulate a success or failure flow for a user:

| Result     | First Name | Last Name  |
| ---------- | ---------- | ---------- |
| Success    | Abby       | CaineenUAT |
| Empty data | Failure    | Smith      |

All other test data will be described in the specific operations.

## Invoke

This step marks the beginning of the user authentication flow. For this authentication method, you should provide the user's device's IP address. If the IP address is a home Wi-Fi, then the next OTP step is usually skipped. If the IP address is cellular, then the next OTP step will be required.

The test data for this step is below:

| Result  | IP Address  |
| ------- | ----------- |
| Success | any         |
| Failure | 127.128.0.0 |

The response to this request will detail the next step. For example:

```json theme={null}
{
  "step": "validate_otp"
}
```

The next step will either be [Validate OTP](#validate-otp) or [Consent](#consent).

<Card title="POST /api/users/{id}/equifax/auth/invoke" icon="terminal" href="/api-reference/equifax/invoke" horizontal />

## Validate OTP

This step is only required if `validate_otp` was the next step that was returned in the `Invoke` response from above.

The test data for this step is below:

| Result  | OTP code |
| ------- | -------- |
| Success | 1111     |
| Failure | 2222     |

The next step is [Consent](#consent).

<Card title="POST /api/users/{id}/equifax/auth/validate_otp" icon="terminal" href="/api-reference/equifax/validate-otp" horizontal />

## Consent

After a user agrees to the Terms & Conditions and gives their consent to pull their credit report, this step is complete.

The next step is [Identity](#identity).

<Card title="POST /api/users/{id}/equifax/auth/consent" icon="terminal" href="/api-reference/equifax/consent" horizontal />

## Identity

This step retrieves a user's identity and returns it as a response. The user must validate the identity that has been returned is their own. If all information is valid, you can proceed to the last step [Credit Report](#credit-report).

If you receive an error, or the user marks some of the returned information as invalid, then please use [DIT](#dit) to retrieve their identity.

<Warning>
  **Notice**

  Use `30030` postal code to get a successful response.
</Warning>

The next step is [Credit Report](#credit-report).

<Card title="POST /api/users/{id}/equifax/auth/identity" icon="terminal" href="/api-reference/equifax/identity" horizontal />

## Abort

You can abort the user authentication flow after any of previous steps detailed above. This method will rollback all previous data, and allow the flow to be restarted from the beginning at any time.

<Card title="POST /api/users/{id}/equifax/auth/abort" icon="terminal" href="/api-reference/equifax/abort" horizontal />

## Credit Report

This step can only be called after a successful Identity was retrieved and validated by the user. If the credit report is pulled successfully, then you will receive a list of debt accounts. Otherwise, you will receive an error.

<Warning>
  **Warning**

  The most common error returned on this step is: `Report is empty`. This means that we successfully retrieved the credit report, however it does not contain any debt accounts or credit score information in it. When this happens, you have a \~20% chance that the [DIT](#dit) identity verification method will resolve the problem. If DIT is also unsuccessful or you continue to receive this error after a successful DIT response, please collect the `X-Trace-ID` headers of your request and send it to [support@debt-wise.com](mailto:support@debt-wise.com).
</Warning>

<Card title="POST /api/users/{id}/equifax/credit_reports" icon="terminal" href="/api-reference/equifax/credit-report" horizontal />

## DIT

You can use this method when Identity is invalid or absent. You need to collect all required parameters for this method manually from the user and send it to us. The result of this method will either be a list of debt accounts or an error.

<Info>
  **A thing to know**

  Please look at the [DIT parameters schema](/api-reference/equifax/dit).
</Info>

<Card title="POST /api/users/{id}/equifax/auth/dit" icon="terminal" href="/api-reference/equifax/dit" horizontal />