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.
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:
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.
To view the examples, go to the following pages:
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:
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
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.
.../persons/ID-3419/accounts
"personName": "Eleanor Rigby"
"residencyCountryCode": "GB"
"priceListTypeCode": "STANDARD"
"customerGroupCode": "GROUP_A"
"accountTypeCode": "CURRENCY"
"currencyCode": "GBP"
We will create a new account for a person by making the following API call.
POST
https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts
Below is an example request body of the API call for creating an account.
{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}
curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTE6MjM6MjUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNDgyMDV9.1lnY03GWnnGdki0uJlkNNSMydwiWv_jsdII10PKPUkA' \
-H 'x-request-id: eb1d4135-bca1-4612-aa83-29637830fe37' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}'
As a result, a new account with accountId: ID-1292
was created and activated.
We will make the API call again without changing the request ID and using the same request data.
The response we received is identical to the initial call, confirming the creation of the account with the ID-1292
. No new account was created.
We will repeat the API call using the same request ID but with updated request data. We will change the currency from GBP to USD.
Below is an example request body for creating an account with the updated currency.
{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "USD"
}
curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTE6MjM6MjUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNDgyMDV9.1lnY03GWnnGdki0uJlkNNSMydwiWv_jsdII10PKPUkA' \
-H 'x-request-id: eb1d4135-bca1-4612-aa83-29637830fe37' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "USD"
}'
As a result, no new account is created. However, the account currency on the existing account ID-1292
is updated to USD as requested.
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.
We will make another API call without the request ID, but the data from the first call remains the same.
{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}
curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTI6Mzk6MTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNTI3NTh9.L6hz-vAyOWwTZ5z5e2aBpppxmwdhq7JqPVbOoC4n7Ak' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}'
The response shows that the new account with accountId: ID-1293
was created and activated.
This time, we will make an additional API call without the request ID. However, we will change the currency from GBP to EUR.
{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "EUR"
}
curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTI6Mzk6MTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNTI3NTh9.L6hz-vAyOWwTZ5z5e2aBpppxmwdhq7JqPVbOoC4n7Ak' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "EUR"
}'
The response shows that the new account with accountId: ID-1294
was created and activated.
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.