B2C Documentation (v0)

Download OpenAPI specification:Download

Quickstart

  • Equifax end-points are accessible first using the User API /users/efx-config response data and the Equifax /oauth/token calls.
  • User API and Equifax API calls are intended to be called directly from the end-client.
  • It is not acceptable to pass any of the data to these calls or responses from these calls to your server.
  • Do not save any data. Short term caching is fine, but long-term storage is not.
  • The preauth token is only valid for 30 seconds
  • Direct API calls must originate from your server
  • User API calls must originate from the end-client
  • Equifax API calls must originate from the end-client

Getting Started

  • Access Credentials will be sent to you in a Postman Environment upon registration via email.
    • The Postman Environment is pre-configured to allow you to use the scripts and walk through the Postman Scripts with minimal intervention to aid in understanding the API call structure.
  • The Consumer Credit - Getting Started - New User.postman_collection.json will walk you through the Create New User steps in order
  • The Consumer Credit - Getting Started - Returning User.postman_collection.json will walk you through the Returning User steps in order
  • In the test environment it is important that you use the User Test Identity provided to you verbatim.
    • You may change the email address and phone number ONLY

Basic Steps To Create New Users & Returning Users (Including Data Access Steps):

Creating New Users:

  • Direct API

    • Customer Login
    • Register New User
  • User API

    • Preauth Token
    • User Identity
    • Phone Verify
    • Send Mobile Code
    • Verify Mobile Code
    • Get EFX Config
  • EFX API

    • OAUTH Token
      • Credit Score Latest
        • Credit Score History
        • Credit Report List
          • Credit Report Summary
          • Credit Report (First in list) - PRINT

    When creating creating a new user:

    • Be sure to save the userId when Registering a New User or you will not be able to generate a returning token for the user

    • Once you create a user the identity information is hashed and used to verify if the same identity is being re-enrolled.

    • If a matching hash is found it will skip the identification process.

      • This is great in production, but may limit your ability to test.
      • To get past this, just add a number to the USER_STREET_2 and increment it each time you register a new user and want to go through the full authentication process.
    • On Register New User - change the email to your email.

      • You may add a +1, +2, etc to keep reusing the same email address (ex: test+1@test.com)
    • On Register New User & User Identity - change the phone number to your mobile phone number or you won't receive the SMS messages.

    • Using the Phone Verify, Send Mobile Code, Verify Mobile Code method, the code in the test system passes through,

      • so you can just keep clicking the send on those functions, though you will receive the text as well.
    • For the Get Identity Quiz and Verify Identity Quiz methods, you will need to find the correct answers and update the Verify Identity Quiz body accordingly to successfully authenticate using those methods.

    • When registering a new user, be sure to save the userId or you will not be able to log that user in later.

      • As a matter of security, we do not allow the listing of user IDs.
    • REMEMBER - you MUST use the test user data EXACTLY as it is provided. Only the phone number and email should be changed.

    Returning Users:

    • Direct API
      • Customer Login
      • New User Token
    • User API
      • Preauth Token - if (idpass=false), the next four calls would need to be made, otherwise skip to Get EFX Config if true)
      • User Identity
      • Phone Verify
      • Send Mobile Code
      • Verify Mobile Code
      • Get EFX Config
    • EFX API
      • OAUTH Token
        • Credit Score Latest
        • Credit Score History
        • Credit Report List
          • Credit Report Summary
          • Credit Report (First in list) - PRINT

Access Credentials

  • Access credentials will be sent to you in a Postman Environment.
  • The Postman Environment is pre-configured to allow you to use the scripts and walk through the Postman Scripts with minimal intervention to aid in understanding the API call structure.

Webhooks

  • Webhooks are available to notify you when an alert (or other notifications) comes in so that you can message users in whatever fashion you wish to return to your site.

  • To get started, please provide us a URL endpoint to push the webhook to.

    • The webhook should implement SSL and Basic HTTP Authentication, so we need a username and password to the endpoint (15-char or less, it's not super secure and probably doesn't need to be).
  • The basic JSON for the web hook will look like the following:

    {
      id: "String - Webhook ID, UUID format",
      type: "String - Webhook Type, see possible values below",
      user_id: "String - StitchCredit user ID, UUID format",
      host_id: "String - The host configuration generating the webhook, UUID format",
      time: "long - Linux epoch, seconds since 1/1/1970",
      error_code: "String - used to report host errors, future use at the moment",
      error_msg: "String - error code details"
      alert_id: "String - id for retrieving more details when available",
      alert_date: "Date - the date/time the alert was reported",
      alert_source: "String - name of the institution reporting when available"
    }
  • When a webhook is received, a response is needed.

  • Responses with a status other than true will cause the webhook to be resent.

    {
      hook_id: "the ID of the webhook",
      status: true | false
    }
    Webhook Type Values
    ACCNEW New Account Created (only sent when created via web, not direct)
    IDFAIL Identity Failed (user identification process failed)
    ACCREG Account Registered (user passed identification and is registered for data)
    ACCREGFAIL Account Registration Failed (user passed identification, but was unable to register for data)
    ACCCLOSED Account Closed (only sent when completed via web, not direct)
    ACCLOCKED Account Locked Out (account is temporarily locked out)
    ACCLOGINFAIL Login Failure (when user authentication fails, web only)
    ACCALERT Account Alert (when credit alert notifications, both daily and real-time)
    SCOREREF User Score has been refreshed
    REPORTREF User Report has been refreshed
    ERROR Error (report important issues that may be of interest)
    TEST Test (testing notification)
  • Additional webhooks may be added without notice

  • Once your host is configured you can use Webhook Test to send a test webhook for a user on demand.

Web Messaging using Post Message

  • To interact with the Consumer Credit Widget you will need to implement a structure using Post Message to receive, process and respond to events generated by the Consumer Credit Widget in the iFrame.
  • Explanation for most messages is explained within the Javascript code:
    • See Tabbed User Interface with Dynamic Consumer Authentication (direct_sample.html) for a working implementation.
  • The /test/preauth-token used in the getData function only functions in the development environment.
    • You should implement your own user authentication on your servers and return a valid preauth-token to continue.
<script>
  //this just throws in a default ID if one isn't provided on the query string
  const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
  console.log("ID: ",id);
  console.log("Loading Message Listener...");

  window.addEventListener("message", receiveMessage, false);

  function receiveMessage(event) {
    if(event && event.source && event.data) {
      // You only need to implement the types that are important/relevant to your use case.
      if(event.data.type === 'AUTH_REQUIRED') {
        //The iframe clident will post this message when a valid preauth token does not exist.
        //Posting a proper message with a preauth token in response allows the client to continue seemlessly.
        //console.log("Auth Required Event Received");
        const es = event.source;
        //this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
        //This is ONLY for testing and does not exist in the production environment.
        getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
          const token = JSON.parse(this.responseText).token;
          console.log("Status: ", this.status, ", token: ", token);
          es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
        });
      }
      else if(event.data.type === 'REG_STARTED') {
        //only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
        es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "bryan+21@test.com", mobile: "0000000000"}},"*");
      }
      else if(event.data.type === 'IDENTITY_STARTED') {
        //You could use this function to pre-populate the given fields.  DoB and SSN will never be prepopulated as it violates compliance
        es.postMessage({type: 'IDENTITY', data: {street1:"", street2: "", city: "", state: "", zip: ""}},"*");
      }
      else if(event.data.type === 'LOGIN_SUCCESSFUL') {
        console.log("User succesfully logged in");
      }
      else if(event.data.type === 'LOGIN_FAILED') {
        //if you see this message more than a few times in a row, it's likely an issue
        //typically this will only occur for full web implementations, not Direct API
        console.log("User login failed");
      }
      else if(event.data.type === 'USER_ENROLLED') {
        //User successfully completed identity and has been enrolled for consumer data
        console.log("User enrollment successful");
      }
      else if(event.data.type === 'IDENTITY_FAILED') {
        //Identity process failed, user is likely "stuck" as they cannot continue
        console.log("User identity failure");
      }
      else if(event.data.type === 'SERVICE_FAILURE') {
        //Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
        console.log("Identity service failure");
      }
    }

    function getData(req, action) {
    var xhr = new XMLHttpRequest();
      xhr.responesType = 'json';
      xhr.onload = action;
      xhr.open("GET", req);
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.send();
    }
  }
