Idempotent requests

Computer networks are imperfect and, occasionally, an HTTP request might be interrupted during transmission and no response will be delivered to the client program. Typically, you will receive an error from your HTTP request library when this happens.

As you cannot be certain whether the request succeeded or failed before the communication was interrupted, you must repeat the request using the same idempotency key. In this way, the investment API can recognise that it is a duplicate of the previous request and handle it accordingly. This ability to achieve the same, intended results, no matter how often the request is repeated is called "Idempotency".

To make our API idempotent, we require you to use "idempotency keys". If your request contains the same idempotency key as a previous request, that has been successfully handled, the Investment API will know not to repeat the work, but rather to repeat the successful response to the request.

Implementing idempotency

1. Provide an idempotency-key HTTP header with the request. This header must have a randomly generated UUID as its value.

   
   

   Example idempotency key

   idempotency-key: ccb07f42-4104-44ad-8e1f-c660bb7b269c

   
   

2. Generate a new and unique idempotency-key value for each new request, but make sure that in case you need to retry a previous request, you use the same idempotency-key value as for the repeated request.

   
   

Request that require idempotency keys

The following POST requests require idempotency keys; sending idempotent keys for other endpoints or HTTP methods has no effect:

• Creates an account.
• Creates an account group.
• Trigger a direct debit
• Creates a fee collection for pre-calculated fee amounts.
• Create account liquidation request
• Create a mandate
• Places a new order. After the creation request for the order is accepted, further processing takes place asynchronously.
• Create portfolios allocation
• Create portfolios configuration
• Create portfolios order
• Trigger portfolio rebalancing
• Creates a new reference account for a user specified by ID.
• Create savings plan
• Creates a tax exemption.
• Update tax residencies
• Trigger a bank transaction for testing purposes. This can be used to simulate a money transfer for various flows which need cash settlements on one of our bank accounts.
• Triggers the creation of a top-up payment.
• Creates a user.
• Trigger a virtual cash decrease
• Trigger a virtual cash increase
• Trigger a withdrawal