Skip to main content

POST /optout/status

Checks the opt-out status of raw UID2s. Given a list of raw UID2s, this endpoint returns the raw UID2s that have opted out, as well as the time that the opt-out took place. For more information, see User Opt-Out.

Used by: This endpoint is used by advertisers, data providers, DSPs, and sharers. More generally, this is for participants who have access to raw UID2s but do not have access to the underlying email addresses or phone numbers and want to know opt-out status.

For details, refer to the following documentation, depending on your role:

Batch Size and Request Parallelization Requirements

The key guidelines for managing batches of requests to this endpoint are as follows:

  • To check the opt-out status of a large number of UID2s, send them in sequential batches with a maximum batch size of 5,000 items per batch.
  • Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of raw UID2s consecutively.

Request Format

POST '{environment}/v2/optout/status'


You must encrypt all requests using your secret. For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.

Path Parameters

Path ParameterData TypeAttributeDescription
{environment}stringRequiredIntegration environment:
Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see Environments.

The integration environment and the production environment require different API keys.

Unencrypted JSON Body Parameters

There is a single body parameter.

Body ParameterData TypeAttributeDescription
advertising_idsstring arrayRequiredThe list of raw UID2s for which you want to check the opt-out status.
Include a maximum of 5,000 entries in one API call.

Request Example

The following is an example of an unencrypted JSON request body:

"advertising_ids": [

The following is an encrypted opt-out status request example:

echo '{"advertising_ids": ["ufv1uGRovNiJNbJqiE/xzM+aKE7jP69MgspOZoEQ3xc="]}' | python3 [Your-Client-API-Key] [Your-Client-Secret]

For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.

Decrypted JSON Response Format


The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.

A successful decrypted response returns the raw UID2s that have opted out. For each, it includes the time at which the opt-out request was made. UID2s that have not opted out are not included in the response.

"body": {
"opted_out": [
"advertising_id": "ufv1uGRovNiJNbJqiE/xzM+aKE7jP69MgspOZoEQ3xc=",
"opted_out_since": 1633643601000
"advertising_id": "zstfu9RG/Ih5trR6hlaHP6hw5yt9mYd5TKg2mRpWVng=",
"opted_out_since": 1709764087000
"status": "success"

Response Body Properties

The response body includes the following properties.

advertising_idstringThe advertising ID (raw UID2).
opted_out_sincenumberThe UNIX timestamp (in milliseconds) that indicates when the raw UID2 was opted out.

Response Status Codes

The following table lists the status property values and their HTTP status code equivalents.

StatusHTTP Status CodeDescription
success200The request was successful. The response will be encrypted.
client_error400The request had missing or invalid parameters.
unauthorized401The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation.

If the status value is anything other than success, the message field provides additional information about the issue.