Skip to main content

Custom ID Support

It is possible to pass (or detect) custom IDs instead of typical identifiers such as email addresses and phone numbers. In order to use a custom, publisher-provided identifier within ATS, you will need to send LiveRamp a mapping file on a regular basis.


Custom ID is Not Available for All Publishers

Due to the complexity of the mapping process, custom ID support is only available for selected publishers who must go through an extensive onboarding process. Please note you cannot pass custom IDs out-of-the-box.

Preparing the File

While LiveRamp is able to flexibly handle most file layouts, we recommend you produce a file as described below. If you would like to create a different file layout or structure, please contact us at

The file should contain your company name, the type of upload (AKP) and the current date in ISO 8601 format separated by underscores. For example:


The contents of the file should contain two tab-separated columns, titled “CID” and “Email Address”. The first column should contain the userIDs you will input to ATS. The second column should contain a SHA-256 hashed email address. Ensure that you downcase the email and remove whitespace before hashing it. See this article for more information on proper hashing.

CID Email Address
0d755934-693e-42c7-b04a-761a9c82df60    a34ecb1e766ae1810eea54d7afef166cb8d46e5d
25f5d3bf-09bb-4e76-8cb8-26707d3fb580    b90390936408cf5e4e48ae29f5842a6513bbdd5f
1935519e-3bc7-44ee-817d-90e34e9ef303    b5bc5a9bafb153cc706f4e2cb30c49310073c9c0
00abb44f-94a2-4939-b072-1704f335d3d2    534746696bda4a9ff15257690bd2b3225b8fe08a
7ed142b0-edf6-4fe5-8050-7fd70ac51183    b5f13ee91506cd7107c943701d176c1b17cee247
bb0069b4-2827-4e04-838d-ecaec8e2485c    3cb028c8292f1111b61222c2931ca4f73bc79fff
07e9a9ba-8797-450b-9326-c6fdb273eb88    bd330c98fc82090b94ae7fc938cf633d5133fbf4
fa667ab6-bcc0-46d9-9ddd-f5c30a433f2a    ccd6421f4371fdcea89c041f2d2a880479f5b6b5
57162817-76d0-484f-a553-9d6f50f3bb19    ed5fc0a6644ea65e3857d69b5ac2547759668c50

You may use gzip compression on the file before upload.

Sending the File

We recommend you deliver a file over SFTP. If you would like us to retrieve the file from a location you control, please contact us at

Follow the steps below to upload a file via LiveRamp's SFTP with an SFTP client.

  1. Make sure that the file is formatted correctly and not password-protected.

  2. If using a firewall, enable outgoing port 8442 or 22.

  3. Sign in to your SFTP client.


    LiveRamp recommends Cyberduck, a free client that works on Mac and PC.

  4. In the "Host" field, enter "".

  5. Enter the username and password given to you by your LiveRamp representative.

  6. If it does not already exist, create a new subdirectory within “/uploads” named “akp”.

  7. Upload the file to the “/uploads/akp” directory, or to the subdirectory for the.


    If you run into problems with the transfer, please see the troubleshooting SFTP uploads article.


Recurring Uploads: To account for newly registered users, we recommend uploading new files on a weekly basis.

Configuring ATS for Custom IDs

Once we have confirmed successful ingestion of your first mapping file, you will need to configure ats.js for your newly-created custom identifier.

We will provide you with an accountID, which will be included in your configuration. You must also include a regular expression for your identifier in "Customer ID Regex" field within the Console setup. This regular expression enables ats.js to validate that identifiers match an expected pattern.

Similar to using ats.js with raw identifiers, you can either pass your identifier directly in the configuration (as the customerID) parameter, or let ats.js operate in detect mode.