To protect your POST requests against duplicating, you can use the optional header parameter x-request-id - request ID.
Below we will provide examples to show the difference in the API call outcomes with and without the request ID header parameter.
Use case
We will review several examples that illustrate the difference in the API outcomes when the request ID is used and when the request ID is not applied.
The initial request data:
Use case data
API parameters with values
Person's Tuum id is ID-3419.
The name of the account holder is Eleanor Rigby.
Eleanor is a resident of Great Britain.
The standard price list is assigned to the account.
Eleanor is assigned to the GROUP_A customer group.
Currency account type.
The account currency code is GBP.
Explanatory examples
To view the examples, go to the following pages:
Summary
From the illustrated examples we can see that when the x-request-id parameter is applied, it prevents the system from creating new objects. And when the x-request-id is not used or is used with unique value as per each call, all the POST calls are treated as unique and new objects are created:
POST call / Request ID
Same request ID
No or unique request ID
Initial POST call
Unique response
Unique response
Duplicated POST call
Same as in the initial response
Unique response
Duplicated POST with updated data
Same as in the initial response
Unique response
Usage recommendations
If you use the x-request-id header parameter, it is recommended to avoid reusing the same parameter value, even if the requests are made to different Tuum APIs.
Requests without request ID
Duplicated POST without request ID and the same data
We will make another API call without the request ID, but the data from the first call remains the same.
The response shows that the new account with accountId: ID-1293was created and activated.
Duplicated POST without request ID but changed data
This time, we will make an additional API call without the request ID. However, we will change the currency from GBP to EUR.
The response shows that the new account with accountId: ID-1294was created and activated.
Response
Summary for not using the request ID
If you make multiple POST calls to the same API endpoint without including the header parameter x-request-id, each subsequent call is treated as unique and will receive a separate response.
The same applies when you use the header parameter x-request-id with different unique values for each POST call.
The request ID value must be in the format of a Universally Unique IDentifier (UUID), .
If you make multiple POST calls to the same API endpoint using the same value for the x-request-id header parameter, all subsequent calls will receive the same response as the initial call. This principle also holds even if you use different data in the request body of a repeated request.