<\script>

Token Validity Times

Direct Tokens

Preauth Tokens

User Tokens

Mobile Verification Tokens

1 hour

30 seconds

15 minutes

15 minutes


Refresh Tokens are valid after 15 minutes, and expire after 30 minutes

Customer Tokens are valid for 1 day (not used in Direct API)

Action Tokens are valid for 10 minutes (not used in Direct API)

Simple Web Integration Guide

Web Integration Requirements:

  • API Key
  • Host Registration (eg your web site address)
  • Integration Host & parameters
  • Configuration Flags
  • Primary Theme Color (six character hex, without #)

Sample Embed Page:
To embed into HTML, create an iframe as shown in the following example with its src reflecting this color-coded URL:

"https://efx-dev.stitchcredit.com/api/users/start?key=[API-KEY]&ocf=[FLAGS]&oct=[COLOR]"


Embed example:

<html>
  <head>
    <title>StitchCredit</title>
    <meta name="description" content="StitchCredit Consumer Credit Reports"/>
    <link rel="icon" href="/favicon.ico">
    <style>
      body { background: #F9FAFB; }
      #sc-iframe { border:none;overflow:hidden;padding:0px;margin:0px;
      width:100%;height:100vh;z-index:1;position:absolute;left:0;top:0; }
    </style>
  </head>
  <body>
    <iframe id="sc-iframe" src="https://efx-dev.stitchcredit.com/api/users/start?key=[API-KEY]&ocf=[flags]&oct=[color]" width=“100%” height=“100vh”></iframe>
  </body>
</html>

Web Integration with Customer Authentication

  • A token from /direct/login is required for all other Direct API end-points in yellow.
    • It is a bearer authorization token
  • Once you have a preauth token, returned from /direct/user-reg or /direct/preauth-token, pass it to the Web UI entry point in the embedded iFrame.
  • Be sure to save the ID returned from /direct/user-reg or you won’t be able to reauthorize the user when they return.
  • **The preauth token is only valid for 30 seconds

Direct API End-points:

Customer Login
/direct/login
Register New User
New User Token
Change Email
Change Phone
Close Account
Update Refresh
/direct/user-reg
/direct/preauth-token
/direct/change-email
/direct/change-phone
/direct/close-account
/direct/update-refresh [PREMIUM FEATURE]

Consumer Web with Custom Authentication Requirements:

  • StitchCredit Registration:
    • API Key
    • Host Registration (eg your web site address)
    • Integration Host & parameters
    • Configuration Flags
    • Primary Theme Color (six character hex, without #)
    • Pre-auth token – optional if using postmessage configurationsee Advanced Embedded Page w/ Messaging
  • Only the registered host can serve the UI with the designated API Key
  • Embed iframe on a blank page under the registered host
  • Style the iframe/page to suit your needs

Sample iframe with Inline Token:

Create an iframe as shown in the following example with its __src__ reflecting this color-coded URL:

"https://efx-dev.stitchcredit.com/login-direct?key=[API-KEY]&token=[PREAUTH-TOKEN]&ocf=[FLAGS]&oct=[COLOR]"


Embed example:

<html>
  <head>
    <title>StitchCredit</title>
    <meta name="description" content="StitchCredit Consumer Credit Reports"/>
    <link rel="icon" href="/favicon.ico">
    <style>
      body { background: #F9FAFB; }
      #sc-iframe { border:none;overflow:hidden;padding:0px;margin:0px;
      width:100%;height:100vh;z-index:1;position:absolute;left:0;top:0; }
    </style>
  </head>
  <body>
    <iframe id="sc-iframe" src=“https://efx-dev.stitchcredit.com/login-direct?key=[API-KEY]&token=[PREAUTH-TOKEN]&ocf=[FLAGS]&oct=[COLOR]” width=“100%” height=“100vh” frameborder=“0”></iframe>
</body>
</html>

Advanced Embedded Page w/ Messaging

  • Facilitates communication between the primary application and the embedded StitchCredit application
  • Allows customer application to react to changes and events in the StitchCredit application
  • Customer needs to implement AJAX preauth token generation function, the “getData” implementation in the sample files only work in the testing environment and will not work in production.
    • True user authentication and processing must be done server-side.
  • Sample files show possible usage and event handling (see Sample Files section)

API Process Flow

Communication & Token Flow

  • The objective of using tokens is to reduce the use of API Keys and/or Password tokens, improving security by reducing exposure
  • Tokens further optimize the performance of the system by reducing the number of authentication lookups necessary to complete a request
  • Multiple different tokens are used to secure different systems and aspects of the application
  • The Direct Token is used to secure YOUR credentials and access - Your API Key, Secret and the Tokens generated should never leave your server
  • The Direct API is used to generate pre-auth tokens for consumer client access
  • Preauth tokens are intended to be sent to the client and exchanged for a user token. They expire quickly and should be exchanged for user tokens right away
  • User tokens are intended for client API access
  • EFX Config data is used to retrieve an Equifax OAuth Delivery token
  • The EFX OAuth Delivery token is locked to the IP that requests it and cannot be used from any other IP
  • The EFX OAuth Delivery token is required for all Equifax API Requests

Direct API

Collection of end-points that should be called from your server.

Customer Login

/direct/login

  • Using your credentials in the request body ("apikey" and "secret"), the response will contain the token and refresh token.
  • These tokens are required for completing the other requests to Direct API endpoints.
  • This token will be valid for approximately one hour.
  • After the one hour, the refresh token will become valid.
  • If the token expires, use /direct/refresh-token?token={refresh} to get a new token
Request Body schema: application/json

Add your credentials to "apikey" and "secret".
(keep these credentials a secret)

secret
required
string
apikey
required
string

Responses

Request samples

Content type
application/json
{
  • "secret": "{{SECRET}}",
  • "apikey": "{{API_KEY}}"
}

Customer Refresh Token

/direct/refresh-token

query Parameters
token
required
string
Example: token={{rdtoken}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Register New User

/direct/user-reg

  • Creates a new user with unique userId and preauth token.
  • When a user logs back in, use /direct/preauth-token/{userId} to generate that user a new preauth token and a new userId (refer to Returning User)

Don't store the token across sessions.
Use the userId from the previous session to generate a new userId and a new preauth token.

Request Body schema: application/json
email
required
string
fname
required
string
lname
required
string
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "{{USER_EMAIL}}",
  • "fname": "{{USER_FNAME}}",
  • "lname": "{{USER_LNAME}}",
  • "mobile": "{{USER_MOBILE}}"
}

New User Token

/direct/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Close User Account

/direct/close-account/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Change User Email

/direct/change-email/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "test@test.com"
}

Change User Phone

/direct/change-mobile/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "mobile": "1234567890"
}

Change User Host

/direct/change-host/{userId}

