How to get started with our APIs

Get Started

ABN AMRO Bank offers a collection of APIs that will allow you to integrate our services into your applications. This page will guide you through all the steps you need to take before you can make your first API call.

  1. Registration
  2. Obtaining an API key
  3. Authentication
  4. Sandbox testing

 

Registration

Before you can start using our APIs, you will first need to register on the developer portal.

  1. Go to the Registration page.
  2. Fill in the form with your details.
  3. Submit the form!

After submitting, we will send you an email with an activation link. Activate your account by following that link and you are ready to go!

 

Obtaining an API Key

To actually start using APIs, you need to get an API key. This you can do from the My Apps page. To go to your My Apps:

  • Log in to your developer account. You will automatically land on the My Apps page.
  • If you are already logged in, click on My Apps.

On the My Apps page, you will be able to register an app. This is necessary to get an API key. To register an app do the following:

  1. Click the ‘Request API Key’ button. Or, if you already have an app registered, click on ‘Add a new App’.
  2. Submit a name and choose which API product(s) you want to associate with your app. Click on submit.
  3. You will return to the My Apps page. There you can see the status of your app(s).

Once your app’s status is approved, you can use the API key. You can see your API key and secret by:

  1. Clicking on your app
  2. Selecting the ‘Keys’ tab
  3. Your API key is listed as ‘Consumer Key’. The corresponding secret is listed as ‘Consumer secret’.

 

Authentication

To use any of our APIs, you need to authenticate yourself. For each API the way you need to authenticate yourself is described in the API's documentation.

 

Error Handling

This section provides an overview of the ABN AMRO APIs error model as well as guidance to developers on how to handle these errors.

  1. Error Format
  2. HTTP Status Codes
  3. Error Codes
Error Format

All ABN AMRO APIs throw errors in following JSON format:

{
"errors": [
	{
	  "code": "ERROR_UNIQUE_CODE",    
	  "message": "ERROR_MESSAGE",
	  "category" : "SHORT_DESCRIPTION/ERROR_CATEGORY",
	  "reference" : "API_DOCUMENTATION_LINK",
	  "status" : "HTTP_STATUS_CODE",
	  "traceId" : "UUID"
	}
]
}

These response attributes are explained in more detail:

Name Type Required Description
code string true Code that uniquely identifies the error for the API
message string true Long text message describing the error
category string true Short description or category of the error
reference string true API Documentation link
status string true HTTP Status code
traceId string true Unique request ID associated with the API call

 

The category of an error will indicate what a specific problem is. For example suppose there is a category that indicates “invalid IBAN”. There could be multiple reasons why the IBAN is invalid: “illegal country code”, “IBAN too long”, “IBAN too short” just to mention a few. That would result in three unique error codes, all with the same category.

For a consumer of the API the exact reason why the IBAN is invalid may not matter. When an “invalid IBAN” is reported an interactive application will prompt the user to enter the correct IBAN. A non-interactive system may flag an input record as having an invalid IBAN which needs to be investigated later on by an operator.

An API consumer should always first consider if the category suffices. If more specific error handling is needed, the entire code can be considered however an API consumer should never assume that only a fixed set of error codes are used. At a later point in time additional errors can be added for the same category.

For the “invalid IBAN” category another reason could be that the checksum on the IBAN fails. The addition of the checksum validation could result in another “invalid IBAN” error that should be treated by API consumers as any other “invalid IBAN” error. The code of the API-consumer should never break on additional reasons (like IBAN checksum failed). API consumers should not throw "unknown reason" exceptions, just treat it as another error in the same category.

 

HTTP Status Codes

The ABN AMRO API attempts to return appropriate HTTP status codes for every request. HTTP Status codes used in APIs are as follows:

Code Text Description
200 OK Request successful and Response not empty (e.g. used with POST or GET requests)
201 Created Resource successfully created (used with POST requests)
202 Accepted Response to long-running processes / Start of an asynchronous process. The response body contains a way to monitor the process.(e.g used with DELETE requests where the action will likely succeed but has not yet been enacted)
204 No Content Request successful and Response empty (e.g. used with PUT or DELETE requests; also used with partial updates / POST requests with patch keyword)
301 Moved Permanenently This and all future requests should be directed to the provided URI. (used with All)
303 See Other The response to the request can be found under another URI. (used with PATCH,POST,PUT, DELETE)
304 Is Modified Not Modified - resource has not been modified since the date or version passed via request headers If-Modified-Since or If-None-Match
400 Bad Request Validation errors or missing data in request
401 Unauthorized Authentication errors (Access token not valid or API key not valid)
403 Forbidden Authorization error (Insufficient scope)
404 Not Found Requested resource not found
415 Unsupported Media Type Media type not supported
429 Too Many Requests Quota exceeded
500 Internal Server Error Technical errors
503 Service Unavailable Service Unavailable
Error Codes

