Import many contacts

POST /contacts/batch runs up to 1000 operations in one request. Use it for a first load, and for a nightly sync.

The four operations

`op`	What it does
`upsert`	Creates the contact, or updates the one that matches. The default.
`update`	Updates the contact that matches. Never creates one.
`delete`	Deletes the profile.
`assign`	Sets or clears the account owner.

Name the contact with id, or with an identity such as external_id.

A batch

curl -X POST https://kaisupport.com/api/v1/contacts/batch \
  -H "Authorization: Bearer $KAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "op": "upsert", "data": {
          "external_id": "DK-1042",
          "name": "Ayşe Yılmaz",
          "email": "ayse@example.com",
          "attributes": { "package": "Tam Destek" }
      }},
      { "op": "assign", "external_id": "DK-1043", "owner": "baran@example.com" },
      { "op": "delete", "external_id": "DK-0007" }
    ]
  }'

Read the response

{
  "summary": { "total": 3, "created": 1, "updated": 0, "deleted": 1, "assigned": 1, "errors": 0 },
  "results": [
    { "index": 0, "op": "upsert", "status": "created", "id": "4f1d6f2a-..." },
    { "index": 1, "op": "assign", "status": "assigned", "id": "7d2b8e11-..." },
    { "index": 2, "op": "delete", "status": "deleted", "id": "8b2f1c40-..." }
  ]
}

One bad operation does not stop the others. Kai runs every operation and reports each one on its own. The status code describes the request, not the rows. A request that Kai understands returns 200, even when every operation in it failed. Always read summary.errors and the results array.

{
  "index": 4,
  "op": "upsert",
  "status": "error",
  "error": {
    "type": "invalid_attributes",
    "message": "Some attributes could not be stored.",
    "details": [{ "key": "exam_year", "message": "expected a number" }]
  }
}

Import 40,000 contacts

Create the attributes first

Send POST /attributes for each attribute that your rows carry. Kai refuses an attribute key that the workspace does not define.

Split the rows into batches of 1000

A larger request would run for minutes and can stop at a proxy timeout with no report of what it did.

Send the batches one after the other

Two batches that run at the same time can hold the same person and make two contacts. Send them in sequence.

Log the failed rows

Record index and error.type for each failed operation. Correct those rows and send them again.

import itertools, requests

API = "https://kaisupport.com/api/v1"
HEADERS = {"Authorization": f"Bearer {KAI_API_KEY}"}

def batches(rows, size=1000):
    it = iter(rows)
    while chunk := list(itertools.islice(it, size)):
        yield chunk

failures = []
for chunk in batches(contacts):
    body = {"operations": [{"op": "upsert", "data": row} for row in chunk]}
    response = requests.post(f"{API}/contacts/batch", json=body, headers=HEADERS)
    response.raise_for_status()
    result = response.json()
    failures += [r for r in result["results"] if r["status"] == "error"]
    print(result["summary"])

print(f"{len(failures)} rows failed")

Repeat a batch safely

An upsert matches on identity, so the same batch sent twice updates the same contacts. It does not make copies. Give every row an external_id if your system has one. It is the strongest match, because you control it. See Identity.

Start here

Concepts

How to

Import many contacts

The four operations

A batch

Read the response

Import 40,000 contacts

Repeat a batch safely

​The four operations

​A batch

​Read the response

​Import 40,000 contacts

​Repeat a batch safely

The four operations

A batch

Read the response

Import 40,000 contacts

Repeat a batch safely