path Parameters
userId
required
string
query Parameters
host
required
string
Example: host={{HOST_ID}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Update User Refresh Date

/direct/update-refresh/{userId}

*Premium Feature - May Require Additional Access

path Parameters
userId
required
string
query Parameters
rmonly
required
boolean
Example: rmonly=false
header Parameters
Content-Type
required
string
Example: application/json

Responses

Get Alert Detail

/direct/efx-alert/{alertId}

*Premium Feature - May Require Additional Access

path Parameters
alertId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Test API

Collection of end-points for testing webhooks

New Pre-auth Token

/test/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Test

/test/webhook/send/{userId}

path Parameters
userId
required
string
query Parameters
count
required
integer <int32>
Example: count=1
type
required
string
Example: type=NEW_ACCOUNT
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Sink

/test/webhook/sink

Request Body schema: application/json
Array ()
type
required
string
user_id
required
string
time
required
string
error_code
required
string
error_msg
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Tabbed User Interface with dynamic Consumer Authentication

Tabbed User Interface with dynamic Consumer Authentication integration

direct_sample.html:

<html>
  <head>
    <title>StitchCredit</title>
    <link rel="icon" href="/favicon.ico" />
    <meta name="description" content="StitchCredit Consumer Credit Reports" />
    <meta
    name="viewport"
    content="minimum-scale=1, initial-scale=1, width=device-width"
    />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        position: relative;
        background: #eeeeee;
      }
      #sc-iframe {
        margin: 0;
        padding: 0;
        z-index: 1;
        width: 100%;
        height: 100vh;
        border: none;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <iframe
    id="sc-iframe" allowTransparency="true"
    src="https://efx-dev.stitchcredit.com/login-direct?key=5a10e0d7-1dc8-4325-929f-d0d131990527"
    ></iframe>
    <script>
      //this just throws in a default ID if one isn't provided on the query string
      const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
      console.log("ID: ",id);
      console.log("Loading Message Listener...");

      window.addEventListener("message", receiveMessage, false);

      function receiveMessage(event) {
        if(event && event.source && event.data) {
        // You only need to implement the types that are important/relevant to your use case.
        if(event.data.type === 'AUTH_REQUIRED') {
          //The iframe clident will post this message when a valid preauth token does not exist.
          //Posting a proper message with a preauth token in response allows the client to continue seemlessly.
          //console.log("Auth Required Event Received");
          const es = event.source;
          //this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
          //This is ONLY for testing and does not exist in the production environment.
          getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
            const token = JSON.parse(this.responseText).token;
            console.log("Status: ", this.status, ", token: ", token);
            es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
          });
        }
        else if(event.data.type === 'REG_STARTED') {
          //only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
          es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "bryan+21@test.com", mobile: "0000000000"}},"*");
        }
        else if(event.data.type === 'IDENTITY_STARTED') {
          //You could use this function to pre-populate the given fields.  DoB and SSN will never be prepopulated as it violates compliance
          es.postMessage({type: 'IDENTITY', data: {street1:"", street2: "", city: "", state: "", zip: ""}},"*");
        }
        else if(event.data.type === 'LOGIN_SUCCESSFUL') {
          console.log("User succesfully logged in");
        }
        else if(event.data.type === 'LOGIN_FAILED') {
          //if you see this message more than a few times in a row, it's likely an issue
          //typically this will only occur for full web implementations, not Direct API
          console.log("User login failed");
        }
        else if(event.data.type === 'USER_ENROLLED') {
          //User successfully completed identity and has been enrolled for consumer data
          console.log("User enrollment successful");
        }
        else if(event.data.type === 'IDENTITY_FAILED') {
          //Identity process failed, user is likely "stuck" as they cannot continue
          console.log("User identity failure");
        }
        else if(event.data.type === 'SERVICE_FAILURE') {
          //Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
          console.log("Identity service failure");
        }
      }

      function getData(req, action) {
        var xhr = new XMLHttpRequest();
        xhr.responesType = 'json';
        xhr.onload = action;
        xhr.open("GET", req);
        xhr.setRequestHeader("Content-Type", "application/json");
        xhr.send();
      }

    }
    </script>
  </body>
</html>   

All-in-One User Interface with dynamic Consumer Authentication

All-in-One User Interface with dynamic Consumer Authentication integration

aio_sample.html:

<html>
  <head>
    <title>StitchCredit</title>
    <link rel="icon" href="/favicon.ico" />
    <meta name="description" content="StitchCredit Consumer Credit Reports" />
    <meta
      name="viewport"
      content="minimum-scale=1, initial-scale=1, width=device-width"
    />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        position: relative;
        background: #eeeeee;
      }
      #sc-iframe {
        margin: 0;
        padding: 0;
        z-index: 1;
        width: 100%;
        height: 100vh;
        border: none;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <iframe
      id="sc-iframe" allowTransparency="true"
      src="https://efx-dev.stitchcredit.com/login-aio?key=5a10e0d7-1dc8-4325-929f-d0d131990527"
    ></iframe>
    <script>
    //this just throws in a default ID if one isn't provided on the query string
    const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
    console.log("ID: ",id);
    console.log("Loading Message Listener...");

    window.addEventListener("message", receiveMessage, false);

    function receiveMessage(event) {
        if(event && event.source && event.data) {
            // You only need to implement the types that are important/relevant to your use case.
            if(event.data.type === 'AUTH_REQUIRED') {
                //The iframe clident will post this message when a valid preauth token does not exist.
                //Posting a proper message with a preauth token in response allows the client to continue seemlessly.
                //console.log("Auth Required Event Received");
                const es = event.source;
                //this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
                //This is ONLY for testing and does not exist in the production environment.
                getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
                    const token = JSON.parse(this.responseText).token;
                    console.log("Status: ", this.status, ", token: ", token);
                    es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
                });
            }
            else if(event.data.type === 'REG_STARTED') {
                //only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
                es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "bryan+21@test.com", mobile: "0000000000"}},"*");
            }
            else if(event.data.type === 'IDENTITY_STARTED') {
                //You could use this function to pre-populate the given fields.  DoB and SSN will never be prepopulated as it violates compliance
                es.postMessage({type: 'IDENTITY', data: {street1:"", street2: "", city: "", state: "", zip: ""}},"*");
            }
            else if(event.data.type === 'LOGIN_SUCCESSFUL') {
                console.log("User succesfully logged in");
            }
            else if(event.data.type === 'LOGIN_FAILED') {
                //if you see this message more than a few times in a row, it's likely an issue
                //typically this will only occur for full web implementations, not Direct API
                console.log("User login failed");
            }
            else if(event.data.type === 'USER_ENROLLED') {
                //User successfully completed identity and has been enrolled for consumer data
                console.log("User enrollment successful");
            }
            else if(event.data.type === 'IDENTITY_FAILED') {
                //Identity process failed, user is likely "stuck" as they cannot continue
                console.log("User identity failure");
            }
            else if(event.data.type === 'SERVICE_FAILURE') {
                //Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
                console.log("Identity service failure");
            }
        }

        function getData(req, action) {
        var xhr = new XMLHttpRequest();
            xhr.responesType = 'json';
            xhr.onload = action;
            xhr.open("GET", req);
            xhr.setRequestHeader("Content-Type", "application/json");
            xhr.send();
        }

    }
    </script>
  </body>
</html>

Tile User Interface with dynamic Consumer Authentication

Tile User Interface with dynamic Consumer Authentication integration

tile_sample.html:

