Imports

Bring a CSV of contacts in. The file is uploaded in one request and processed in the background; the import records what happened to every row.

The column map

column_map says which CSV column holds which field, and which columns become typed properties. A property entry is a column name, or { column, type } with type one of string, number or boolean — the default is string.

{
  "email": "Email",
  "first_name": "First name",
  "last_name": "Last name",
  "unsubscribed": "Opted out",
  "properties": {
    "plan": "Plan",
    "seats": {
      "column": "Seats",
      "type": "number"
    }
  }
}

What happens to a row

A new address is created. An address that already exists is updated with the row's values when on_conflict is upsert, and skipped when it is skip, the default.
A row with no usable address, a value that does not match its property's type, or a row past your plan's contact limit is failed. The first thousand failures are kept with their row numbers.
Rows are processed in batches, so an import that is in_progress already has some of its contacts. No contact.created webhook is sent per row.
The file is deleted seven days after the import completes. The counts stay.

Endpoints

POST /contacts/imports

Upload a file of up to 50 MB; the rows are processed in the background.

Body

Body
Field	Type	Description
`file`*	file	The CSV, up to 50 MB, as a multipart part.
`column_map`	string	A JSON object mapping `email`, `first_name`, `last_name`, `unsubscribed` and `properties` to column names. A property entry is a column name, or `{ column, type }` with `type` one of `string`, `number` or `boolean`.
`on_conflict`	string	`upsert` updates a contact whose address already exists; `skip` (the default) leaves it alone.

2 more fields (segments, topics)

Body, less common
Field	Type	Description
`segments`	string	A JSON array of `{ id }` segments every imported contact is added to.
`topics`	string	A JSON array of `{ id, subscription }` topic choices applied to every imported contact.

curl -X POST "https://api.rasket.com/contacts/imports" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -F "file=@contacts.csv" \
  -F "column_map={\"email\":\"Email\",\"first_name\":\"First name\",\"properties\":{\"plan\":\"Plan\"}}" \
  -F "on_conflict=upsert" \
  -F "segments=[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]"

const form = new FormData();
form.append("file", new Blob([csv]), "contacts.csv");
form.append("column_map", "{\"email\":\"Email\",\"first_name\":\"First name\",\"properties\":{\"plan\":\"Plan\"}}");
form.append("on_conflict", "upsert");
form.append("segments", "[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]");

const response = await fetch("https://api.rasket.com/contacts/imports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
  body: form,
});

const { id } = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/contacts/imports",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    files={"file": open("contacts.csv", "rb")},
    data={
        "column_map": "{\"email\":\"Email\",\"first_name\":\"First name\",\"properties\":{\"plan\":\"Plan\"}}",
        "on_conflict": "upsert",
        "segments": "[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]",
    },
)

id = response.json()["id"]

Response `201`

{
  "object": "contact_import",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17"
}

The response is immediate; poll the import for its counts.
No contact.created or contact.updated webhook is sent per row. One audit entry records the import.
Rows past your plan's contact limit are counted as failed.

GET /contacts/imports

Every import, newest first.

Query parameters

Query parameters
Field	Type	Description
`status`	string	`queued`, `in_progress`, `completed` or `failed`.
`limit`	integer	How many items to return, 1–100. Defaults to 20.
`after`	string	Return the page that follows this item ID. Mutually exclusive with `before`.
`before`	string	Return the page that precedes this item ID. Mutually exclusive with `after`.

curl -X GET "https://api.rasket.com/contacts/imports?status=completed" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/contacts/imports?status=completed", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/contacts/imports?status=completed",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())

Response `200`

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_import",
      "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
      "status": "completed",
      "created_at": "2026-09-08T22:22:17.595Z",
      "completed_at": "2026-09-08T22:24:01.330Z",
      "counts": {
        "total": 1240,
        "created": 1180,
        "updated": 40,
        "skipped": 15,
        "failed": 5
      }
    }
  ]
}

GET /contacts/imports/{id}

One import, with its status and counts.

Path parameters

Path parameters
Field	Type	Description
`id`*	string	The import's ID.

curl -X GET "https://api.rasket.com/contacts/imports/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/contacts/imports/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/contacts/imports/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]

Response `200`

{
  "object": "contact_import",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
  "status": "completed",
  "created_at": "2026-09-08T22:22:17.595Z",
  "completed_at": "2026-09-08T22:24:01.330Z",
  "counts": {
    "total": 1240,
    "created": 1180,
    "updated": 40,
    "skipped": 15,
    "failed": 5
  }
}

counts is { total, created, updated, skipped, failed }. completed_at is null until the import finishes.
The uploaded file is deleted seven days after the import completes; the counts stay.

The column map

What happens to a row

Endpoints

POST /contacts/imports

Body

Response 201

GET /contacts/imports

Query parameters

Response 200

GET /contacts/imports/{id}

Path parameters

Response 200

Response `201`

Response `200`

Response `200`