Help & Support

The API Reference, (also known as the API specification) provides users with technical information regarding how to integrate and initiate a product’s API call. Information on the API Reference tab includes:

• Introduction to the product API.

• Open API specifications. (YAML).

• Authentication schemes.

• Sample requests, responses, and error messages.

• Other information or files as appropriate for the specific product.

Where do I find it?

On the APIs product page, access the API Reference tab to the right of Overview.

Additional API Documents

If an API product has additional documents (for example, Product Guide, Mock Test Data, Getting Started procedures, Sequencing documents, etc.), an additional tab is available next to the API Reference tab after sign in.

Where do I find it?

On some API Product pages the Additional Documents tab is displayed, but not all products have additional documents.

Users within the developer portal are defined by roles which align with access privileges.

Account Holder

Every user that is registered with a Developer Portal account. An Account Holder can: 

• View Public Products.

• Access Product Documentation and API Reference when signed-in.

• Access Partner Products if in possession of a Partner Product Code.

• Access Private Products if an Equifax associate.

• Create an App then becomes an App Owner.

App Owners

After an Account Holder creates an app, they become an App Owner.  App Owner privileges include:

• View Public Products.

• Access Partner Products if applicable.

• Access Private Products if applicable.

• Access Product Documentation and API Reference.

• Create Apps.

• Add products to an App.

• Remove products from App.

• Invite and manage Collaborators.

• Access Sandbox credentials.

• Add and manage IP Whitelists.

• Request Tier Promotion of App.

• Use Test and Live credentials for Approved APIs.

Collaborators

An App Owner can designate and invite a Collaborator to have read-only access to an Application along the tier promotion journey. Collaborators are able to:

• View Public Products.

• Have “Read-Only” Access to the invited ‘collaborating’ application.

• Access Product Documentation and API Reference to invited Partner and Private Products.

• Access Sandbox credentials.

• Use Test/Live Credentials for Approved APIs.

Important Information:

• An App Owner can add or remove their Collaborators at any time.

Where do I find it?

Open the App page on your Dashboard. Click Add Collaborator. Enter their email address.

Application Owner Change

App Owners can transfer their ownership of an existing app to another person, if - and only if - that person is already a collaborator. Ownership transfer means the new owner is able to fully manage the app and the current owner is removed entirely from the application.

Important Information:

• Pending ownership change means that the new owner has not yet accepted the change. The existing (prior) owner can cancel the request anytime until new owner acceptance.

• App ownership change does not happen immediately. It is completed overnight after the new owner accepts ownership.

• If the proposed new owner does not accept app ownership after 30 days, the new owner request is removed and must be submitted by the current owner again.

• After change of ownership is approved by the new owner, it cannot be undone.

• For the prior owner to see the App, they must be added as a Collaborator by the new owner.

Where do I find it?

Click to your App page on the Dashboard.

Creating an App

To consume an API, you must create an application on the dashboard and select one or more products. Follow these steps:

1. To create an application, Sign In. Your Dashboard page opens.

2. If you’ve been given a Partner Product Access Code, enter it in the optional field on your Dashboard to gain access to a Partner Product that’s not publicly available. Click Submit.

3. In the Create New Application panel, name  your application in the provided field.

4. Add a Description as appropriate.

5. Click Next. The new app opens on its own page.

Add API Products to your App

1. On the app page, click Add API Product. The Add API Products page opens.

2. Select one or more of the API Products you want to include in your application.

   • If you don’t see a product you are expecting to see, it is likely a Partner product that requires a Partner Product Access Code. Contact your EFX account manager to obtain that code - and then enter it on the Dashboard.

   • You can add as many products as you would like to an app, but if one of the products is not approved for your app, then you will not be able to go live with the others.

3. When done with your product selections, scroll to the bottom of the page and click Add.

4. NOTE - Unless you are only using the "Equifax Gateway (XML Consumer)” product, then you must always include the "Security Service" product in your selections to access the Identity Access Management Systems (IdAMS)

Where do I find it?

Click DASHBOARD on the top navigation of every page.

Client ID and Secret

Equifax uses IdAMS for authentication of API calls - this is the "Security Service" product which needs to be included in every subscription. See here for details of the specs for the Security Service.

