Lookup Table API
This feature is in beta
This requires that you have the lookup_table
feature enabled in Amplitude. Contact your Amplitude account manager if you need help.
Introduction¶
Lookup Tables let you augment user and event properties. Instead of using formulas, you can upload a CSV file that contains property mappings to derive new properties.
To create a Lookup property, create a Lookup Table to reference. You can retrieve and update each of the tables using the API. Lookup Tables are identified by the name and are scoped per project.
Get more examples for this API
Run our Postman Collection for a full library of example requests and responses for this API.
Endpoints¶
Region | Endpoint |
---|---|
Standard Server | https://amplitude.com/api/2/lookup_table |
EU Residency Server | https://analytics.eu.amplitude.com/api/2/lookup_table |
Authorization¶
This API uses Basic Auth, using the API key and secret key for your project. Pass your API key in the request header like {{api-key}}:{{secret-key}}
. api-key
replaces username, and secret-key
replaces the password.
Considerations¶
The max file size is 100 MB and the file can not have more than 1,000,000 rows.
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 the type multipart/form-data type.
Parameters¶
Name |
Description |
---|---|
name |
Required. String. Name of the table. |
file |
Required. File. A CSV representation of the mappings. |
Example request¶
POST '/api/2/lookup_table/:name' HTTP/1.1
Host: api2.amplitude.com
Authorization: Basic {{api-key}}:{{secret-key}}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=":name"; filename="file.csv"
Content-Type: text/csv
(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
Responses¶
-
Invalid file
-
File type is invalid. Accepted file types are
text/csv
,text/plain
, andtext/tab-separated-values
. -
File is empty
-
Found duplicate column header. There's a duplicate column, please remove the column so the file can be processed.
Retrieve a Lookup Table¶
Retrieve a Lookup Table by its name.
Parameters¶
Name |
Description |
---|---|
name |
Required. String. Name of the table. |
Example request¶
Response¶
Update a Lookup Table¶
Update a Lookup Table's columns and data.
Parameters¶
Name |
Description |
---|---|
name |
Required. String. Name of the table. |
file |
Required. File. A CSV representation of the mappings. |
Example request¶
PATCH /api/2/lookup_table/:name HTTP/1.1
Host: amplitude.com
Authorization: Basic {{api-key}}:{{secret-key}}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=":name"; filename="file.csv"
Content-Type: text/csv
(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
Response¶
- Requires at least one modification. There should be a file attached.
- File type is invalid. Accepted file types are
text/csv
,text/plain
, andtext/tab-separated-values
. - File is empty.
- Found duplicate column header. There's a duplicate column, please remove the column so the file can be processed.
Delete a Lookup Table¶
Delete a Lookup Table.
Parameters¶
Name |
Description |
---|---|
name |
Required. String. Name of the table. |
force |
Optional. Boolean. Delete the associated properties. Defaults to false . |
Example request¶
Response¶
List all Lookup Tables¶
List all the Lookup Tables for the project.
Example request¶
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"
}
]
}