callbotagent.aiDocs
v1 · Contract draft
ENPL
Open dashboard
Preview

Upsert customer

Preview documentation / simulated contract (draft). Schemas and examples reflect the planned Commerce API v1 — final values will be confirmed when the production contract is frozen.

PUT /customers/{externalCustomerId}

Description

Profil, locale BCP 47 i dowodem zgody. Base URL: https://api.callbotagent.ai/api/v1/commerce.

Required scope

customers:write

Headers

Header Value Required
Content-Type application/json (gdy body) when body present
X-CBA-Key-Id key identifier (in examples: cba_test_••••••••) yes
X-CBA-Timestamp RFC 3339 UTC yes
X-CBA-Nonce unique nonce within the 300 s window yes
X-CBA-Content-SHA256 SHA-256 hex surowego body (e3b0c44… dla pustego) yes
X-CBA-Signature hmac-sha256=<hex> yes
Idempotency-Key idempotency key mutations: yes

Body parameters

Field Type Required Description
phone string yes E.164
locale string yes BCP 47, np. pl-PL
consent.status enum yes granted
consent.proof object warunkowo Wymagany przy granted
source_version string yes Source version

Example request

curl -X PUT https://api.callbotagent.ai/api/v1/commerce/customers/CUSTOMER-8821 \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-11T10:00:00Z" \
  -H "X-CBA-Nonce: n_8f3a2c1b" \
  -H "X-CBA-Content-SHA256: <sha256-body>" \
  -H "X-CBA-Signature: hmac-sha256=<hex>" \
  -H "Idempotency-Key: idem-customers-externalCustomerId-put" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+48512123456","locale":"pl-PL","consent":{"status":"granted","proof":{"source":"checkout_optin","reference":"form-2026-07-09-2231","collected_at":"2026-07-09T22:31:07Z"}},"source_version":"2026-07-11T09:00:00Z"}'

Example response

{
  "external_customer_id": "CUSTOMER-8821",
  "outcome": "upserted",
  "consent": {
    "status": "granted"
  }
}

Possible errors

Status code Meaning
401 invalid_signature / expired_timestamp / replay_nonce HMAC / replay window
403 insufficient_scope missing required scope
404 resource_not_found resource unavailable for principal
409 idempotency_key_reused / stale_source_version idempotency / version conflict
422 validation_failed body does not match schema / invariants
429 rate_limited limits — see Retry-After

Related