Applications which are at the "Sandbox" level will be given IdAMS Client ID and Client Secret to use (see the "My Company Subscriptions" screen) - these details need to be supplied in every API request call. For applications which are at "Test" or "Live" level, you will need your own Client ID and Client Secret, which will be setup by Equifax and provided to you.

If you need to check your IdAMS credentials, please visit the IdAMS portal.

Our authorization server authenticates your application by verifying the supplied Client ID and Client Secret, so please keep these credentials safe.

Important Information:

• This is shown in the Sandbox, but not shown during promotion until the products have been approved.

• Changing the Client Secret will have an effect on your production traffic. Be sure to read the dialogs carefully and be prepared to make the change in your system when you change it here.

• There is no requirement for you cache any authentication tokens, the Equifax API management services will manage token expiry on your behalf, and you will be made aware when a token has expired

Where do I find it?

Click DASHBOARD on the top navigation bar to open your App page.

Reset the Client Secret using the reset API of Security Service. If you do not refresh the client secret manually, IDAMS will refresh it automatically every 30 days.

Scope and Endpoints

API Scope

Scope is used to limit access for OAuth tokens. The scope parameter in an oAuth request allows the application to express the desired scope of the access request. 

The scope value can in turn be mapped to API resources, and used to validate an API request by a client, to ensure that the client has access to the API resource before allowing the API call to proceed.

The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.

Scope Sequence Example:

• Token request is made using scope=api.equifax.com/business/staffing/talent-reports

• A token is generated and sent back to the client in response to the Oauth token call.

• This token is subsequently used to access the API via the URL api.equifax.com/business/staffing/talent-reports. Since the token has been granted access to the URL via the scope parameter, the API proxy code upon inspecting the token will allow the API call to proceed.
  NOTE: The API proxy code can be programmed to disallow access to any other token that does not have the scope for this URL associated with it.

Important Information:

• The Scope for your App is shown under the given product listed on the App page.

• The Endpoints, for a given product, can be found within the API Reference on the product overview page.

API Endpoints

An endpoint is one end of an API interaction. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. Each endpoint is the location from which APIs can access the resources they need to carry out their function.

APIs work using ‘requests’ and ‘responses.’ When an API requests information from a web application or web server, it will receive a response. The place that APIs send requests and where the resource lives, is called an endpoint.

Endpoint Example:

• Client makes an API GET call to api.equifax.com/business/staffing/talent-reports
  In this case, api.equifax.com/business/staffing/talent-reports is the endpoint of the API call, to which the client connects to access the resource.

Important Information:

• The Endpoints can be found within the API Reference on the certain product's overview page.

Where do I find it?

Each Application page has links to the API Product page(s). The endpoints are within the API Reference for each product.

Hiding and Deleting Apps

The App Owner can view, hide, deactivate, or delete their apps at any time. Collaborators can only hide apps from their own Dashboard, but cannot deactivate, or delete apps.

The Dashboard shows all the Apps that you have created, or have been named a Collaborator. App owners can hide apps from view, deactivate, or delete apps:

• To hide an app from view, but not stop production traffic, select the app (checkbox), then click Hide. The app is moved  under the HIDDEN APPS tab.

• Deactivating an app stops production traffic!
  To deactivate a hidden app, click the app, then on the app page, click the (dotted) menu next to the Current Environment: field  and select Deactivate.

• Deleting an App stops production traffic and removes the app from the system entirely!  
  To delete a deactivated app, click the app, then on the app page, click the (dotted) menu next to the Current Environment field  and select Delete.

Important Information:

You can only Delete Apps that have been Deactivated. This step by step approach assists with mistakenly deleting an app you need.

Where do I find it?

Click DASHBOARD  on the top navigation bar to open your App page.

In order to evaluate or consume Equifax API products, you must establish a connection between your system and the API product. This is done by creating an App that contains one or more of the API Products.

After you have created your app in the Sandbox environment, you can promote it to the test environment and ultimately to production.

Environments Available

We support the following environments for all our API Products, however, you need credentials to test and consume them. A summary of each environment is described below.

Sandbox

• Username and password for the API portal.

• Base URL: https://api.sandbox.equifax.co.uk

