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:

• Advertiser/Data Provider Integration Guide
• DSP Integration Guide
• UID2 Sharing: Overview

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, without creating multiple parallel connections.

Request Format

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

For authentication details, see Authentication and Authorization.

important

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 Parameter	Data Type	Attribute	Description
{environment}	string	Required	Testing (integration) environment: https://operator-integ.uidapi.com 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.

note

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

Unencrypted JSON Body Parameters

There is a single body parameter.

Body Parameter	Data Type	Attribute	Description
advertising_ids	string array	Required	The 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": [
    "ufv1uGRovNiJNbJqiE/xzM+aKE7jP69MgspOZoEQ3xc=",
    "zstfu9RG/Ih5trR6hlaHP6hw5yt9mYd5TKg2mRpWVng=",
    "VZqcve81+ImeoNUsizTFLEMOvREptJo1ROZvKw9ibSM="
  ]
}

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

echo '{"advertising_ids": ["ufv1uGRovNiJNbJqiE/xzM+aKE7jP69MgspOZoEQ3xc="]}' | python3 uid2_request.py https://prod.uidapi.com/v2/optout/status [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

note

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.

Property	Format	Description
advertising_id	string	The advertising ID (raw UID2).
opted_out_since	number	The 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.

Status	HTTP Status Code	Description
success	200	The request was successful. The response will be encrypted.
client_error	400	The request had missing or invalid parameters.
unauthorized	401	The 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.