The Retrieval API Developer Hub

The Retrieval API allows you to match your data to the LiveRamp Identity Graph and receive RampIDs. API calls are made using batch request calls that contain up to 1000 records per call.

Guides    API Reference

The Identity Envelope Decryption Endpoint

Learn how you can use the Retrieval API for identity envelope decryption.

πŸ“˜

Want API reference information for the Identity Envelope Decryption endpoint?

See "Decrypt Identity Envelopes" for more information.

What is an Identity Envelope?

An Identity envelope is an opaque and encrypted structure containing RampIDs and metadata. Each envelope is created with a client-specific encryption key that makes it unique. An envelope is valid for 30 days from the date of creation.

An envelope is represented as a Base64-encoded string.

Identity envelope string example

AY3SYJlFDI1RqsMv9gZOjOab6hGuwWKmbE4K70Z-Zex27DD6M9U0Jg.

The string is different each time an envelope is created for the same underlying data as a result of randomization.

Identity Envelope Decryption

Due to the opaque nature of identity envelopes, they need to be decrypted into usable identifier data for the parties who receive them. The Retrieval API provides the decryption capability using the envelope decryption endpoint. This endpoint is used to decode and decrypt an envelope to extract the identifier in the envelope. The Retrieval API then encrypts the value with a partner-specific encryption key and partner ID. The result is a RampID in the partner ID space that is usable for transactions.

There is a limitation to the type of data the API can decrypt from. The data represented in the envelopes must correspond to a valid RampID. Data types such as cookie and mobile ID are not currently supported.

Envelope Decryption Endpoint

The API supports envelope lookups on Person-based identifiers. As the name implies, the input envelope must represent an individual in the underlying data, namely, with granularity of "X" (meaning INDIVIDUAL).

This endpoint supports POST operations with an envelope string passed in as a query parameter. The standard API parameters for the lookup endpoint are also applicable.

The URI path is:

  • /people/envelope?key=<envelope_string_representing_individual>

The API returns status code 200 to indicate a successful execution. The resulting decrypted RampID is made available in the anonymousConsumerLink attribute in the "anonymousAbilitec" bundle.

Unsuccessful responses from the endpoint may return status codes of 400 (bad request), 404 (not found) or 500 (server error). See Errors and Troubleshooting section for details.

🚧

Before Using the Identity Envelope Decryption Endpoint

In order to use this endpoint, a user must be set up with proper credentials and access permissions. A client representative can help with this setup. For making API calls, a user needs to have a client ID and a client secret. For more details, see "Request an Access Token".

Sample Requests and Responses

The following sample requests assume a valid access token is obtained and passed in the Authorization header.

Batch Calls

Due to privacy restrictions, you will need to transcode multiple envelopes at a time using batch calls. The API supports passing up to 1000 envelopes in the same batch call. This can be done by making a POST call to https://us.identity.api.liveramp.com/batch/lookup and passing in JSON that looks like:

[
  "/people/envelope/?key=AUGGsYEKVWxnDsHU6b65TfdHEmC0vY51YrJhxTTRtB54A5dTzdrLIQ", 
  "/people/envelope/?key=AUGFOIZ5kDgv1weSzQ7NXo8sOMraa4ORJJONSoutNa3jb65Rgmj7aE", 
 . . .
]

The response should look like:

{
  "person": {
    "anonymousAbilitec": {
      "anonymousConsumerLink": "XiT001sgRRky74xZ6NrpSsF6z2ucg6TeV8rISolIhOMe-R94lh47QP2xuVITxFm6otlyrB"
    }
  }
}{
  "person": {
    "anonymousAbilitec": {
      "anonymousConsumerLink": "XiT001xuVITx94lh47QP2xuVITxFmyrBF6z2ucg6TeV8rIe-R94lh47Qh47QP2xrIhz2u"
    }
  }
}

Decrypting a Singular Envelope to a RampID

Sample request (example only, not valid for real-world use cases):

curl --header "Authorization: Bearer <ACCESS_TOKEN>" 'https://us.identity.api.liveramp.com/people/envelope?key=AUGGsYEKVWxnDsHU6b65TfdHEmC0vY51YrJhxTTRtB54A5dTzdrLIQ'

Sample response with derived RampID output:

{
  "person": {
    "anonymousAbilitec": {
      "anonymousConsumerLink": "XiT001sgRRky74xZ6NrpSsF6z2ucg6TeV8rISolIhOMe-R94lh47QP2xuVITxFm6otlyrB"
    }
  }
}

Errors and Troubleshooting

In addition to error codes listed in Error documents, the envelope decryption endpoint may return the following errors:

Category

Message

Status Code

Cause

Invalid lookup request

Invalid keyType and documentClass combination

400

Only people documents are supported.

Invalid RampID granularity for document class

400

Only INDIVIDUAL granularity ("X") is supported

Unsupported RampID source in the envelope

400

The source type of the identity link data in the envelope is not supported by the API.

Invalid envelope

Envelope error: READ_ENVELOPE_HANDLE_FAILED

400

Envelope handle cannot be read.

Envelope error: INVALID_ENVELOPE_HANDLE

400

Envelope handle is invalid/unsupported.

Envelope error: ENVELOPE_EXPIRED

400

Envelope was created at least 30 days ago and has expired.

Envelope error: NO_PERMITTED_SUBNETWORKS

400

Envelope does not contain at least 1 permitted publisher subnetwork.

Envelope error: ENVELOPE_DECRYPTION_FAILED

400

Envelope payload cannot be decrypted using the key indicated by the handle.

Envelope error: ENVELOPE_DECODING_FAILED

400

Envelope string is not in valid Base64 format.

No matching entity

Entity in the envelope no longer exists

404

The entity represented in the envelope does not exist in the data repository any more.

Opted-out entity

404

The entity represented in the envelope has opted out.

Server error

Internal server error

500

An error was encountered on server side while processing the request.

Updated 2 months ago

The Identity Envelope Decryption Endpoint


Learn how you can use the Retrieval API for identity envelope decryption.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.