Every AbiliTec link has a specific encoding to ensure the security and privacy of our partner's data. In cases where partners are interested in translating their links from one partner encoding to another, the Lookup endpoint can be used.

Due to the sensitive nature of AbiliTec links, there are certain privacy restrictions that must be validated before you can transcode. Please reach out to your LiveRamp Representative if you are interested in enabling this feature.

Transcoding Concepts

The first 4 characters in an AbiliTec Link are known as the partner encoding, or domain encoding, which uniquely identifies the partner.

XXXXUS02xyz12345

If you are receiving any links from LiveRamp, you can check what your native partner encoding is by looking at the first 4 characters.

The native partner encoding is the default encoding for received links. Knowing your native partner encoding will assist you in calling the API for the correct use cases.

The character in the 7th position can be used to distinguish between maintained or derived links. Maintained links will have a 0 in that position while derived ones have a 1. For more information, see AbiliTec Identifiers.

Other to Native

In this situation, you receive links in encodings that are different than your default encoding and you want to translate those 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 link of any authorized encoding to the API and use the /people/abilitec/ lookup endpoint to receive that specific identifier in your default, native encoding. For household AbiliTec links you can use the /households/abilitec/ lookup endpoint.

In the example below, Partner A receives links encoded with T999 from Partner B's data lake. Partner A wants to transcode these links into their default, native encoding of T001. The resulting output can be found in the consumerLink attribute. For information about requesting an access token, see Getting Started.

curl -H "Authorization: Bearer $TOKEN" \
"https://us.identity.api.liveramp.com/people/abilitec/?key=T999US02xyz12345"
{
  "person" : {
    "abilitec" : {
      "consumerLink" : "T001US02qrs67890"
    }
  }
}

Native to Other

To transcode your links from a native partner encoding into another entity's encoding, you can make AbiliTec API calls using the same lookup endpoints: the /people/abilitec/ lookup endpoint and the /households/abilitec/ lookup endpoint.

To output links in a different encoding other than your native partner encoding, you can provide a partner encoding, to 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 described above. The ability to transcode requires proper authorization setup.

Your LiveRamp representative will properly permission and provide partner encodings to you.

In the example below, a partner wants to transcode links 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 consumerLink attribute.

In the below example, a partner can transcode links from T001 into T999 by providing a partnerEncoding parameter.

curl -H "Authorization: Bearer $TOKEN" \
"https://us.identity.api.liveramp.com/people/abilitec/?key=T001US02qrs67890&partnerEncoding=T999"
{
  "person" : {
    "abilitec" : {
      "consumerLink" : "T999US02xyz12345"
    }
  }
}

Batch Calls

You can also transcode multiple links at a time using batch calls. The AbiliTec API supports passing up to 1000 links in the same batch call. This can be done by making a POST call to https://us.identity.api.liveramp.com/batch/lookup
< NEED a better description >>:

[
  "/people/abilitec/?key=T999US02xyz12345", 
  "/people/abilitec/?key=T999US02bcd54321", 
 . . .
]

To transcode from your native encoding to others using a batch call, the output partner encoding will need to be specified as a parameter in the request.

📘

Important performance note

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

Other to Native Batch Call Example

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" : {
      "abilitec" : {
        "consumerLink" : "T001US02qrs67890"
      }
    }
  }
}, {
  "code" : 200,
  "document" : {
    "person" : {
      "abilitec" : {
        "consumerLink" : "T001US02fgh09876"
      }
    }
  }
} ]

Native to Other Batch Call Examples

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" : {
      "abilitec" : {
        "consumerLink" : "T999US02xyz12345"
      }
    }
  }
}, {
  "code" : 200,
  "document" : {
    "person" : {
      "abilitec" : {
        "consumerLink" : "T999US02bcd54321"
      }
    }
  }
} ]