Getting Started Guide
Getting Started
Register for an Account
For a full User Guide, please click here.
After you register for an account, you'll receive an Activate Account email and be prompted to create a password. Then, as a signed-in account owner, you’ll be able to perform the following activities:
- View Product Overview information and API Reference documentation.
- Create apps and invite collaborators to join.
- Get credentials (Client ID and Client Secret) for sandbox testing (for the products that support this).
- Promote your apps.
NOTE: If you’re planning (or even considering) to “Go Live,” contact us to discuss our requirements for access and integration so we can help get the process started and keep you moving along at your pace.
Create an Application
- To create an app, Sign In. Your Dashboard page opens.
- In the "Create New Application" section, give your app a name and an optional description, then click "Next".
- Select the API Products you want to include in your app, then click the "Add" button. Unless you are only using the "Equifax Gateway (XML Consumer) product, then you must always include "Security Service". Your app will appear on its own page where you can manage everything from one centralised location.
Experiment in Sandbox
Please note that not all products have a Sandbox, for more details please see the ‘API Product’ page for each product.
Ready to see the API in action? Generate simulated results using our test data in the Sandbox:
- Access the IdAMS credentials from the App page (accessed via the Dashboard)
- You might need to add a certificate into Postman, if you are using it. Click here for instructions.
- Code and test the responses using the provided test data. The downloadable file for Postman (available from https://www.getpostman.com/) includes a description file to explain which requests will return which responses (for example, how to return an error message)
Don't forget that you have the flexibility to invite and manage collaborators for each of your apps - do this from the bottom-right corner of the app details screen.
Promote to Test
- When you’re ready to promote your app to the test environment, click the "Test" tab in the Credentials & Details panel on your app page.
- Enter (and manage) your whitelisted IPs here. These can also be amended once you have been approved to Test, during the request to promote to Live (see below) and after a request to Live has been approved. However, they cannot be amended while a request to promote (either to Test or Live) is pending approval from Equifax. IP Whitelisting is an Equifax Security requirement.
- Select your Targeted Go Live date and submit your request.
- Your request and app details will be sent to the Equifax product teams for review.
- As soon as one or more API Products are approved, you’ll be notified by email.
- Please note: Test IdAMS credentials are required for promotion to Test. These will be provided to you by Equifax.
Go Live
- After you’ve fully tested your app, just go through similar steps as performed in Test. You can add additional IP ranges during the request to promotion, and also after the request has been approved by Equifax (but not while a request to promote is pending approval from Equifax).
- Our team will review your app one more time.
- New IdAMS credentials will be supplied to you by Equifax.
- Then you can validate your integration and call the API.
Roles & Permissions
Product Types
Our API Products are categorised by types that aligned to specific access privileges and workflows.
Public Products are exposed to existing and prospective customer users.
Partner Products are made available to specific Equifax customers, strategic partners, or connectors.
- A named or branded product configured for one or more specific customers.
- A customised solution developed for a specific customer.
- Solutions developed for a specific group of customers. For example, a migration solution.
Private Products are available only to internal Equifax users and developers.
Product Documentation
Each product has corresponding documentation which consists of Product Overview content, an API Reference and Additional API Documents (if applicable).
Access to product documentation is based on product type:
- Public Products: Available to all users regardless of login status.
- Partner Products: Available to specific account owners who have a Partner Product Access Code.
- Private Products: Available only to specific internal Equifax users.
Product Overview
The Product Overview helps users understand “Why should I use this product? What’s the value?” The content is made up of a basic description, top 3 benefits, key features and use cases for each product.
API Reference
The API Reference, also known as the Technical Specification, provides users with an understanding of “How the Product works and how to integrate.”
To access an API Reference, select the API Product via the API Product Page and click the "API Reference" tab next to "Overview".
Additional API Documents
If an API product has additional documents (for example: Data Dictionaries, Test Packs etc.), an additional tab becomes available next to the "API Reference" tab.
Security Standards
Authorization
We use 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.
We use the following methods for authentication:
OAuth 2.0 Grant Type
Client ID and Client Secret
Access Token
Environments
We support multiple environments for all our APIs to help you:
- Innovate without constraints.
- Develop production ready apps.
- Meet compliance needs.
Access requirements
You must have an approved set of IdAMS credentials (Client ID and Client Secret) for an environment to access it. This can be done by creating an app and adding APIs then requestion promotion of the app to each environment.
NOTE: The Base URLs listed for each of the environments below are API endpoints, not web endpoints.
Sandbox
- Base URL: https://api.sandbox.equifax.co.uk
Test
- Base URL: https://api.uat.equifax.co.uk
- Additional security: Requires valid IdAMS credentials, and APIs can only be accessed from whitelisted IP Addresses.
- Costs: Please contact your Equifax sales representative.
- Usage constraints: Please contact your Equifax sales representative.
Live
- Base URL: https://api.equifax.co.uk
- Additional security: Requires valid IdAMS credentials, and APIs can only be accessed from whitelisted IP Addresses.
- Costs: This varies per API product. Please contact your Equifax sales representative.
- Usage constraints: Please contact your Equifax sales representative.
Versioning
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.co.uk/namespace/v1/resource.
Backward incompatible ("breaking") changes to API contracts results in the release of a new version. While we track backward compatible changes, these changes do not change existing API contracts. Instead, they result in new interfaces or modify internal implementation of an API to provide new behaviour without impacting old behaviour.
As a consumer of Equifax APIs, you should create your app 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, to alert you to use the new URI and that the current URI may be deprecated in the future.
- 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/fields may be immediately deprecated for security reasons. Otherwise, we will give you reasonable notice of deprecations.
We will share all changes to the contract and behaviour as change logs on the portal, and provide guides to help you migrate from one version to another.
Copyright © Equifax, Inc. All rights reserved Equifax and the Equifax
marks used herein are trademarks of Equifax Inc. Other product and company names mentioned herein are the property of their respective owners.
