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 RampID Transcoding Endpoint

Learn how to transcode your RampIDs to a partner's encoding, or transcode a partner's RampIDs to your encoding.

πŸ“˜

Want API reference information for the RampID Transcoding endpoint?

See "Transcode RampIDs" for more information.

Every RampID has a specific encoding to ensure the security and privacy of our partner's data. In cases where partners are interested in translating their RampIDs from one partner encoding to another, the Retrieval API can be leveraged to do so.

🚧

Due to the sensitive nature of RampIDs, there are certain privacy restrictions that must be validated before we provision access to the ability to transcode. Please reach out to your LiveRamp representative if you are interested in enabling this feature.

Transcoding Concepts

The first 4 characters (after the prefix) in a RampID are known as the "partner encoding", or "encoding", which uniquely identifies the partner.

If you are receiving any RampIDs from LiveRamp (through the Authenticated Traffic Solution, the Retrieval API, Mapping Files, etc.), you can check what your "native" partner encoding is by looking at the first 4 characters (after the prefix) of the RampID.

The "native" partner encoding is the default encoding that you will receive RampIDs in. Knowing your native partner encoding will assist you in calling the API for the correct use cases.

Note that the RampID prefix can be used to distinguish between a maintained or derived RampID. Maintained RampIDs will have a prefix of XY while derived RampIDs use Xi. More on this can be found here.

Other to Native

This is for cases where you are receiving RampIDs in encodings that are different than your default and want to translate those RampIDs into your native partner encoding. Each partner encoding you would like to transcode from requires an explicit one-time authorization to be performed by our client support team.

Once configured, you can send any RampID of any authorized encoding to the API and use the /people/anonymousAbilitec/ endpoint to receive that specific RampID in your default, native encoding. For household-based RampIDs (identified by an hY prefix) you can use the /households/anonymousAbilitec/ endpoint instead.

In the below example, a partner is receiving RampIDs encoded with T999 from another entity's data lake. and wants to transcode these RampIDs into their default, native encoding of T001. The resulting output can be found in the anonymousConsumerLink attribute (instructions for obtaining a bearer token can be found here).

curl -H "Authorization: Bearer $TOKEN" \
"https://us.identity.api.liveramp.com/people/anonymousAbilitec/?key=XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD"
{
  "person" : {
    "anonymousAbilitec" : {
      "anonymousConsumerLink" : "XYT0017PNOohstUb2z9jZHY4v5ef_i-DOGbBv-GzZL-ecBKZ4"
    }
  }
}

Native to Other

If you are looking to transcode your RampIDs from your native partner encoding into another entity's encoding, this is also possible via the same endpoint.

To output links in a different encoding other than your native partner encoding, provide the partner encoding (which will designate the exact partner encoding of the output identifier) directly as a query parameter. A partner encoding value is typically a 4-character string in the format of "partner Encoding" in the image above.

πŸ“˜

The ability to transcode Native to Other requires proper authorization setup. Your LiveRamp representative will properly permission and provide partner encodings to you.

In the below example, a partner wants to transcode RampIDs from their native partner encoding T001 into another entity's encoding of T999. You can see in the path that this is done by including the &partnerEncoding=T999 parameter on the call. The resulting output can be found in the anonymousConsumerLink attribute.

curl -H "Authorization: Bearer $TOKEN" \
"https://us.identity.api.liveramp.com/people/anonymousAbilitec/?key=XYT0017PNOohstUb2z9jZHY4v5ef_i-DOGbBv-GzZL-ecBKZ4&partnerEncoding=T999"
{
  "person" : {
    "anonymousAbilitec" : {
      "anonymousConsumerLink" : "XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD"
    }
  }
}

Batch Call Example

You can also transcode multiple RampIDs at a time using batch calls. The API supports passing up to 1000 RampIDs 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/anonymousAbilitec/?key=XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD", 
  "/people/anonymousAbilitec/?key=XYT999Zxyz_NDhFMTZDQz-tQkUxRC00NjE2LTkxOUItMkYwOUQ0OUJCQ0E2MDdGOTk5NTQ", 
 . . .
]

If you would like to transcode from your native encoding to others using a batch call, the output partner encoding will need to be specified as a partnerEncoding query parameter in the request.

πŸ“˜

Important performance note

When possible, batching up your transcoding requests into groups of 1000 RampIDs and calling the RampID Transcoding endpoint will result in much better performance for your application.

Other to Native Batch Call Example Response

curl -H "content-type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d @input.json \
"https://us.identity.api.liveramp.com/batch/lookup"
[ {
  "code" : 200,
  "document" : {
    "person" : {
      "anonymousAbilitec" : {
        "anonymousConsumerLink" : "XYT0017PNOohstUb2z9jZHY4v5ef_i-DOGbBv-GzZL-ecBKZ4"
      }
    }
  }
}, {
  "code" : 200,
  "document" : {
    "person" : {
      "anonymousAbilitec" : {
        "anonymousConsumerLink" : "XYT001k0MS00MDc1LUI4NjEtMjlCOUI0MUY3MENBCgNjVGQjE0MTMtRkFBMC00QzlELUJF"
      }
    }
  }
} ]

Native to Other Batch Call Example Response

curl -H "content-type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d @input.json \
"https://us.identity.api.liveramp.com/batch/lookup?partnerEncoding=T999"
[ {
  "code" : 200,
  "document" : {
    "person" : {
      "anonymousAbilitec" : {
        "anonymousConsumerLink" : "XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD"
      }
    }
  }
}, {
  "code" : 200,
  "document" : {
    "person" : {
      "anonymousAbilitec" : {
        "anonymousConsumerLink" : "XYT999Zxyz_NDhFMTZDQz-tQkUxRC00NjE2LTkxOUItMkYwOUQ0OUJCQ0E2MDdGOTk5NTQ"
      }
    }
  }
} ]

Updated 2 months ago

The RampID Transcoding Endpoint


Learn how to transcode your RampIDs to a partner's encoding, or transcode a partner's RampIDs to your encoding.

Suggested Edits are limited on API Reference Pages

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