📘

RampID translation was formerly known as "RampID transcoding". You might continue to see instances of "transcode", "transcoding", and "transcoded" in some places.

📘

Want API reference information for the RampID Translation endpoint?

See "Translate 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 RampID API can be leveraged to do so.

The only type of input accepted by the Translation endpoint is a RampID, which is also the only output returned.

🚧

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

Translation 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 RampID 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. For more information on RampIDs, see RampIDs.

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 translate 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 translate 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 translate 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 translate 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 translate 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 translate 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 translate 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 translation requests into groups of 1000 RampIDs and calling the RampID Translation 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"
      }
    }
  }
} ]

Requesting RampID Translation Permissions

Translation permissions depend on a two-way agreement between your company and the partner whose RampIDs you wish to translate. This agreement must explicitly consent to the translation while specifying the translation direction (native to other or other to native).

When you contact your LiveRamp representative about obtaining translation permissions, they will email both you and your partner to obtain this consent, cc:ing [email protected].

The email for the partner doing the translation will read:

Please confirm permission to translate Company A RampIDs into Company 
B RampIDs.  Once received, your permission may be revoked at 
any time via email to [email protected].

The email for the partner translated from will read:

 Please confirm permission to translate Company A RampIDs into Company B RampIDs.  
 Once received, your permission may be revoked at any time via email to 
 [email protected].

If you are translating both to and from a partner's RampIDs, you must obtain separate permission for each translation direction:

 Please confirm permission to translate Company A RampIDs into Company 
B RampIDs and to translate Company B RampIDs into 
Company A RampIDs.  Once received, your permission may be revoked at any time via 
email to [email protected].