Multi-Customer

Service version: 2
Last edit: 2024.09.19
TomTom Maps

Public Preview Notice

This feature of the Matrix Routing v2 API is in Public Preview. If you would like to try it out, please contact Sales.

What is the Multi-Customer feature?

The Matrix v2 service has processing limits per customer. Customers may want to offer Matrix v2, e.g., via an app or API platform, to their own multiple customers called sub-customers on this page. The Multi-Customer feature allows every sub-customer to have their own independent limits, so that requests from different sub-customers will not affect each other during processing time.

How to use the Multi-Customer feature?

This section covers the actions that must be taken to use the Multi-Customer feature in the Matrix Routing v2 API.

Note: If Sub-Customer-ID is not provided at all, then Matrix v2 works without the Multi-Customer feature.

Request

In order to use the Multi-Customer feature you should add the Sub-Customer-ID header to the regular Matrix v2 requests. Please be aware that this document does not specify the complete request, but only additional input data.

Header nameDescription
Sub-Customer-ID

Specifies an identifier for the sub-customer.

  • It is used to differentiate your customers in the Multi-Customer feature.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • The value should not contain sensitive information, because it can be used for tracing. Please consider using the SHA256 hash.

Value: An identifier for the sub-customer.

Error response

The Matrix v2 may return HTTP 400 Bad Request while using Sub-Customer-ID header in the following cases:

  • Sub-Customer-ID header does not match the regular expression '^[a-zA-Z0-9-]{1,100}$', for example, the value has a length greater than 100.
  • The Multi-Customer feature is not enabled for your API Key. Please contact Sales to enable this feature.

Example error message

Please notice the subCustomerId value in the target field.

1HTTP 400 Bad Request
2{
3 "detailedError": {
4 "code": "BAD_REQUEST",
5 "message": "Bad Request",
6 "details": [
7 {
8 "code": "BAD_ARGUMENT",
9 "message": "You are not allowed to use Sub-Customer-ID header.",
10 "target": "subCustomerId",
11 "innerError": {
12 "code": "ILLEGAL_PARAMETER"
13 }
14 }
15 ]
16 }
17}

Usage scenarios

The feature can be used with both Synchronous and Asynchronous Matrix v2 APIs.

Keep in mind that for the Asynchronous API all the endpoints are affected:

Synchronous API

Interaction with the Synchronous API is done in a single API call, so it is enough to set the Sub-Customer-ID header for the Synchronous Submission request in order to have the Multi-Customer feature effective.

Asynchronous API

The Sub-Customer-ID header must be set for all the asynchronous Matrix endpoints to be effective.

Scenario Sub-Customer-ID header value in the Asynchronous Matrix v2 Submission endpoint Sub-Customer-ID header value in the Asynchronous Matrix v2 Status or Download endpointsHTTP response status code
Sub-Customer-ID provided in the Submission endpoint matches with other endpoints. Access is allowed.value1value1HTTP 200 OK
Sub-Customer-ID provided in the Submission endpoint does not match with other endpoints. Access is denied.value1value2HTTP 404 NOT FOUND
Sub-Customer-ID is not provided in the Submission endpoint but provided in other endpoints. Access is denied.-value1HTTP 404 NOT FOUND

Sub-Customer-ID is provided in the Submission endpoint but not provided in other endpoints. Access is allowed.
In this case, we decided to allow access to the Matrix v2 result and status without the Sub-Customer-ID being filled.
It is up to the Customer to secure the download/status access with the Sub-Customer-Id header, if they find it necessary to make sure that one sub-customer won't have access to another sub-customer's matrices.

value1-HTTP 200 OK