---
updatedAt: 2026-04-07T10:11:22.000Z
agentTools:
  siteIndex: https://developers.liveramp.com/llms.txt
  projectIndex: https://developers.liveramp.com/authenticatedtraffic-api/v1.0/llms.txt
---

# Custom ID Support

How to pass your own user ID in lieu of a "raw" identifier or hash.

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.

[block:api-header]
{
  "title": "Preparing the File"
}
[/block]

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 <ats@liveramp.com>.

The file should contain your company name, the type of upload (AKP) and the current date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format separated by underscores. For example:

`IansCompany_AKP_2020-03-01.tsv`

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](https://docs.liveramp.com/connect/en/hashing-identifiers.html) for more information on proper hashing.

[block:code]
{
  "codes": [
    {
      "code": "CID\tEmail Address\n0d755934-693e-42c7-b04a-761a9c82df60\ta34ecb1e766ae1810eea54d7afef166cb8d46e5d\n25f5d3bf-09bb-4e76-8cb8-26707d3fb580\tb90390936408cf5e4e48ae29f5842a6513bbdd5f\n1935519e-3bc7-44ee-817d-90e34e9ef303\tb5bc5a9bafb153cc706f4e2cb30c49310073c9c0\n00abb44f-94a2-4939-b072-1704f335d3d2\t534746696bda4a9ff15257690bd2b3225b8fe08a\n7ed142b0-edf6-4fe5-8050-7fd70ac51183\tb5f13ee91506cd7107c943701d176c1b17cee247\nbb0069b4-2827-4e04-838d-ecaec8e2485c\t3cb028c8292f1111b61222c2931ca4f73bc79fff\n07e9a9ba-8797-450b-9326-c6fdb273eb88\tbd330c98fc82090b94ae7fc938cf633d5133fbf4\nfa667ab6-bcc0-46d9-9ddd-f5c30a433f2a\tccd6421f4371fdcea89c041f2d2a880479f5b6b5\n57162817-76d0-484f-a553-9d6f50f3bb19\ted5fc0a6644ea65e3857d69b5ac2547759668c50",
      "language": "text",
      "name": "IansCompany_AKP_2020-03-01.tsv"
    }
  ]
}
[/block]

You may use gzip compression on the file before upload.

[block:api-header]
{
  "title": "Sending the File"
}
[/block]

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 <ats@liveramp.com>.

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. Note: LiveRamp recommends [Cyberduck](http://www.cyberduck.ch/), a free client that works on Mac and PC.
4. In the "Host" field, enter "files.liveramp.com".
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. Note: If you run into problems with the transfer, please see the [troubleshooting SFTP uploads](https://liveramp.elevio.help/en/articles/53501) article.

[block:callout]
{
  "type": "success",
  "body": "To account for newly registered users, we recommend uploading new files on a weekly basis.",
  "title": "Recurring Uploads"
}
[/block]

[block:api-header]
{
  "title": "Configuring ATS for Custom IDs"
}
[/block]

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 you must include in your configuration. You must also include a  regular expression for your identifier in `customerIDRegex`. 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. If you opt for detection, ensure that you pass `"detectionSubject": "customerIdentifier"` alongside any other required attributes (such as `detectionType`).

[block:api-header]
{
  "title": "Sample Configurations"
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "  {\n    \"logging\": \"debug\", \n    \"placementID\": 9999, \n    \"detectionType\": \"url\",\n    \"urlParameter\": \"customerid\"\n    \"detectionSubject\": \"customerIdentifier\",\n    \"customerIDRegex\": \"[0-9a-f]{32}\\Z\",\n    \"accountID\": \"123456\"\n  }",
      "language": "json",
      "name": "Custom ID Detection"
    }
  ]
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "  {\n    \"logging\": \"debug\", \n    \"placementID\": 9999, \n    \"customerIDRegex\": \"[0-9a-f]{32}\\Z\",\n    \"accountID\": \"123456\",\n    \"customerID\": \"0d755934-693e-42c7-b04a-761a9c82df60\"\n  }",
      "language": "json",
      "name": "Custom ID Direct"
    }
  ]
}
[/block]