Error codes in the error response uniquely describe the error. Whenever you contact API Support for any specific error you are seeing in an API please provide the error code and traceId.

Details of generic error codes are as follows:

Code Category Description
ERR_1001_001 INCORRECT_HEADER Malformed or incorrect Authorization header
ERR_1002_001 MISSING_HEADER Basic authentication header missing
ERR_1002_002 MISSING_HEADER Access token header missing
ERR_1002_003 MISSING_HEADER API Key Header missing
ERR_1003_001 MALFORMED_REQUEST JSON Request: Container Depth exceeded
ERR_1003_002 MALFORMED_REQUEST JSON Request: Number of elements/ properties in an object exceeded the allowed limit
ERR_1003_003 MALFORMED_REQUEST JSON Request: Number of elements in an array exceeded the allowed limit
ERR_1003_004 MALFORMED_REQUEST JSON Request: Object entry/property name too long
ERR_1003_005 MALFORMED_REQUEST JSON Request: Object property value too long
ERR_1003_006 MALFORMED_REQUEST Request message malformed
ERR_1003_007 MALFORMED_REQUEST SOAP Request Message malformed
ERR_1004_001 INCORRECT_PARAMETER Incorrect or missing value for {parameter name}
ERR_1004_002 INCORRECT_PARAMETER Incorrect value of grant type
ERR_1004_003 INCORRECT_PARAMETER Token passed is not a valid token type
ERR_1004_004 INCORRECT_PARAMETER Incorrect or missing value for client_assertion_type
ERR_1005_001 JWT_LIFESPAN_TOO_LONG JWT lifespan too long
ERR_1006_001 JWT_INCORRECT Some attribute is incorrect, see the error message.
ERR_1007_001 JWT_INCOMPLETE Some attribute is missing, see the error message.
ERR_1008_001 JWT_EXPIRED The presented JWT has expired.
ERR_1009_001 JWT_INACTIVE The presented JWT is not active yet.
ERR_1010_001 JWT_INVALID The signature of the presented JWT is not valid.
ERR_1010_002 JWT_INVALID The algorithm used to sign the presented JWT is not supported.
ERR_1011_001 JWT_MALFORMED The presented JWT is malformed.
ERR_2001_001 INVALID_CLIENT_IDENTIFIER Client identifier is either missing or invalid
ERR_2002_001 INVALID_ACCESS_TOKEN Invalid access token
ERR_2003_001 ACCESS_TOKEN_EXPIRED Access token expired
ERR_2004_002 APIKEY_STATUS_NOT_ACTIVE The developer who created the the Developer App that has the API key you are using has an inactive status
ERR_2004_003 APIKEY_STATUS_NOT_ACTIVE The Developer App associated with the API key is revoked
ERR_2005_001 INVALID_API_KEY Invalid API Key
ERR_2005_002 INVALID_API_KEY API Key cannot be used for the API call
ERR_3001_001 ACCESS_DENIED Acccess denied for this IP address
ERR_3002_001 INSUFFICIENT_SCOPE Insufficient scope of the token. Token cannot be used for this call
ERR_3002_002 INSUFFICIENT_SCOPE Insufficient scope of the token. Token cannot be used for this call
ERR_7001_001 QUOTA_VIOLATION Quota for the call exceeded
ERR_7002_001 TOO_MANY_REQUESTS Spikes in API Call
ERR_8XXX_XXX INTERNAL_SERVER_ERROR All errors of this range of codes corresponds to internal server error.
ERR_9001_001 SERVICE_UNAVAILABLE Service is currently unavailable

 

Note: Details for error codes specific to APIs are described in respective API documentation.

 

Sandbox Testing

The next thing to do is to start experimenting with our APIs. You should do this in the sandbox environment we provide specifically for this purpose. In this environment you can access dummy data and accounts, to safely try out all the functionalities of our APIs. The interface is identical to the interface of our production APIs, the only difference is the data that is accessed through the API. Making a call to a sandbox API functions the same as making a call to a regular API.

As the interface is different for each API, please have a look at the documentation of the API you have registered your app with. There you will find a Tutorials section which will tell you all you need to know to make a first call. Or take a look at the Operations & Sandbox pages to see a list of all the operations offered for that specific API. And if you are looking for a more in-depth description of the API interface, just visit the Technical Details.