<html>
  <head>
    <title>StitchCredit</title>
    <link rel="icon" href="/favicon.ico" />
    <meta name="description" content="StitchCredit Consumer Credit Reports" />
    <meta
      name="viewport"
      content="minimum-scale=1, initial-scale=1, width=device-width"
    />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        position: relative;
        background: #eeeeee;
      }
      #sc-iframe {
        display:block;
        margin: 0 auto;
        padding: 0;
        z-index: 1;
        width: 500px;
        height: 675px;
        border: none;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <iframe
      id="sc-iframe" allowTransaparency="true"
      src="https://efx-dev.stitchcredit.com/login-tile?key=5a10e0d7-1dc8-4325-929f-d0d131990527"
    ></iframe>
    <script>
    //this just throws in a default ID if one isn't provided on the query string
    const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
    console.log("ID: ",id);
    console.log("Loading Message Listener...");

    window.addEventListener("message", receiveMessage, false);

    function receiveMessage(event) {
        if(event && event.source && event.data) {
            // You only need to implement the types that are important/relevant to your use case.
            if(event.data.type === 'AUTH_REQUIRED') {
                //The iframe clident will post this message when a valid preauth token does not exist.
                //Posting a proper message with a preauth token in response allows the client to continue seemlessly.
                //console.log("Auth Required Event Received");
                const es = event.source;
                //this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
                //This is ONLY for testing and does not exist in the production environment.
                getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
                    const token = JSON.parse(this.responseText).token;
                    console.log("Status: ", this.status, ", token: ", token);
                    es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
                });
            }
            else if(event.data.type === 'REG_STARTED') {
                //only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
                es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "bryan+21@test.com", mobile: "0000000000"}},"*");
            }
            else if(event.data.type === 'IDENTITY_STARTED') {
                //You could use this function to pre-populate the given fields.  DoB and SSN will never be prepopulated as it violates compliance
                es.postMessage({type: 'IDENTITY', data: {street1:"", street2: "", city: "", state: "", zip: ""}},"*");
            }
            else if(event.data.type === 'LOGIN_SUCCESSFUL') {
                console.log("User succesfully logged in");
            }
            else if(event.data.type === 'LOGIN_FAILED') {
                //if you see this message more than a few times in a row, it's likely an issue
                //typically this will only occur for full web implementations, not Direct API
                console.log("User login failed");
            }
            else if(event.data.type === 'USER_ENROLLED') {
                //User successfully completed identity and has been enrolled for consumer data
                console.log("User enrollment successful");
            }
            else if(event.data.type === 'IDENTITY_FAILED') {
                //Identity process failed, user is likely "stuck" as they cannot continue
                console.log("User identity failure");
            }
            else if(event.data.type === 'SERVICE_FAILURE') {
                //Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
                console.log("Identity service failure");
            }
        }

        function getData(req, action) {
        var xhr = new XMLHttpRequest();
            xhr.responesType = 'json';
            xhr.onload = action;
            xhr.open("GET", req);
            xhr.setRequestHeader("Content-Type", "application/json");
            xhr.send();
        }

    }
    </script>
  </body>
</html>

Tile User Interface with dynamic Consumer Authentication integration and configuration display flags override

Tile User Interface with dynamic Consumer Authentication integration and configuration display flags override

tile_sample_score_only.html:

<html>
  <head>
    <title>StitchCredit</title>
    <link rel="icon" href="/favicon.ico" />
    <meta name="description" content="StitchCredit Consumer Credit Reports" />
    <meta
      name="viewport"
      content="minimum-scale=1, initial-scale=1, width=device-width"
    />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        position: relative;
        background: #eeeeee;
      }
      #sc-iframe {
        display:block;
        margin: 0 auto;
        padding: 0;
        z-index: 1;
        width: 500px;
        height: 550px;
        border: none;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <iframe
      id="sc-iframe" allowTransaparency="true"
      src="https://efx-dev.stitchcredit.com/login-tile?key=5a10e0d7-1dc8-4325-929f-d0d131990527&ocf=1"
    ></iframe>
    <script>
    //this just throws in a default ID if one isn't provided on the query string
    const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
    console.log("ID: ",id);
    console.log("Loading Message Listener...");

    window.addEventListener("message", receiveMessage, false);

    function receiveMessage(event) {
        if(event && event.source && event.data) {
            // You only need to implement the types that are important/relevant to your use case.
            if(event.data.type === 'AUTH_REQUIRED') {
                //The iframe clident will post this message when a valid preauth token does not exist.
                //Posting a proper message with a preauth token in response allows the client to continue seemlessly.
                //console.log("Auth Required Event Received");
                const es = event.source;
                //this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
                //This is ONLY for testing and does not exist in the production environment.
                getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
                    const token = JSON.parse(this.responseText).token;
                    console.log("Status: ", this.status, ", token: ", token);
                    es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
                });
            }
            else if(event.data.type === 'REG_STARTED') {
                //only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
                es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "bryan+21@test.com", mobile: "0000000000"}},"*");
            }
            else if(event.data.type === 'IDENTITY_STARTED') {
                //You could use this function to pre-populate the given fields.  DoB and SSN will never be prepopulated as it violates compliance
                es.postMessage({type: 'IDENTITY', data: {street1:"", street2: "", city: "", state: "", zip: ""}},"*");
            }
            else if(event.data.type === 'LOGIN_SUCCESSFUL') {
                console.log("User succesfully logged in");
            }
            else if(event.data.type === 'LOGIN_FAILED') {
                //if you see this message more than a few times in a row, it's likely an issue
                //typically this will only occur for full web implementations, not Direct API
                console.log("User login failed");
            }
            else if(event.data.type === 'USER_ENROLLED') {
                //User successfully completed identity and has been enrolled for consumer data
                console.log("User enrollment successful");
            }
            else if(event.data.type === 'IDENTITY_FAILED') {
                //Identity process failed, user is likely "stuck" as they cannot continue
                console.log("User identity failure");
            }
            else if(event.data.type === 'SERVICE_FAILURE') {
                //Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
                console.log("Identity service failure");
            }
        }

        function getData(req, action) {
        var xhr = new XMLHttpRequest();
            xhr.responesType = 'json';
            xhr.onload = action;
            xhr.open("GET", req);
            xhr.setRequestHeader("Content-Type", "application/json");
            xhr.send();
        }

    }
    </script>
  </body>
</html>

Getting Started

  • Access Credentials will be sent to you in a Postman Environment upon registration via email.
    • The Postman Environment is pre-configured to allow you to use the scripts and walk through the Postman Scripts with minimal intervention to aid in understanding the API call structure.
  • The Consumer Credit - Getting Started - New User.postman_collection.json will walk you through the Create New User steps in order
  • The Consumer Credit - Getting Started - Returning User.postman_collection.json will walk you through the Returning User steps in order
  • In the test environment it is important that you use the User Test Identity provided to you verbatim.
    • You may change the email address and phone number ONLY

Basic Steps To Create New Users & Returning Users (Including Data Access Steps):

