Capture API
Create customer records through the supported external capture contract.
- For
- Developers and integration admins
- Owner
- Integration engineering
- Outcome
- Capture customer records through the supported external API.
- Last verified
- 2026-08-30
- Next review
- 2026-11-28
- Status
- supported
The Sakhaa Capture API is the supported external API for customer intake. Signed-in CRM application routes, provider callbacks, and platform routes are not public API contracts.
Create a dedicated API client
- Open API Clients as a company admin.
- Create one client for one external integration.
- Save the one-time secret in a server-side secret store.
- Set the default source, owner, field mappings, active state, and rate limit.
- Call GET /api/v1/capture/info before sending a person record.
Use X-API-Key and X-API-Secret. The Bearer token shown by the old Engage developer page is not the Capture API contract.
Capture one person
POST /api/v1/capture/person requires a name, an email or phone, and an Idempotency-Key header. The client mapping controls source, owner, and custom fields.
curl -X POST 'https://crm.sakhaa.ai/api/v1/capture/person' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: <API_KEY>' \
-H 'X-API-Secret: <API_SECRET>' \
-H 'Idempotency-Key: docs-test-0001' \
-d '{"name":"API Test Person","email":"api-test@example.invalid"}'Retry and bulk rules
- Reuse an idempotency key only when retrying the same logical request.
- Use a new key when the person data represents new work.
- For a 409 response, stop automatic retries and recover the earlier request manually.
- For a 503 response, retry only when the response marks the error as retryable. Keep the same key for the same request.
- Send no more than 100 people in one bulk request.
- Inspect successful, duplicates, and failed results before retrying a batch.
- Do not retry successful or duplicate results from a partially failed batch.
Security and operating limits
- Keep the secret on a server. Do not place it in browser code, URLs, logs, or support messages.
- Each client resolves one company and workspace boundary.
- The client has its own active state, rate limit, source, owner, and mappings.
- Browser origin metadata is not an authentication control. Keep the API secret on a trusted server.
- Regenerating the secret makes the old secret stop working immediately.
Download the contract
Use the published OpenAPI 3.1 file for request and response details. It includes only GET /info, POST /person, and POST /persons/bulk.