API Docs

Authentication

The account is derived from the authenticated key alone. Order and customer bodies never carry an account id, so one client can never write into another's data.

Auth failures with an ingest key, in the order they are checked:

Errors

Errors are JSON {"detail": "…"} unless noted. There is no path version today; unknown request fields on orders and customers are silently ignored (see FAQ).

Limits

Step 1 — Verify the key

Set TELLTALE_API_KEY in your environment (the account is derived from the key), then:

curl -s https://api.telltale.pro/ingest/health \
  -H "Authorization: Bearer $TELLTALE_API_KEY"

{"ok":true,"account_id":"…","connected_integrations":["custom-api"],"orders_ingested":0,"store_timezone":null,"hint":"…"}

Then set your store timezone (IANA name only):

curl -s -X PATCH https://api.telltale.pro/ingest/account \
  -H "Authorization: Bearer $TELLTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_timezone":"America/New_York"}'

Step 2 — Historical backfill

1. Dry-run a sample first. POST /ingest/orders?dry_run=true (and /ingest/customers?dry_run=true) validates every row and writes nothing: per-row error codes and warnings come back so you fix the export before loading a year of history. See the Dry run reference below.
2. Customers first (consent and subscriptions): POST /ingest/customers in pages of up to 5,000. Include external_id (must equal the customer_id you use on orders), email, phone in E.164, consent, and subscription_status if you run subscriptions.
3. Orders: POST /ingest/orders in pages of up to 5,000 rows and under 32 MiB, oldest first, at least 12 months. Overlapping pages are safe (idempotent on order_id); if a run dies, restart from the last page you got a 200 for. GET /ingest/batches is your audit trail of what each page did.
4. Size batches well under both caps. On a plain-text 413, split by bytes; on a JSON 413, split by rows. On a 500 from orders nothing was written, so fix and retry the same batch.
5. Read the response counters. Treat dropped_invalid > 0 as a bug in your export: it means an unparseable order_date or order_amount, or a row whose customer id, email and phone are all blank. A missing required field is a 422 for the whole request instead (see FAQ).

Step 3 — Ongoing sync

• New or updated orders: POST a batch of one, or micro-batch every minute. Re-posting the same order_id merges lifecycle fields: refunds and cancels only ever move forward, and order_date and customer_id never change.
• Refunds: re-POST the whole order row (all required fields, unchanged order_amount) with the new cumulative refunded_amount. order_amount stays the gross total; Telltale nets refunds itself. This drives net revenue and any fee credits.
• Cancellations: re-POST with cancelled_at.
• Consent changes (STOP, unsubscribe): re-POST the customer with consent.sms=false or consent.suppressed=true, or send one event to POST /webhooks/custom-api. Telltale otherwise learns suppressions only from connected email and SMS providers.
• The nightly recompute at 02:00 UTC picks everything up. Call POST /ingest/sync only after large loads.

Step 4 — Install the on-site pixel (optional)

