Use the API to decrypt identity envelopes.
The Identity Envelope Decryption endpoint decrypts an identity envelope to extract a RampID and its associated metadata, then re-encrypts the information 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. The cookie and mobile ID data types are not currently supported.
Envelope Decryption Call
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 the 200 status code to indicate a successful execution. The resulting decrypted RampID is made available in the anonymousConsumerLink attribute in the "anonymousAbilitec" bundle.
Pseudonymous identifier
In the context of the RampID API, references to "anonymousAbilitec" indicate resolving to people-based pseudonymous online identifiers. For more information, see "RampID Methodology" in the Identity documentation.
Unsuccessful responses from the endpoint may return status codes of 400 (bad request), 404 (not found) or 500 (server error). For more information, see "Errors and Troubleshooting".
Sample Requests and Responses
The following sample requests assume a valid access token is obtained and passed in the Authorization header.
Batch Calls
You can transcode up to 1000 envelopes at a time using the same batch call, which is a POST call to https://us.identity.api.liveramp.com/batch/lookup
with JSON in the following format:
[
"/people/envelope/?key=AUGGsYEKVWxnDsHU6b65TfdHEmC0vY51YrJhxTTRtB54A5dTzdrLIQ",
"/people/envelope/?key=AUGFOIZ5kDgv1weSzQ7NXo8sOMraa4ORJJONSoutNa3jb65Rgmj7aE",
. . .
]
The corresponding response is formatted similar to the following:
{
"person": {
"anonymousAbilitec": {
"anonymousConsumerLink": "XiT001sgRRky74xZ6NrpSsF6z2ucg6TeV8rISolIhOMe-R94lh47QP2xuVITxFm6otlyrB"
}
}
}{
"person": {
"anonymousAbilitec": {
"anonymousConsumerLink": "XiT001xuVITx94lh47QP2xuVITxFmyrBF6z2ucg6TeV8rIe-R94lh47Qh47QP2xrIhz2u"
}
}
}
Decrypting a Singular Envelope to a RampID
Sample request:
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"
}
}
}
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 API doesn't support the format of the identity link data in this envelope. | |
Invalid envelope | Envelope error: READ_ENVELOPE_HANDLE_FAILED | 400 | The envelope handle cannot be read. |
Envelope error: INVALID_ENVELOPE_HANDLE | 400 | The envelope handle is invalid/unsupported. | |
Envelope error: ENVELOPE_EXPIRED | 400 | The envelope was created at least 30 days ago and has expired. | |
Envelope error: NO_PERMITTED_SUBNETWORKS | 400 | The 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 | The envelope string is not in a valid Base64 format. | |
No matching entity | The entity in the envelope no longer exists | 404 | The entity represented in the envelope does not exist in the data repository. |
Opted-out entity | 404 | The entity represented in the envelope has opted out. | |
Server error | Internal server error | 500 | An error was encountered on the server side while processing the request. |