API authentication

Yesoma exposes a small REST API under /api/v1/* for reading and writing the resources you can see in the app: customers, inquiries, follow-ups. Call it from your own scripts, dashboards, or automation.

Create an API key

1. Open Settings → API → Create key.
2. Give it a label and pick scopes (the permissions the key has).
3. Yesoma shows the key once — copy it now. It looks like yk_live_.... You can't read it again; only revoke it.

Scopes

Each scope unlocks a specific surface:

| Scope | Allows | | --- | --- | | read:customers | GET /api/v1/customers, GET /api/v1/customers/:id | | write:customers | Create or update customers | | read:inquiries | List and read inquiries | | write:inquiries | Create inquiries; reply via the API | | read:followups | List follow-ups | | write:followups | Create or complete follow-ups |

Pick the smallest scope set the integration needs. You can rotate keys any time.

Authenticate

Send the API key in the Authorization header as a bearer token:

curl https://app.getyesoma.com/api/v1/customers \
  -H "Authorization: Bearer yk_live_..." \
  -H "Accept: application/json"

Every successful response includes a X-Yesoma-Request-Id header you can quote when contacting support.

Rate limits

Generous workspace-level limits (hundreds of requests per minute). If you hit them, the response is 429 with a Retry-After header. Back off and retry.

Errors

Standard HTTP semantics:

• 400 — your request body is malformed.
• 401 — missing or wrong API key.
• 403 — your key doesn't have the required scope.
• 404 — the resource doesn't exist or isn't in this workspace.
• 429 — rate limited.
• 5xx — Yesoma's problem; retry.

The body is always { "error": "...", "detail": "..." }.

Revoke

Settings → API → key row → Revoke. Effective immediately. Any in-flight requests with the revoked key get 401.

Related

• Webhook events for push-style integrations
• Slack alert recipe