1. Settings → On-site tracking: add your storefront origins (scheme://host, no path, up to 50) and copy the snippet.
2. Consent: add data-telltale-consent="required" and call window.telltale('consent','granted') from your consent manager. Global Privacy Control is honoured. Events without granted consent are dropped silently.
3. Single-page apps: call window.telltale('track', 'page_view' | 'add_to_cart' | 'checkout_started') on route changes. Set product_external_id to the same product id you send on orders.

<script async src="https://api.telltale.pro/pixel/v1/telltale-pixel.js"
  data-telltale-key="pk_…" data-telltale-endpoint="https://api.telltale.pro/pixel/collect"></script>

Step 5 — Marketing consent

Consent is boolean today: consent.marketing_email, consent.sms, consent.suppressed, consent.bounced. SMS sends are gated on sms alone, so only set it true where you hold prior express written consent, and keep your own proof record. Consent provenance fields (when, how, source) are planned.

Step 6 — Coupons and attribution

Coupons today. Telltale never creates discount codes on any platform. Shopify, WooCommerce and BigCommerce libraries sync automatically; for a custom platform, enter codes by hand in Sightings → Templates & offers. Send discount_codes, discount_total and discount_pct on orders for discount-sensitivity analytics; codes are not used for attribution.

Attribution today. Every Telltale call-to-action links to your storefront with utm_source=telltale, utm_medium=<channel>, utm_campaign=<type> and utm_content=<tracking_id>. Orders are attributed either URL-precisely (when the order's source carries that utm_content) or by 7-day last-touch on the customer.

Also make sure your storefront domain is set on the account (the team can set it for you today; a self-serve field is planned). Telltale builds every call-to-action on top of it.

Step 7 — Trigger sync and verify

curl -s -X POST https://api.telltale.pro/ingest/sync \
  -H "Authorization: Bearer $TELLTALE_API_KEY"

{"queued":true,"task_id":"…","status_url":"/ingest/sync/…","message":"Analytics recompute queued. Poll status_url; fresh numbers appear once it completes."}

Poll the status_url (GET /ingest/sync/{task_id} with the same key) until status is done, failed or skipped; a few minutes is typical. Then check the app: the Nest Report shows metrics, Audience Builder lists scored customers, and Sightings shows opportunities. GET /ingest/health confirms the row count and GET /ingest/batches shows what happened to each page.

curl -s https://api.telltale.pro/ingest/sync/<task_id> \
  -H "Authorization: Bearer $TELLTALE_API_KEY"

Health

Verifies the key and reports current state. connected_integrations lists every connected provider, orders_ingested is the total order count for the account.

{"ok": true, "account_id": "<uuid>", "connected_integrations": ["custom-api", "klaviyo"],
 "orders_ingested": 12034, "store_timezone": "America/New_York",
 "hint": "POST /ingest/orders and /ingest/customers to load data, then POST /ingest/sync to recompute analytics."}

Orders

Batch upsert of 1 to 5,000 orders as {"orders": [ … ]}. The customer identity on each order is upserted too, so buyers do not need a separate customers call. Idempotent on order_id. The batch is one transaction.

Behaviour: an in-batch duplicate order_id is last-write-wins; rows with no customer id, email or phone are dropped and counted in dropped_invalid.

{"received": 2, "distinct_order_ids": 2, "deduped_in_batch": 0, "accepted": 2, "dropped_invalid": 0,
 "orders_upserted": 2, "customers_upserted": 1, "naive_timestamps": 0,
 "next": "POST /ingest/sync to recompute analytics for this account.",
 "warning": "<only when naive_timestamps > 0>"}

curl -s -X POST https://api.telltale.pro/ingest/orders \
  -H "Authorization: Bearer $TELLTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orders":[{"order_id":"A1001","customer_id":"C42","order_date":"2026-09-20T14:03:00-04:00","order_amount":86.4,"currency":"USD","product_name":"Oat Milk 12pk","email":"jo@example.com","phone":"+12125551212","source":"email","shipping_city":"Brooklyn","shipping_state":"NY","shipping_zip":"11201","discount_codes":["WELCOME10"],"discount_total":8,"discount_pct":8.5,"refunded_amount":0}]}'

Customers

Batch upsert of 1 to 5,000 customers as {"customers": [ … ]}. Identity resolves on external_id, then email, then phone, then creates a new customer. Use it for consent, addresses and subscription state; buyers are already created by orders.

{"received": 2, "customers_upserted": 2, "skipped_no_identity": 0, "subscriptions_applied": 1}

curl -s -X POST https://api.telltale.pro/ingest/customers \
  -H "Authorization: Bearer $TELLTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customers":[{"external_id":"C42","email":"jo@example.com","phone":"+12125551212","name":"Jo Park","address":{"street":"1 Main St","city":"Brooklyn","state":"NY","zip":"11201","country":"US"},"consent":{"marketing_email":true,"sms":false},"subscription_status":"active","subscription_started_at":"2026-02-01T00:00:00Z"}]}'

Account settings

Body {"store_timezone": "America/New_York"}. IANA names only; abbreviations like CST return 422. The value is stored and echoed on /ingest/health. Note: the recompute pipeline does not consume it yet, so local-time analytics still assume UTC until that lands.

Sync

No body. Queues a full analytics recompute for the account. Throttled to one call per 10 minutes per account (429 with Retry-After otherwise); the nightly recompute runs regardless.

{"queued": true, "task_id": "…", "status_url": "/ingest/sync/<task_id>", "message": "Analytics recompute queued. Poll status_url; fresh numbers appear once it completes."}

curl -s -X POST https://api.telltale.pro/ingest/sync \
  -H "Authorization: Bearer $TELLTALE_API_KEY"

Sync status

Status of a recompute this account queued. Task ids from other accounts (or unknown ids) return 404.