Creating New Users:

  • Direct API

    • Customer Login
    • Register New User
  • User API

    • Preauth Token
    • User Identity
    • Phone Verify
    • Send Mobile Code
    • Verify Mobile Code
    • Get EFX Config
  • EFX API

    • OAUTH Token
      • Credit Score Latest
        • Credit Score History
        • Credit Report List
          • Credit Report Summary
          • Credit Report (First in list) - PRINT

    When creating creating a new user:

    • Be sure to save the userId when Registering a New User or you will not be able to generate a returning token for the user

    • Once you create a user the identity information is hashed and used to verify if the same identity is being re-enrolled.

    • If a matching hash is found it will skip the identification process.

      • This is great in production, but may limit your ability to test.
      • To get past this, just add a number to the USER_STREET_2 and increment it each time you register a new user and want to go through the full authentication process.
    • On Register New User - change the email to your email.

      • You may add a +1, +2, etc to keep reusing the same email address (ex: test+1@test.com)
    • On Register New User & User Identity - change the phone number to your mobile phone number or you won't receive the SMS messages.

    • Using the Phone Verify, Send Mobile Code, Verify Mobile Code method, the code in the test system passes through,

      • so you can just keep clicking the send on those functions, though you will receive the text as well.
    • For the Get Identity Quiz and Verify Identity Quiz methods, you will need to find the correct answers and update the Verify Identity Quiz body accordingly to successfully authenticate using those methods.

    • When registering a new user, be sure to save the userId or you will not be able to log that user in later.

      • As a matter of security, we do not allow the listing of user IDs.
    • REMEMBER - you MUST use the test user data EXACTLY as it is provided. Only the phone number and email should be changed.

    Returning Users:

    • Direct API
      • Customer Login
      • New User Token
    • User API
      • Preauth Token - if (idpass=false), the next four calls would need to be made, otherwise skip to Get EFX Config if true)
      • User Identity
      • Phone Verify
      • Send Mobile Code
      • Verify Mobile Code
      • Get EFX Config
    • EFX API
      • OAUTH Token
        • Credit Score Latest
        • Credit Score History
        • Credit Report List
          • Credit Report Summary
          • Credit Report (First in list) - PRINT

Direct API Integration Guide

  • A token from /direct/login is required for all other Direct API end-points in yellow.
    • It is a bearer authorization token
  • Once you have a preauth token, returned from /direct/user-reg or /direct/preauth-token, pass it to the consumer and have the consumer app complete the calls directly to the User API end-points in light blue.
  • Be sure to save the ID returned from user-reg or you won’t be able to reauthorize the user when they return.
  • User API end-points in gray are not available for use when Direct API calls are in play.
  • All end-points in light blue are available to the consumer
  • Equifax end-points are accessible first using the User API /users/efx-config response data and the Equifax /oauth/token calls.
  • User API and Equifax calls are intended to be called directly from the end-client. It is not acceptable to pass any of the data to these calls or responses from these calls to your server.
  • Do not save any data. Short term caching is fine, but long-term storage is not.
  • **The preauth token is only valid for 30 seconds

Direct API End-points:

Customer Login
/direct/login
Register New User
New User Token
Change Email
Change Phone
Close Account
Update Refresh
/direct/user-reg
/direct/preauth-token
/direct/change-email
/direct/change-phone
/direct/close-account
/direct/update-refresh [PREMIUM FEATURE]

User API End-points:

Preauth Token
User Identity
Phone Verify
Send Mobile Code
Renew Mobile Code
Verify Mobile Code
Get Identity Quiz
Verify Identity Quiz
Get EFX Config
/users/preauth-token
/users/identity
/users/get-mobile
/users/send-code
/users/renew-code
/users/verify-code
/users/get-quiz
/users/verify-quiz
/users/efx-config
Start
Initialize
Customer Login
Register New User
Password Recovery
Recovery Token Verify
Password Reset
Action Token
Change Email
Change Phone
Change Password
Change Recovery
Close Account
/users/start
/users/initialize
/users/login
/users/register
/users/password-recovery
/users/recovery-token
/users/password-reset
/users/action-token
/users/change-email
/users/change-phone
/users/change-password
/users/change-recovery
/users/close-account

Equifax API End-points:

Delivery Token
Credit Alerts
Credit Score
Credit Score History
Credit Report List
Credit Report
Credit Report Summary
Credit Report PDF
/oauth/token
/v1/creditMonitoring
/v1/creditScore
/v1/creditScore/history
/v1/creditReport
/v1/creditReport/{reportId}
/v1/creditReport/{reportId}/summary
/v1/creditReport/{reportId}/print

Update Data Refresh Date [PREMIUM FEATURE]

  • A consumer’s score & report data refresh date is set based on the enrollment date.
  • The purpose of this endpoint is to reset the refresh date and/or pull a new score & report at a new date.
  • For users who register prior to the desired refresh date, remove their features at the end of the month and re-add them on desired refresh date the following month.
    • To remove, must use /update-refresh?rmonly=true
  • For users who register after the refresh date, their features may be removed and re-added on the desired refresh date the following month.
    • To remove and read use /update-refresh

Change User Host

  • Configurations are grouped and referred to as hosts
  • Move users between hosts to change feature sets

App Integration

Sign Up


Image of page example for Sign Up
Image of page example for Registering Terms of Use

Login

Image of credit report page example

Identity

  • Consumers must be notified and express specific consent to access third party data to verify identity

  • Required Identity Consent language:

    You understand that by clicking “Continue”, you are explicitly agreeing to and providing “written instructions” to StitchCredit under the Fair Credit Reporting Act to obtain my credit information from one or more of the three nationwide credit reporting agencies. Third-party sources, including your mobile carrier may be used to verify your identity. You authorize StitchCredit to obtain such information for you to confirm your identity, and, for as long as you are a member of StitchCredit, to provide you with your credit information. You may elect to terminate your account and this authorization at any time.

    Image of identity page example
    Image of page example for consumer consent language

Mobile Verification

Mobile Identity Consent language:

We will attempt to verify your identity by sending a text with a one-time code to your mobile phone number ending in xxxx.

Message and data rates may apply.

Image of page for sending code via SMS to verify identity
Image of page for entering identity verifying code via SMS

Identification Quiz

Image of page for identification quiz
Image of page for successful sign up as a result of successful identification

Dashboard/Score

Image of page for showing dashboard of scores returned by various bureaus
Image of page for showing score returned by a single bureaus

Reports

Image of page for showing report summary
Image of page for showing score credit accounts

Monitoring

Image of page showing credit monitoring

ID Restoration

Image of page showing ID restoration

Communication & Token Flow

  • The objective of using tokens is to reduce the use of API Keys and/or Password tokens, improving security by reducing exposure
  • Tokens further optimize the performance of the system by reducing the number of authentication lookups necessary to complete a request
  • Multiple different tokens are used to secure different systems and aspects of the application
  • The Direct Token is used to secure YOUR credentials and access - Your API Key, Secret and the Tokens generated should never leave your server
  • The Direct API is used to generate pre-auth tokens for consumer client access
  • Preauth tokens are intended to be sent to the client and exchanged for a user token. They expire quickly and should be exchanged for user tokens right away
  • User tokens are intended for client API access
  • EFX Config data is used to retrieve an Equifax OAuth Delivery token
  • The EFX OAuth Delivery token is locked to the IP that requests it and cannot be used from any other IP
  • The EFX OAuth Delivery token is required for all Equifax API Requests

Compliance

  • Consumers must always know who they are dealing with
    • Terms of Use and Privacy Policy are from and through StitchCredit – there is no ability to white label this at this time
  • Content delivered to users must not be misleading in any way
  • Consumers must know where the data came from
  • Pages with consumer credit data must be compliant with all data presentation requirements and restrictions, no matter how small
  • Customers may not access consumer data at any time
  • Saving data at any time is NOT PERMITTED under any circumstances
  • Login security must be present:
    • Account lockout after 5 consecutive failed attempts
    • Multi-step account recovery process

Registration

Image of page example for Sign Up
Image of page example for Registering Terms of Use

Identity

  • Consumers must be notified and express specific consent to access third party data to verify identity

    You understand that by clicking “Continue”, you are explicitly agreeing to and providing “written instructions” to StitchCredit under the Fair Credit Reporting Act to obtain my credit information from one or more of the three nationwide credit reporting agencies. Third-party sources, including your mobile carrier may be used to verify your identity. You authorize StitchCredit to obtain such information for you to confirm your identity, and, for as long as you are a member of StitchCredit, to provide you with your credit information. You may elect to terminate your account and this authorization at any time.

    Image of identity page example
    Image of page example for consumer consent to access third party data to verify identity

