Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

Use this flow when you already have a customer record system (a CRM, a billing platform, your own database) and want Spotzee to mirror those contacts so you can market to them.

​
What you’ll build

A repeatable job that:
  1. Reads a batch of contacts from your source system.
  2. Sends them to Spotzee with external_id set to your stable customer ID.
  3. Uses an Idempotency-Key so timeouts and retries are safe.
  4. Walks through every page of source data without re-importing what’s already in.

​
Prerequisites

You’ll need a sk_ project key with write access. See Authentication for how to mint one.

​
Walkthrough

1

Pick a stable identifier

Choose the field in your source system that uniquely identifies a customer and never changes — usually the primary key from your customers table. Pass it to Spotzee as external_id on every contact.Spotzee uses external_id as the upsert key: re-syncing the same external id updates the existing contact rather than creating a duplicate.
2

Map your fields to Spotzee's schema

Spotzee contacts have a small set of first-class fields (email, phone, external_id, locale, timezone, first_name, last_name) and a flexible data object for anything else. Map your CRM columns to first-class fields where they line up; put everything else into data.
Your columnSpotzee field
customers.idexternal_id
customers.email_addressemail
customers.phone_e164phone
customers.localelocale
everything elsedata.<your_key>
3

Batch in groups of 100

POST /contacts/batch accepts up to 100 contacts per call. That’s the sweet spot for throughput and error handling — a smaller batch limits the blast radius of a partial failure.
4

Send each batch with an idempotency key

Generate a unique key per batch (a UUID derived from the first and last external_id works well — it’s deterministic, so a retry from a queue uses the same key).
POST /contacts/batch HTTP/1.1
Host: apix.spotzee.com
Authorization: Bearer sk_…
Idempotency-Key: sync-batch-cust_001-cust_100
Spotzee-Version: 2026-04-28
Content-Type: application/json

{
  "contacts": [
    {
      "external_id": "cust_001",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "data": { "lifetime_value": 4250 }
    }
  ]
}
5

Handle partial failures

The response includes a per-item errors[] array. Items that succeeded are committed; failed items are returned with their external_id and a code from the error catalogue. Retry only the failed items in a fresh request.
6

Walk every page of source data

Use cursor pagination on your source system the same way you’d page Spotzee — see Pagination. Persist the cursor so a crashed job resumes where it stopped.

​
Pitfalls to avoid

Don’t use the contact’s email address as external_id. Emails change. A stable, immutable customer ID — like the primary key of your customers table — is the right shape.
  • Don’t loop one contact at a time. Single-contact POST /contacts works, but you’ll burn rate-limit budget needlessly. Always batch.
  • Don’t reuse the same idempotency key for two different batches. Spotzee returns 409 idempotency_key_mismatch if you do. See Idempotency for the exact semantics.
  • Don’t write back to your source from the response. Spotzee returns its own id for each contact, but you should key off external_id on your side — that way a re-import doesn’t break.

​
Reference