Getting started

The SalesOS API is a JSON-over-HTTPS API rooted at:

https://api.salesos.org/v1

The machine-readable contract is the OpenAPI 3 document at GET /v1/openapi.json. It needs no authentication, and the API reference and the SDKs are generated from it.

1. Create an API key

1. In SalesOS, open Settings → API Keys and choose New API Key.
2. Name it after the integration that will use it, for example warehouse-sync.
3. Grant only the scopes it needs, for example READ_LEADS and WRITE_CONTACTS. See scopes.
4. Set an expiry (90 days is the default) and, if the integration runs from fixed addresses, an IP allow-list.
5. Copy the secret. It is shown once: SalesOS stores only a hash of it.

The key acts as you, in the organization you created it in. It never has more access than your own user, and your role and record visibility still apply.

2. Authenticate

Send the key in the X-API-Key header:

export SALESOS_API_KEY=sk_...
curl https://api.salesos.org/v1/leads?limit=5 \
  -H "X-API-Key: $SALESOS_API_KEY"

Authorization: ApiKey sk_... also works. API-key requests do not need a CSRF token or a session.

3. Read the response

List endpoints return one envelope:

{
  "data": [{ "id": "clx...", "firstName": "Ada", "status": "NEW" }],
  "page": 1,
  "limit": 5,
  "total": 42,
  "totalPages": 9,
  "hasMore": true
}

Every response also carries:

4. Write safely

Send an Idempotency-Key on every POST and PATCH so a retried request can't create a duplicate:

curl -X POST https://api.salesos.org/v1/leads \
  -H "X-API-Key: $SALESOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"firstName":"Ada","lastName":"Lovelace","email":"[email protected]","company":"Analytical Engines"}'

Next steps

• Authentication: scopes, expiry, rotation, IP allow-lists
• Requests: pagination, sorting and filtering
• Errors: the error shape and the codes to branch on
• API reference: every operation, with a try-it console
• GraphQL: read across objects, custom objects included
• Developer orgs: a free sandbox org to build in, and change sets to promote what you built