• API credentials (Client ID and Client Secret): Available upon creation of an App.

• Data: Only mocked responses.

• Cost: None.

• Usage Constraints: None.

Test

• Base URL: https://api.uat.equifax..co.uk

• API credentials (Client ID and Client Secret): Available after App Tier Promotion Request is Approved.

• Data: Realistic test data.

• Cost: None.

• Usage Constraints: None.

Live

• Base URL: https://api.equifax.co.uk

• API credentials (Client ID and Client Secret): Available after App Tier Promotion Request is Approved.

• Data: Real production data.

• Additional security: Ability to whitelist IPs.

• Cost: Varies according to the API product. Please contact your Equifax representative.

• Usage constraints: Please contact your Equifax representative.

Tier Promotion

After you are done experimenting with the API products using mock data in the Sandbox environment, you can submit a request to promote your App to the Test environment and experiment with the products using realistic test data. After you are done testing the API products in the test environment you can submit a request to promote your App to the Live environment and then consume real live API data returned by the products in your App.

Important Information:

• Your request will be reviewed by our Sales and/or Operations team to verify that you are entitled to consume the API Products in your App. Therefore it is important you provide complete and accurate information in your My Company Profile.

• The amount of time it takes to complete the verification above depends on whether your company has an existing relationship with Equifax - and the type of API products you are seeking to test and/or consume.  See Becoming a Customer, at the top of this page, for a high-level overview of this process.

• After the criteria above is satisfied, you will receive an email notifying you whether your request was approved or rejected for each API product in your app. If you have any problems with any of the steps above, contact your Equifax account manager.

Promoting your App from Sandbox to Test Environment:

1. Navigate to your App on your portal Dashboard.

2. Click on Promote to Test button

3. Select your targeted Go Live date. This is only collected for informational purposes. It does not guarantee your request will be approved by this date.

4. Enter and manage whitelist IPs from which your system will be calling our API Products. This information ensures an additional layer of security. These are specific to the Test environment and will not persist when promoting to the next environment.

5. Please note: Test IdAMS credentials are required for promotion to Test. These will be provided to you by Equifax.

6. Click Submit. You will receive a confirmation email.

7. If your test promotion request is approved, your App Status will change to Pending in Test and your App Environment will change to Test. You will be notified by email and you will be able to view your App’s Client ID and Secret. You can use this Client ID and Secret to connect your system to the approved API Products in your App.
   NOTE: If no one has reached out to you or your developer within 48 hours of your developer portal application tier promotion request, please reach out to our sales team via the Contact Us form. If you have any problems with any of the steps above, contact your Equifax account manager.

8. If your request is rejected you will be notified by email and you will not be able to test/consume the rejected API Product(s) in your App.

Promoting your App from Test to Live Environment:

1. Navigate to your App on your portal Dashboard.

2. Click on Promote to Live button

3. Update your targeted Go Live date. This is only collected for informational purposes. It does not guarantee your request will be approved by this date.

4. Enter (or update your previously entered) whitelist IPs from which your system will be calling our API Products. This information ensures an additional layer of security.

5. Please note: Live IdAMS credentials are required for promotion to Live. These will be provided to you by Equifax.

6. Click Submit. You will receive a confirmation email.

7. If your Live promotion request is approved, your App Status will change to Pending in Live and your App Environment will change to Live. You will be notified by email and you will be able to view your App’s Client ID and Secret. You can use this Client ID and Secret to connect your system to the approved API Products in your App.
   NOTE: After the criteria above is satisfied, you will receive an email notifying you whether your request was approved or rejected for each API product in your app. If you have any problems with any of the steps above, contact your Equifax account manager.

8. If your request is rejected you will be notified by email and you will not be able to test/consume the rejected API Products in your App.

Authorization

Equifax uses OAuth 2.0, an industry-standard protocol that allows Equifax to grant permission for access to our products and services without sharing unique credentials with a third party. The protocol defines a process that allows limited access to resources hosted by web-based services accessed over HTTP. Tokens assigned to authenticated clients are required to access all protected resources.

OAuth 2.0 Grant Type

The type of access called “OAuth 2.0 grant type” used for Equifax APIs is client credentials – here the username and password are not required. Rather, you obtain the Access Token by providing only the client_id, client_secret, and the scope.

