4. File format specs

All files must comply with this standard formatting so our ingestion process can run correctly.

Name and File Extension

Files can be placed either at the directory root or within any subdirectory. Some important considerations:

1. They can be named in any way, but cannot contain any white spaces and must have a .tsv or .tsv.gz extension.
2. If using compression, GZIP must be used exclusively.
3. All files must bu formatted in tab separated values or tsv. No comma separated files will be admitted.

File Format

The first line within the .tsv file must be a header line, and only the following will be accepted:

• device_type (required): type of identifier being sent. See below for accepted identifiers.
• device_id (required): the identifier's value.
• segments (required): a list of comma-separated Segment IDs to be assigned to this individual identifier, per your Taxonomy Definition.
• country_code (optional): ISO-code for the country the identifier belongs to. It is not a required column, but we encourage you to add it if possible.
• partner_segment_id (optional): our ID associated with a segment. It can be used as an internal identifier or for segment mapping and population via Data-IN, taking this ID as a reference.
• remove_segments (optional): Remove devices that have been associated (populated) a segment.
• remove_partner_segment_id (optional): Same case as the previous one but I use this ID as a guide and not the Segment ID.

Accepted identifier types for the "device_type" column:

• web: a Retargetly web cookie identifier, can be desktop, tablet or mobile.
• android: exclusive for Google Advertising IDs (GAID or AAID), no cookies.
• ios: exclusive for IDs For Advertising (IDFA), no cookies.
• external_id: a third party ID, needs to be previously synced through the User Cookie Sync Process.
• email: a user email, to be onboarded deterministically. Can be in plain text, SHA-256 or SHA-512.
• phone: a user phone number, can be mobile, home or work. Can be in plain text, SHA-256 or SHA-512. See Phone Number Formatting.
• nid: a user's national identification number, depending on the country can be a Documento Nacional de Identidad (DNI), Cedula de Identidad (CI), Cadastro de Pessoas Físicas (CPF), a Tax ID, and so on. Please reach out to us for more information on this.
• rely_encrypt: device_id is encrypted. To be able to use this field, its necessary to establish an encryption key before file uploads. Notify our team via email at desk@retargetly.com if you will like to use encrypted device identifiers.

Special considerations:

1. The columns must be separated not by a comma but by a TAB, also referenced as \t. But within a particular column, its values must be separated by a comma. And the final character in each line must be a line break (\n) and cannot be a carriage return (\r).
2. As previously mentioned, emails, phones and nids can be uploaded in plain text or hashed using SHA-256 or SHA-512. Don't use a salt when hashing. If you decide to send the identifiers in plain text, the ingestion process will overwrite the file and hash them using SHA-256 for storage. If you decide to hash them yourself, please follow these guidelines:
   1. email: no whitespaces of any kind, and all text must be lowercased. For example, "JohnApple@Mac.com " must be changed to "johnapple@mac.com".
   2. nid: no whitespaces, or special characters of any kind. Only include numbers. For example, "34.929-392 92" must be changed to "3492939292".
   3. phone: only include numbers and leave out dial tone numbers. Leave in only the country code, area code and number. For example: "+54 (9) 11 7282-3222" must be changed to "541172823222". See here for more detail.

Examples of valid and invalid files

Valid file

Includes all required headers, and formatting is correct. See that some emails for example can be hashed, and some in plain text. Each line will be treated individually.

device_type    device_id    country_code    segments
email    ejemplo@gmail.com    MX    111111,22222,33333
email    fc2ae4a1fb374548ea80556dc51ab3471a311231d8bffaa1dece31371bcceb62    AR    123456,123410,232322
android    1b671a64-40d5-491e-99b0-da01ff1f3341    AR    123123

Invalid files

Headers are missing.

email    ejemplo@gmail.com    111111,22222,33333
android    1b671a64-40d5-491e-99b0-da01ff1f3341    123123

Device type in value 2 is invalid. Should be email, not e-mail.

device_type    device_id    segments
android    1b671a64-40d5-491e-99b0-da01ff1f3341    123123
e-mail    ejemplo@gmail.com    111111,22222,33333

Using semicolon instead of tab to separate columns.

device_type;device_id;country_code;segments
email;ejemplo@gmail.com;MX;111111,22222,33333
email;fc2ae4a1fb374548ea80556dc51ab3471a311231d8bffaa1dece31371bcceb62    AR    123456,123410,232322
android;1b671a64-40d5-491e-99b0-da01ff1f3341;AR;123123

Not sending all required headers. All files must include at least device_type, device_id, and segments.

device_id
ejemplo@gmail.com
fc2ae4a1fb374548ea80556dc51ab3471a311231d8bffaa1dece31371bcceb62
1b671a64-40d5-491e-99b0-da01ff1f3341

If you have any additional questions, please reach out at desk@retargetly.com.