Mobile Identification (Option 1)

  • Users must consent to receiving an SMS message for authentication – note that not all users will qualify to do mobile identification, roughly 60% do at the moment.

    We will attempt to verify your identity by sending a text with a one-time code to your mobile phone number ending in xxxx.


    Message and data rates may apply.
    Image of mobile identification page example

Identity Quiz (Option 2)

  • Users who don’t qualify or are unable to pass mobile verification must pass an identity quiz.
  • Users will have at most 2 chances to pass a quiz, assuming enough questions can be generated.
  • Users may re-enter and try to pass the identity quiz again, however two attempts (2 chances each) is the limit and will result in a 72-hr lockout.
    Image of identity quiz page example

Credit Score - Dashboard

  • The provider of the score is required – do not use a logo, you must have marketing approval from a bureau to use their logo
  • VantageScore 3.0 – must be present, just like that (VantageScore is one word and it’s a brand, ignore the mistake in this image)
  • The date the score was pulled is required
  • The date the next score will be available is strongly encouraged, this is based on the weekly or monthly refresh you subscribe to
  • VantageScore 3.0 is known as an “educational score” and may differ from the Fico Score used to determine credit availability – notice must be given
    Image of credit score dashboard page example

Credit Report

  • The provider of the report is required
  • The date the report was pulled is required
    Image of credit report page example

Credit Monitoring

  • The provider of the alert is required
  • The date of the alert is required
    Image of credit report page example

Identity Restoration

  • This product content must be delivered as is
  • Equifax® ID Restoration
  • Has your identity been compromised?
  • A specialist will help you work through the process.
  • Once your issues are resolved, we continue to monitor the situation for three months.
  • Call today so that we may help you verify and begin resolving any discrepancies.
  • Call 1-877-368-4940 today to get started
Image of identity restoration page example

API Process Flow

Direct API

Collection of end-points that should be called from your server.

Customer Login

/direct/login

  • Using your credentials in the request body ("apikey" and "secret"), the response will contain the token and refresh token.
  • These tokens are required for completing the other requests to Direct API endpoints.
  • This token will be valid for approximately one hour.
  • After the one hour, the refresh token will become valid.
  • If the token expires, use /direct/refresh-token?token={refresh} to get a new token
Request Body schema: application/json

Add your credentials to "apikey" and "secret".
(keep these credentials a secret)

secret
required
string
apikey
required
string

Responses

Request samples

Content type
application/json
{
  • "secret": "{{SECRET}}",
  • "apikey": "{{API_KEY}}"
}

Customer Refresh Token

/direct/refresh-token

query Parameters
token
required
string
Example: token={{rdtoken}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Register New User

/direct/user-reg

  • Creates a new user with unique userId and preauth token.
  • When a user logs back in, use /direct/preauth-token/{userId} to generate that user a new preauth token and a new userId (refer to Returning User)

Don't store the token across sessions.
Use the userId from the previous session to generate a new userId and a new preauth token.

Request Body schema: application/json
email
required
string
fname
required
string
lname
required
string
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "{{USER_EMAIL}}",
  • "fname": "{{USER_FNAME}}",
  • "lname": "{{USER_LNAME}}",
  • "mobile": "{{USER_MOBILE}}"
}

New User Token

/direct/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Close User Account

/direct/close-account/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Change User Email

/direct/change-email/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "test@test.com"
}

Change User Phone

/direct/change-mobile/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "mobile": "1234567890"
}

Change User Host

/direct/change-host/{userId}

path Parameters
userId
required
string
query Parameters
host
required
string
Example: host={{HOST_ID}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Update User Refresh Date

/direct/update-refresh/{userId}

*Premium Feature - May Require Additional Access

path Parameters
userId
required
string
query Parameters
rmonly
required
boolean
Example: rmonly=false
header Parameters
Content-Type
required
string
Example: application/json

Responses

Get Alert Detail

/direct/efx-alert/{alertId}

*Premium Feature - May Require Additional Access

path Parameters
alertId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

User API

Collection of end-points that should be called from the consumer app.

Preauth Token

/users/preauth-token/{paToken}

  • This request uses userId (from the response of /direct/user-reg) to generate a User Token.

  • The User Token is a bearer token that must be passed to the consumer's device so that the consumer app can directly complete User API requests.

The Preauth Token needed for this request is also generated by /direct/user-reg or /direct/preauth-token

path Parameters
paToken
required
string

Responses

User Identity

/users/identity

  • This endpoint is most useful for checking whether the user's identity needs to be verified.
  • If the response has idpass set to true, then the user's identity is already verified.
  • If idpass is false, then the user's identity needs to be verified.
    • The user's identity can then be verified with either:
      • /users/get-mobile (phone sms verification)
      • /users/get-quiz (an identity quiz)
  • The user's identity must be verified in order to enable the user's device to request the Equifax config data.
    • The data in the Equifax config provides the necessary credentials for making requests to the Equifax API from the consumer's device.
Request Body schema: application/json
ssn
required
string
dob
required
string
mobile
required
string
street1
required
string
street2
required
string
city
required
string
state
required
string
zip
required
string

Responses

Request samples

Content type
application/json
{
  • "ssn": "{{USER_SSN}}",
  • "dob": "{{USER_DOB}}",
  • "mobile": "{{USER_MOBILE}}",
  • "street1": "{{USER_STREET1}}",
  • "street2": "{{USER_STREET2}}",
  • "city": "{{USER_CITY}}",
  • "state": "{{USER_STATE}}",
  • "zip": "{{USER_ZIP}}"
}

Phone Verify

/users/get-mobile

header Parameters
Content-Type
required
string
Example: application/json

Responses

Send Mobile Code

/users/send-code/{mtoken}

path Parameters
mtoken
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Renew Mobile Code

/users/renew-code

Request Body schema: application/json
key
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "{{mTransactionKey}}"
}

Verify Mobile Code

/users/verify-code

Request Body schema: application/json
key
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "{{mTransactionKey}}",
  • "code": "{{passcode}}"
}

Get Identity Quiz

/users/get-quiz

header Parameters
Content-Type
required
string
Example: application/json

Responses

Verify Identity Quiz

/users/verify-quiz

Request Body schema: application/json
key
required
string
id
required
string
required
Array of objects (Answer)

Responses

Request samples

Content type
application/json
{
  • "key": "{{qTransactionKey}}",
  • "id": "{{qzId}}",
  • "answers": [
    ]
}

Get EFX Config

/users/efx-config

  • Use this endpoint to get the Equifax credentials and url
    • These will be needed for the consumer app to send requests to the Equifax API.
header Parameters
Content-Type
required
string
Example: application/json

Responses

Equifax API

OAUTH Token

/{efx_url}/oauth/token

  • For this path parameter, {efx_url}, use the url found in the response of a call to /users/efx-config.
  • A successful request to {efx_url}/oauth/token will return credentials required for other Equifax API calls.
path Parameters
efx_url
required
string
Example: https://api.efx-url.com/consumer-data
Request Body schema: application/x-www-form-urlencoded
scope
required
string
grant_type
required
string
api_key
required
string
client_assertion
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "access_token": "87e22d35-0089-4613-809b-62f248c2c978",
  • "token_type": "bearer",
  • "expires_in": 610,
  • "scope": "read write"
}

Health Check