Setting up OAuth 2.0 requires getting credentials, requesting an Access Token, and accessing protected resources.

Client ID and Client Secret

Equifax uses IdAMS for authentication of API calls - this is the "Security Service" product which needs to be included in every subscription. See here for details of the specs for the Security Service.

You must have an approved set of IdAMS credentials (Client ID and Client Secret) for an environment to access it.

When you Create an App, Equifax assigns a Client ID and Client Secret for each environment for the API Products you want to access.

Our authorization server authenticates your application request by verifying the supplied Client ID and Client Secret, so please keep these credentials safe.

Access Token

You must make a POST call to the token endpoint of the Authorization Server to generate an Access Token. Credentials and other parameters must be passed depending on the Authorization Server supported by the API Products in your App.

Access tokens are mapped to your credentials and determine your authorization to call the approved API Products in your App. To call APIs in an environment, you must obtain a token from that environment.

Access Protected Resources:

All requests made to Equifax APIs must contain a valid Access Token. Requests with invalid tokens will be denied access to the resource with the API, returning HTTP 401 status code.

Security Certificates

In order for customers to have a trusted connection with an Equifax API, they must utilize the updated Sectigo certificates.

To import the required certificates into your organization's trust store, perform the steps below.

1. Navigate to the Sectigo Intermediate Certificates - RSA Support and download the specific certificates described in the next two steps.

2. Under Organization Validation, click [Download] Sectigo RSA Organization Validation Secure Server CA [ Intermediate ]

3. Under Root Certificates, click [Download] SHA-2 Root : USERTrust RSA Certification Authority

The accepted TLS 1.2 ciphers for the Equifax for Developers Portal include the following ciphers:

• ECDHE-RSA-AES256-GCM-SHA384

• DHE-RSA-AES256-GCM-SHA384

• ECDHE-RSA-AES128-GCM-SHA256

• DHE-RSA-AES128-GCM-SHA256

NOTE: The Equifax endpoint is SNI enabled and if you're running a legacy utility you may have to consider a change which considers SNI in your endpoint resolution.

Equifax supports explicit versioning of API contracts. We use the major version numbering scheme, which involves easily detectable patterns such as V1 or V2 in path segments to distinguish URIs by their version. 

For example, POST https://api.equifax.com/namespace/v1/resource

Backward incompatible changes to API contracts results in the release of a new version. While we track backward compatible changes, these changes do not alter existing API contracts. Instead, they result in new interfaces or modify internal implementation of an API to provide new behavior without impacting existing behavior.

As a consumer of Equifax APIs, you should create your application expecting that the following changes might occur without notification:

• Addition of a new optional parameter to the URI.

• Addition of new optional data elements to the request body.

• APIs may return “redirection” http response code (301, 302) instead of the documented code for a method.

• Addition of fields in the response bodies.

• Rate limits applied to an API may change dynamically and may result in the API returning http status code 429.

• APIs or their parameters and fields may be immediately deprecated for security reasons. Otherwise, Equifax will provide reasonable notice of deprecations.

API Deprecation Best Practice

APIs represent system to system interaction channels for Equifax products. So while the technique to upgrade versions is specific to API best practices, the upgrade and deprecation of an API really touches the life cycle of product enhancements. 

Equifax’s API lifecycle and deprecation policy:

1. Equifax follows industry standard practices in defining major and minor versions:

   1. Major version: The major version indicates to API consumers that significant changes have occurred in the API contract from a previous version. A significant change may or may not be backward compatible.

   2. Minor version: The minor versions are backward compatible changes to the API contract. 

2. Equifax will add a major version to an API only because of industry changes, security/compliance changes or when a feature/modification is introduced to support the request of multiple customers to provide enhanced features in the market. A major version may significantly restructure, remove or rename a data structure or one of its members, add a new interface to an existing API, or change a default setting.

3. Equifax will announce the release of the next major version 3 months in advance.

4. External customers will have a reasonable time (18 months) to migrate off of the deprecated version.

5. Minor versions are backward compatible and do not have set sunset rules. Equifax will notify customers about backward compatible minor version changes ahead of time.

Note: External customers, please refer to your contract for details on this agreement and compliance.