Preventing duplication

To protect your POST requests against duplicating, you can use the optional header parameter x-request-id.

The x-request-id value must be in the format of a Universally Unique IDentifier (UUID), RFC 4122.

Below we will provide examples to show the difference in the API call outcomes with and without the x-request-id header parameter.

Use case

We will review several examples to illustrate how API outcomes differ when the x-request-id is used as the request ID versus when it is not applied.

The initial request data:

Use case data	API parameters with values
Person's Tuum id is ID-3419.	.../persons/ID-3419/accounts
The name of the account holder is Eleanor Rigby.	"personName": "Eleanor Rigby"
Eleanor is a resident of Great Britain.	"residencyCountryCode": "GB"
The standard price list is assigned to the account.	"priceListTypeCode": "STANDARD"
Eleanor is assigned to the GROUP_A customer group.	"customerGroupCode": "GROUP_A"
Currency account type.	"accountTypeCode": "CURRENCY"
The account currency code is GBP.	"currencyCode": "GBP"

Explanatory examples

To view the examples, go to the following pages:

Requests with same request ID

Requests without request ID

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.

Currently, not all POST endpoints support the x-request-id header used to prevent duplicate requests. If you are unsure whether a particular endpoint supports this header, please contact the Tuum team for clarification.