📘

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

The only type of input accepted by the Transcoding 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 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 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 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"
      }
    }
  }
} ]

Requesting RampID Transcoding Permissions

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

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

The email for the partner doing the transcoding will read:

Please confirm permission to transcode 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 transcoded from will read:

 Please confirm permission to transcode 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 transcoding both to and from a partner's RampIDs, you must obtain separate permission for each transcoding direction:

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