/{efx_url}/v1/creditMonitoring/healthcheck

query Parameters
format
required
string
Example: format=json
header Parameters
Content-Type
required
string
Example: {{content-type}}

Responses

Credit Monitoring

/{efx_url}/v1/creditMonitoring

query Parameters
format
required
string
Example: format=json

Responses

CreditReportList

/{efx_url}/v1/creditReport

query Parameters
format
required
string
Example: format=json

Responses

Credit Report Summary (First in list)

/{efx_url}/v1/creditReport/{reportId}/summary

path Parameters
reportId
required
string
query Parameters
format
required
string
Example: format=json

Responses

Full Credit Report (First in list)

/{efx_url}/v1/creditReport/{reportId}

path Parameters
reportId
required
string
query Parameters
format
required
string
Example: format=json

Responses

Credit Report (First in list) - PRINT

/{efx_url}/v1/creditReport/{reportId}/print

path Parameters
reportId
required
string
query Parameters
access_token
required
string
Example: access_token={{efxtoken}}

Responses

Credit Score Latest

/{efx_url}/v1/creditScore/latest

query Parameters
format
required
string
Example: format=json

Responses

Credit Score History

/{efx_url}/v1/creditScore/history

query Parameters
historicalLimit
required
integer <int32>
Example: historicalLimit=24
format
required
string
Example: format=json

Responses

Test API

Collection of end-points for testing webhooks

New Pre-auth Token

/test/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Test

/test/webhook/send/{userId}

path Parameters
userId
required
string
query Parameters
count
required
integer <int32>
Example: count=1
type
required
string
Example: type=NEW_ACCOUNT
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Sink

/test/webhook/sink

Request Body schema: application/json
Array ()
type
required
string
user_id
required
string
time
required
string
error_code
required
string
error_msg
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Getting Started - Create New User

Customer Login

/direct/login

  • Using your credentials in the request body ("apikey" and "secret"), the response will contain the token and refresh token.
  • These tokens are required for completing the other requests to Direct API endpoints.
  • This token will be valid for approximately one hour.
  • After the one hour, the refresh token will become valid.
  • If the token expires, use /direct/refresh-token?token={refresh} to get a new token
Request Body schema: application/json

Add your credentials to "apikey" and "secret".
(keep these credentials a secret)

secret
required
string
apikey
required
string

Responses

Request samples

Content type
application/json
{
  • "secret": "{{SECRET}}",
  • "apikey": "{{API_KEY}}"
}

Register New User

/direct/user-reg

  • Creates a new user with unique userId and preauth token.
  • When a user logs back in, use /direct/preauth-token/{userId} to generate that user a new preauth token and a new userId (refer to Returning User)

Don't store the token across sessions.
Use the userId from the previous session to generate a new userId and a new preauth token.

Request Body schema: application/json
email
required
string
fname
required
string
lname
required
string
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "{{USER_EMAIL}}",
  • "fname": "{{USER_FNAME}}",
  • "lname": "{{USER_LNAME}}",
  • "mobile": "{{USER_MOBILE}}"
}

Preauth Token

/users/preauth-token/{paToken}

  • This request uses userId (from the response of /direct/user-reg) to generate a User Token.

  • The User Token is a bearer token that must be passed to the consumer's device so that the consumer app can directly complete User API requests.

The Preauth Token needed for this request is also generated by /direct/user-reg or /direct/preauth-token

path Parameters
paToken
required
string

Responses

User Identity

/users/identity

  • This endpoint is most useful for checking whether the user's identity needs to be verified.
  • If the response has idpass set to true, then the user's identity is already verified.
  • If idpass is false, then the user's identity needs to be verified.
    • The user's identity can then be verified with either:
      • /users/get-mobile (phone sms verification)
      • /users/get-quiz (an identity quiz)
  • The user's identity must be verified in order to enable the user's device to request the Equifax config data.
    • The data in the Equifax config provides the necessary credentials for making requests to the Equifax API from the consumer's device.
Request Body schema: application/json
ssn
required
string
dob
required
string
mobile
required
string
street1
required
string
street2
required
string
city
required
string
state
required
string
zip
required
string

Responses

Request samples

Content type
application/json
{
  • "ssn": "{{USER_SSN}}",
  • "dob": "{{USER_DOB}}",
  • "mobile": "{{USER_MOBILE}}",
  • "street1": "{{USER_STREET1}}",
  • "street2": "{{USER_STREET2}}",
  • "city": "{{USER_CITY}}",
  • "state": "{{USER_STATE}}",
  • "zip": "{{USER_ZIP}}"
}

Phone Verify

/users/get-mobile

header Parameters
Content-Type
required
string
Example: application/json

Responses

Send Mobile Code

/users/send-code/{mtoken}

path Parameters
mtoken
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Verify Mobile Code

/users/verify-code

Request Body schema: application/json
key
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "{{mTransactionKey}}",
  • "code": "{{passcode}}"
}

Get EFX Config

/users/efx-config

  • Use this endpoint to get the Equifax credentials and url
    • These will be needed for the consumer app to send requests to the Equifax API.
header Parameters
Content-Type
required
string
Example: application/json

Responses

OAUTH Token

/{efx_url}/oauth/token

  • For this path parameter, {efx_url}, use the url found in the response of a call to /users/efx-config.
  • A successful request to {efx_url}/oauth/token will return credentials required for other Equifax API calls.
path Parameters
efx_url
required
string
Example: https://api.efx-url.com/consumer-data
Request Body schema: application/x-www-form-urlencoded
scope
required
string
grant_type
required
string
api_key
required
string
client_assertion
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "access_token": "87e22d35-0089-4613-809b-62f248c2c978",
  • "token_type": "bearer",
  • "expires_in": 610,
  • "scope": "read write"
}

Getting Started - Returning User

Customer Login

/direct/login

  • Using your credentials in the request body ("apikey" and "secret"), the response will contain the token and refresh token.
  • These tokens are required for completing the other requests to Direct API endpoints.
  • This token will be valid for approximately one hour.
  • After the one hour, the refresh token will become valid.
  • If the token expires, use /direct/refresh-token?token={refresh} to get a new token
Request Body schema: application/json

Add your credentials to "apikey" and "secret".
(keep these credentials a secret)

secret
required
string
apikey
required
string

Responses

Request samples

Content type
application/json
{
  • "secret": "{{SECRET}}",
  • "apikey": "{{API_KEY}}"
}

New User Token

/direct/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Preauth Token

/users/preauth-token/{paToken}

  • This request uses userId (from the response of /direct/user-reg) to generate a User Token.

  • The User Token is a bearer token that must be passed to the consumer's device so that the consumer app can directly complete User API requests.

The Preauth Token needed for this request is also generated by /direct/user-reg or /direct/preauth-token

path Parameters
paToken
required
string

Responses

Get EFX Config

/users/efx-config

  • Use this endpoint to get the Equifax credentials and url
    • These will be needed for the consumer app to send requests to the Equifax API.
header Parameters
Content-Type
required
string
Example: application/json

Responses

OAUTH Token

/{efx_url}/oauth/token

  • For this path parameter, {efx_url}, use the url found in the response of a call to /users/efx-config.
  • A successful request to {efx_url}/oauth/token will return credentials required for other Equifax API calls.
path Parameters
efx_url
required
string
Example: https://api.efx-url.com/consumer-data
Request Body schema: application/x-www-form-urlencoded
scope
required
string
grant_type
required
string
api_key
required
string
client_assertion
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "access_token": "87e22d35-0089-4613-809b-62f248c2c978",
  • "token_type": "bearer",
  • "expires_in": 610,
  • "scope": "read write"
}

