{% callout type="deprecated" heading="This version of the Lookup Tables API is deprecated" %}
This API is no longer supported. Use the new [API](/docs/apis/analytics/lookup-table-2).
{% /callout %}

## 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`.

| Data residency | Base URL                             |
| -------------- | ------------------------------------ |
| Default        | `https://amplitude.com`              |
| EU             | `https://analytics.eu.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

| Name   | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `name` | String | Yes      | Name of the table.                    |
| `file` | File   | Yes      | A CSV representation of the mappings. |

### Request

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

```bash HTTP
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
```
{% /code-group %}

### Response

{% tabs tabs="Success, HTTP 400: Bad request, HTTP 409: Conflict, HTTP 413: Payload too large" %}
{% tab name="Success" %}

```json
{
  "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"
}
```

{% /tab %}
{% tab name="HTTP 400: Bad request" %}

```bash
HTTP 400: Bad Request
```

- Invalid file
- File type is invalid. Accepted file types are `text/csv`, `text/plain`, and `text/tab-separated-values`.
- File is empty
- Found duplicate column header. Remove the duplicate column so the file can be processed.

{% /tab %}
{% tab name="HTTP 409: Conflict" %}

```bash
HTTP 409: Conflict (Conflict, name already exists)
```

The table already exists
{% /tab %}
{% tab name="HTTP 413: Payload too large" %}

```bash
HTTP 413: Payload Too Large
```

The file exceeds the max size.

{% /tab %}
{% /tabs %}

## Retrieve a Lookup Table

Retrieve a Lookup Table by its name.

### Parameters

| Name   | Type   | Required | Description        |
| ------ | ------ | -------- | ------------------ |
| `name` | String | Yes      | Name of the table. |

### Request

{% code-group %}
```curl cURL
curl -L -X GET 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY
```

```bash HTTP
GET /api/2/lookup_table/:name HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key}
```
{% /code-group %}

### Response

{% tabs tabs="Success, HTTP 400: Not found" %}
{% tab name="Success" %}

```json
{
  "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"
}
```

{% /tab %}
{% tab name="HTTP 400: Not found" %}

```bash
HTTP 404: Not found
```

The table wasn't found because it wasn't created.
{% /tab %}
{% /tabs %}

## Update a Lookup Table

Update a Lookup Table's columns and data.

### Parameters

| Name   | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `name` | String | Yes      | Name of the table.                    |
| `file` | File   | Yes      | A CSV representation of the mappings. |

### Request

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

```bash HTTP
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
```
{% /code-group %}

### Response

{% tabs tabs="Success, HTTP 400: Bad request, HTTP 404: Not found, HTTP 413: Payload too large" %}
{% tab name="Success" %}

```json
{
  "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"
}
```

{% /tab %}
{% tab name="HTTP 400: Bad request" %}

```bash
HTTP 400: Bad Request
```

- Requires at least one modification. There should be a file attached.
- File type is invalid. Accepted file types are `text/csv`, `text/plain`, and `text/tab-separated-values`.
- File is empty.
- Found duplicate column header. Remove the duplicate column so the file can be processed.

{% /tab %}
{% tab name="HTTP 409: Conflict" %}

```bash
HTTP 404: Not found
```

The table wasn't found because it wasn't created.
{% /tab %}
{% tab name="HTTP 413: Payload too large" %}

```bash

HTTP 413: Payload Too Large
```

The file exceeds the max size.
{% /tab %}
{% /tabs %}

## Delete a Lookup Table

Delete a Lookup Table.

### Parameters

| Name    | Type    | Required | Description                                            |
| ------- | ------- | -------- | ------------------------------------------------------ |
| `name`  | String  | Yes      | Name of the table.                                     |
| `force` | Boolean | No       | Delete the associated properties. Defaults to `false`. |

### Request

{% code-group %}
```curl cURL
curl -L -X DELETE 'https://amplitude.com/api/2/lookup_table/:name' \
        -u API_KEY:SECRET_KEY
```

```bash HTTP
DELETE /api/2/lookup_table/:lookup_table_name?force=True HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key}
```
{% /code-group %}

### Response

{% tabs tabs="Success, HTTP 404: Not found" %}
{% tab name="Success" %}

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

{% /tab %}
{% tab name="HTTP 404: Not found" %}

```bash

HTTP 404: Not found
```

The table wasn't found.
{% /tab %}
{% /tabs %}

## List all lookup tables

List all the Lookup Tables for the project.

{% code-group %}
```curl cURL
curl -L -X GET 'https://amplitude.com/api/2/lookup_table' \
        -u API_KEY:SECRET_KEY
```

```bash HTTP
GET /api/2/lookup_table HTTP/1.1
Host: amplitude.com
Authorization: Basic {{api-key}}:{{secret:key}}
```
{% /code-group %}

### Response

```json
{
  "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"
    }
  ]
}
```