{"task_id": "…", "queued_at": "2026-09-22T20:00:00+00:00", "status": "queued | running | done | failed | skipped", "orders_added": 1200, "customers_added": 300, "duration_ms": 42000}

skipped carries a reason (for example already_running). Counters appear only when done.

Dry run

Same body and caps as the real call; nothing is written. Each row is checked exactly the way the write path would treat it. The call is logged in GET /ingest/batches with dry_run: true.

{"dry_run": true, "received": 2, "would_accept": 1, "would_drop": 1,
 "errors": [{"index": 1, "order_id": "A2", "codes": ["no_usable_identity"]}],
 "warnings": [{"index": 0, "order_id": "A1", "code": "unknown_fields_ignored", "fields": ["line_items"]}],
 "errors_truncated": 0, "next": "Fix any errors, then POST again without ?dry_run=true."}

Up to 50 errors and 50 warnings are returned; errors_truncated counts the rest.

curl -s -X POST "https://api.telltale.pro/ingest/orders?dry_run=true" \
  -H "Authorization: Bearer $TELLTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orders":[{"order_id":"A1001","customer_id":"C42","order_date":"2026-09-20T14:03:00-04:00","order_amount":86.4,"currency":"USD","product_name":"Oat Milk 12pk","email":"jo@example.com","phone":"+12125551212","source":"email","shipping_city":"Brooklyn","shipping_state":"NY","shipping_zip":"11201","discount_codes":["WELCOME10"],"discount_total":8,"discount_pct":8.5,"refunded_amount":0}]}'

Ingest activity

The last 1 to 200 batches for the account: endpoint, dry-run flag, status (accepted, rejected, error, queued), received/accepted/dropped counts, error and warning codes, duration, the sync task_id, and the key id used. Rows carry your own order and customer ids in error entries but never names, emails or phones. If you send an X-Request-Id header it is stored with the row so support can find it. Retained 90 days.

curl -s "https://api.telltale.pro/ingest/batches?limit=20" \
  -H "Authorization: Bearer $TELLTALE_API_KEY"

Customer event webhook

Single customer identity or consent event. Body is a free-form object with external_id (alias customer_id), email, phone, name, address, consent, event_type (default custom) and source_label. At least one of email, phone or external id is required.

Deduplicated per account on event_type + external_id (or a hash of the body). A duplicate returns {"received": true, "duplicate": true}; a failed attempt is re-processed on retry. This call also flips the Integrations tile from "Awaiting setup" to connected.

{"received": true, "customer_id": "<uuid>", "link_method": "provider_id|email|phone|fuzzy|created", "is_new": true}

curl -s -X POST https://api.telltale.pro/webhooks/custom-api \
  -H "Authorization: Bearer $TELLTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"C42","phone":"+12125551212","event_type":"sms_stop","consent":{"sms":false,"suppressed":true}}'

Zero-party data webhook

Quiz and preference submissions. Requires the separate token from the Zero-Party Data tile. Body: email, external_customer_id (aliases external_id, customer_id), interests[], attributes{}, source_label, quiz_version, completed_at. At least one of email or external id is required. Deduplicated on content, so a changed submission is a new event.

On-site events

Browser-only. Requires an Origin header on the pixel key's allow-list. Up to 50 events per call, 48 KB body. Unknown fields are rejected. Returns 204 on accept and also on a quiet drop (no consent, out of window).

{"key":"pk_…","events":[{"event_id":"<uuid>","event_type":"page_view|product_view|search|add_to_cart|checkout_started",
  "occurred_at":"2026-09-22T10:00:00Z","anonymous_id":"<1..128>","session_id":"<≤128>","url_path":"/p/oat-milk",
  "page_title":"…","referrer_host":"google.com","product_external_id":"p_88","collection":"…","search":"…",
  "price_cents":4000,"dwell_ms":1200,"consent_state":"granted","raw_props":{"utm_content":"<tracking_id>","sku":"OM-12"}}]}

The universal loader used by the snippet in Step 4. Cached for one hour.

Outbound webhooks (Telltale → you)

Available to workspaces with the API & webhooks settings page. Subscriptions are created in the app. Each delivery is a JSON POST {"event": "<type>", "data": { … }} with headers X-Telltale-Event, X-Telltale-Delivery (deduplicate on it) and X-Telltale-Signature, a hex HMAC‑SHA256 of the raw body with your whsec_… secret. Failed deliveries are retried up to three times with growing gaps (15, then 30, then 45 minutes).