Optional parameters

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

The 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 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.	.../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.