Direct API

Collection of end-points that should be called from your server.

Customer Login

/direct/login

  • Using your credentials in the request body ("apikey" and "secret"), the response will contain the token and refresh token.
  • These tokens are required for completing the other requests to Direct API endpoints.
  • This token will be valid for approximately one hour.
  • After the one hour, the refresh token will become valid.
  • If the token expires, use /direct/refresh-token?token={refresh} to get a new token
Request Body schema: application/json

Add your credentials to "apikey" and "secret".
(keep these credentials a secret)

secret
required
string
apikey
required
string

Responses

Request samples

Content type
application/json
{
  • "secret": "{{SECRET}}",
  • "apikey": "{{API_KEY}}"
}

Customer Refresh Token

/direct/refresh-token

query Parameters
token
required
string
Example: token={{rdtoken}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Register New User

/direct/user-reg

  • Creates a new user with unique userId and preauth token.
  • When a user logs back in, use /direct/preauth-token/{userId} to generate that user a new preauth token and a new userId (refer to Returning User)

Don't store the token across sessions.
Use the userId from the previous session to generate a new userId and a new preauth token.

Request Body schema: application/json
email
required
string
fname
required
string
lname
required
string
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "{{USER_EMAIL}}",
  • "fname": "{{USER_FNAME}}",
  • "lname": "{{USER_LNAME}}",
  • "mobile": "{{USER_MOBILE}}"
}

New User Token

/direct/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Close User Account

/direct/close-account/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Change User Email

/direct/change-email/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "test@test.com"
}

Change User Phone

/direct/change-mobile/{userId}

path Parameters
userId
required
string
Request Body schema: application/json
mobile
required
string

Responses

Request samples

Content type
application/json
{
  • "mobile": "1234567890"
}

Change User Host

/direct/change-host/{userId}

path Parameters
userId
required
string
query Parameters
host
required
string
Example: host={{HOST_ID}}
header Parameters
Content-Type
required
string
Example: application/json

Responses

Update User Refresh Date

/direct/update-refresh/{userId}

*Premium Feature - May Require Additional Access

path Parameters
userId
required
string
query Parameters
rmonly
required
boolean
Example: rmonly=false
header Parameters
Content-Type
required
string
Example: application/json

Responses

Get Alert Detail

/direct/efx-alert/{alertId}

*Premium Feature - May Require Additional Access

path Parameters
alertId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

User API

Collection of end-points that should be called from the consumer app.

Preauth Token

/users/preauth-token/{paToken}

  • This request uses userId (from the response of /direct/user-reg) to generate a User Token.

  • The User Token is a bearer token that must be passed to the consumer's device so that the consumer app can directly complete User API requests.

The Preauth Token needed for this request is also generated by /direct/user-reg or /direct/preauth-token

path Parameters
paToken
required
string

Responses

User Identity

/users/identity

  • This endpoint is most useful for checking whether the user's identity needs to be verified.
  • If the response has idpass set to true, then the user's identity is already verified.
  • If idpass is false, then the user's identity needs to be verified.
    • The user's identity can then be verified with either:
      • /users/get-mobile (phone sms verification)
      • /users/get-quiz (an identity quiz)
  • The user's identity must be verified in order to enable the user's device to request the Equifax config data.
    • The data in the Equifax config provides the necessary credentials for making requests to the Equifax API from the consumer's device.
Request Body schema: application/json
ssn
required
string
dob
required
string
mobile
required
string
street1
required
string
street2
required
string
city
required
string
state
required
string
zip
required
string

Responses

Request samples

Content type
application/json
{
  • "ssn": "{{USER_SSN}}",
  • "dob": "{{USER_DOB}}",
  • "mobile": "{{USER_MOBILE}}",
  • "street1": "{{USER_STREET1}}",
  • "street2": "{{USER_STREET2}}",
  • "city": "{{USER_CITY}}",
  • "state": "{{USER_STATE}}",
  • "zip": "{{USER_ZIP}}"
}

Phone Verify

/users/get-mobile

header Parameters
Content-Type
required
string
Example: application/json

Responses

Send Mobile Code

/users/send-code/{mtoken}

path Parameters
mtoken
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Renew Mobile Code

/users/renew-code

Request Body schema: application/json
key
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "{{mTransactionKey}}"
}

Verify Mobile Code

/users/verify-code

Request Body schema: application/json
key
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "{{mTransactionKey}}",
  • "code": "{{passcode}}"
}

Get Identity Quiz

/users/get-quiz

header Parameters
Content-Type
required
string
Example: application/json

Responses

Verify Identity Quiz

/users/verify-quiz

Request Body schema: application/json
key
required
string
id
required
string
required
Array of objects (Answer)

Responses

Request samples

Content type
application/json
{
  • "key": "{{qTransactionKey}}",
  • "id": "{{qzId}}",
  • "answers": [
    ]
}

Get EFX Config

/users/efx-config

  • Use this endpoint to get the Equifax credentials and url
    • These will be needed for the consumer app to send requests to the Equifax API.
header Parameters
Content-Type
required
string
Example: application/json

Responses

Equifax API

OAUTH Token

/{efx_url}/oauth/token

  • For this path parameter, {efx_url}, use the url found in the response of a call to /users/efx-config.
  • A successful request to {efx_url}/oauth/token will return credentials required for other Equifax API calls.
path Parameters
efx_url
required
string
Example: https://api.efx-url.com/consumer-data
Request Body schema: application/x-www-form-urlencoded
scope
required
string
grant_type
required
string
api_key
required
string
client_assertion
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "access_token": "87e22d35-0089-4613-809b-62f248c2c978",
  • "token_type": "bearer",
  • "expires_in": 610,
  • "scope": "read write"
}

Health Check

/{efx_url}/v1/creditMonitoring/healthcheck

query Parameters
format
required
string
Example: format=json
header Parameters
Content-Type
required
string
Example: {{content-type}}

Responses

Credit Monitoring

/{efx_url}/v1/creditMonitoring

query Parameters
format
required
string
Example: format=json

Responses

CreditReportList

/{efx_url}/v1/creditReport

query Parameters
format
required
string
Example: format=json

Responses

Credit Report Summary (First in list)

/{efx_url}/v1/creditReport/{reportId}/summary

path Parameters
reportId
required
string
query Parameters
format
required
string
Example: format=json

Responses

Full Credit Report (First in list)

/{efx_url}/v1/creditReport/{reportId}

path Parameters
reportId
required
string
query Parameters
format
required
string
Example: format=json

Responses

Credit Report (First in list) - PRINT

/{efx_url}/v1/creditReport/{reportId}/print

path Parameters
reportId
required
string
query Parameters
access_token
required
string
Example: access_token={{efxtoken}}

Responses

Credit Score Latest

/{efx_url}/v1/creditScore/latest

query Parameters
format
required
string
Example: format=json

Responses

Credit Score History

/{efx_url}/v1/creditScore/history

query Parameters
historicalLimit
required
integer <int32>
Example: historicalLimit=24
format
required
string
Example: format=json

Responses

Test API

Collection of end-points for testing webhooks

New Pre-auth Token

/test/preauth-token/{userId}

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Test

/test/webhook/send/{userId}

path Parameters
userId
required
string
query Parameters
count
required
integer <int32>
Example: count=1
type
required
string
Example: type=NEW_ACCOUNT
header Parameters
Content-Type
required
string
Example: application/json

Responses

Webhook Sink

/test/webhook/sink

Request Body schema: application/json
Array ()
type
required
string
user_id
required
string
time
required
string
error_code
required
string
error_msg
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]