Lookup Table API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

Requests go to https://amplitude.com (default) or https://analytics.eu.amplitude.com (EU). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not analytics.amplitude.com.

Considerations

The CSV file must meet the following requirements:

• The max file size is 100 MB and the file can't have more than 1,000,000 rows.
• The first row must contain column names/headers.
• The first column must correspond to the mapping property value and must contain unique values. Lookup Tables search for exact matches, and are case-sensitive.
• Columns must be separated by commas.
• Rows must be separated by line breaks.
• If a field value contains commas or quotes, wrap it in double quotation marks. The first double quote marks the start of the column data, and the last double quote marks the end. If the value contains a string with double quotes, replace each one with two double quotes ("").

Create a Lookup Table

Create a Lookup Table object by uploading a CSV that maps an existing property to the new properties to create. Send the request with content type multipart/form-data.

Parameters

Request

curl -L -X POST 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY \
        -F 'file=@"/path/to/file.csv"' \

Response

{
  "name": "skuToMetadata",
  "column_headers": ["Product Category", "Product Name"],
  "created_at": "2021-07-15T21:04:23.000593",
  "created_by": "rest",
  "last_modified_at": "2021-07-16T19:14:11.627477",
  "last_modified_by": "rest"
}

Retrieve a Lookup Table

Retrieve a Lookup Table by its name.

Parameters

Request

curl -L -X GET 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY

Response

{
  "name": "skuToMetadata",
  "column_headers": ["Product Category", "Product Name"],
  "created_at": "2021-07-15T21:04:23.000593",
  "created_by": "rest",
  "last_modified_at": "2021-07-16T19:14:11.627477",
  "last_modified_by": "rest"
}

Update a Lookup Table

Update a Lookup Table's columns and data.

Parameters

Request

curl -L -X PATCH 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY
        -F 'file=@"/path/to/file.csv"' \

Response

{
  "name": "skuToMetadata",
  "column_headers": ["Product Category", "Product Name"],
  "created_at": "2021-07-15T21:04:23.000593",
  "created_by": "rest",
  "last_modified_at": "2021-07-16T19:14:11.627477",
  "last_modified_by": "rest"
}

Delete a Lookup Table

Delete a Lookup Table.

Parameters

Request

curl -L -X DELETE 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY

Response

{
  "name": "skuToMetadata",
  "success": true
}

List all lookup tables

List all the Lookup Tables for the project.

curl -L -X GET 'https://amplitude.com/api/2/lookup_table' \
        -u API_KEY:SECRET_KEY

Response

{
  "data": [
    {
      "name": "isbnToMetadata",
      "column_headers": ["Genres", "Authors"],
      "created_at": "2021-07-15T21:04:23.000593",
      "created_by": "rest",
      "last_modified_at": "2021-07-16T19:14:11.627477",
      "last_modified_by": "rest"
    },
    {
      "name": "skuToMetadata",
      "column_headers": ["Product Category", "Product Name"],
      "created_at": "2021-07-16T19:28:18.070073",
      "created_by": "rest",
      "last_modified_at": "2021-07-16T19:28:18.070073",
      "last_modified_by": "rest"
    }
  ]
}