Overview

The Privacy API Opt-out endpoint allows authorized partners to opt out users from ID5 tracking using various privacy identifiers including ID5 ID, MAIDs, email addresses, and hashed emails. The system handles multiple identifier types and automatically opts out associated IDs.

Opt Out Request

Example URL

https://api.id5-sync.com/privacy/v2/api/optout?partnerId={partnerId}&apiToken={apiToken}

Request Type

HTTP POST

Request Headers

Content-Type: application/json; charset=UTF-8

Available Parameters

Querystring

Request Body (JSON)

Note: At least one identifier field must be provided in the request body.

ID5 ID Formats Supported

The system accepts ID5 IDs in multiple formats: 

• ID5-prefixed format (decrypted ID5ID): ID5-ZHMOMopHd-M3j2tMtnDyZzOPPzVB_4Zj73nGFlJ5UQ

• ID5* encoded format (encrypted ID5ID): ID5*JAdI2WT2d7kLi4l4ICTmUX3137PpzqvzlNb6OUAl0MX96NChTqVI0oGD7idrCmpw

Example Opt Out Request

https://api.id5-sync.com/privacy/v2/api/optout?partnerId=12345&apiToken=your-api-token

Example 1: Opt out by ID5 ID (decrypted)

{
  "id5Id": "ID5-ZHMOMopHd-M3j2tMtnDyZzOPPzVB_4Zj73nGFlJ5UQ"
}

Result: Decodes to UUID and stores opt-out for the decoded ID

Example 2: Opt out by MAID

{
  "maid": "dc7e803b-fe08-430b-aded-3f4942929000",
  "maidType": "GAID"
}

Result:

• Looks up associated ID5 ID for the MAID

• Stores opt-out for the associated ID5 ID

• Stores MAID in mobile opt-out repository

Example 3: Opt out by email

{
  "email": "test@test.io"
}

Result:

• Converts email to HEM (SHA-256)

• Looks up associated ID5 ID from hard signal storage

• Stores opt-out for the associated ID5 ID

• Records email opt-out

Example 4: Opt out by hashed email (HEM)

{
  "hem": "1958e9b00a8319f05cb46cf06b397e724c5c66a2ff2633c7f0884d6a57432af8"
}

Result:

• Looks up associated ID5 ID from hard signal storage

• Stores FULL opt-out for the associated ID5 ID

• Records email opt-out

Example 5: Opt out with multiple identifiers (same associated ID)

{
  "id5Id": "ID5-ZHMOMopHd-M3j2tMtnDyZzOPPzVB_4Zj73nGFlJ5UQ",
  "maid": "b33fa4b2-5d49-4014-835e-255c462bc9be",
  "maidType": "IDFA"
}

Result:

• Stores opt-out for the ID5 ID

• Stores MAID opt-out (if MAID lookup returns same ID5 ID)

• Stores MAID in mobile opt-out repository

Example 6: Opt out with multiple identifiers (different associated IDs)

{
  "id5Id": "ID5-ZHMOMopHd-M3j2tMtnDyZzOPPzVB_4Zj73nGFlJ5UQ",
  "maid": "a95a6929-8bfc-445d-9625-7c6593c1e950",
  "maidType": "GAID",
  "email": "test@test.io"
}

Result: Stores opt-out for:

• The provided ID5 ID

• The ID5 ID associated with the MAID

• The ID5 ID associated with the email (from hard signal storage)

Plus records MAID and email opt-outs

Opt Out Response

Successful Response

HTTP Status Code

200 OK

Response Body

The response body will be empty for successful opt-out operations.

Error Responses

Authentication Error

HTTP Status Code: 401 Unauthorized

{
  "code": "api_token_invalid",
  "message": "Wrong api token for partnerId",
  "type": "authentication_error"
}

Missing Required Parameter

HTTP Status Code: 400 Bad Request

{
  "code": "request_parameter_invalid",
  "message": "Required request parameter 'partnerId' is not present",
  "type": "invalid_request_error"
}

Important Implementation Notes

Associated ID Lookup

1. MAID Association: When a MAID is provided, the system looks up any previously associated ID5 ID and opts that out as well
2. Email/HEM Association: The system checks hard signal storage for ID5 IDs associated with the email hash
3. Multiple Associations: When multiple identifiers are provided, all associated ID5 IDs are opted out

Email Processing

• Plain text emails are normalized (see normalizing emails) and hashed using SHA-256
• The system looks up associations using the hashed value
• Both email and hem fields are treated equivalently after hashing

Idempotency

The opt-out operation is idempotent - calling it multiple times with the same identifiers will have the same effect as calling it once.

Rate Limiting

Please refer to your partner agreement for specific rate limiting details. Excessive requests may result in temporary blocking.

Support

For technical support or questions about the Privacy API, please contact your ID5 representative.