Multi-Customer

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.

We welcome your contribution to the development of this feature. Please share your observations and suggestions on our forum or send an email to our software engineers.

We appreciate your feedback, and we will keep you posted on how it's used.

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.

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:

• Asynchronous Matrix v2 Submission
• Asynchronous Matrix v2 Status
• Asynchronous Matrix v2 Download

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.