POST /optout/status
Checks the opt-out status of raw EUIDs. Given a list of raw EUIDs, this endpoint returns the raw EUIDs 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, and DSPs. More generally, this is for participants who have access to raw EUIDs but do not have access to the underlying email addresses 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 EUIDs, 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 EUIDs 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 Parameter | Data Type | Attribute | Description |
---|---|---|---|
{environment} | string | Required | Integration environment: https://integ.euid.eu .Production environment: https://prod.euid.eu .For a full list, including regional operators, see Environments. |
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 EUIDs 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.euid.eu/v2/optout/status [Your-Client-API-Key] [Your-Client-Secret]
Even though the script is named for UID2, it is applicable to EUID also.
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 EUIDs that have opted out. For each, it includes the time at which the opt-out request was made. EUIDs 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 EUID). |
opted_out_since | number | The Unix timestamp (in milliseconds) that indicates when the raw EUID 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.