SalesOS

Getting Started

Start building with the SalesOS API in minutes.

The developer portal is the complete guide to API keys, scopes, OAuth, rate limits, idempotency, events and versioning. These pages are a short overview.

Base URL

All API requests go to:

https://api.salesos.org/v1

The machine-readable contract is the OpenAPI document at /v1/openapi.json.

Quick Start

1. Create an API key

Open Settings → API Keys, choose New API Key, grant only the scopes the integration needs (for example READ_LEADS), and copy the secret — it is shown once. See scopes.

2. Make your first request

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

3. Read the response

List endpoints return one envelope:

{
  "data": [
    { "id": "clx8k2…", "firstName": "Jane", "lastName": "Smith", "email": "[email protected]", "status": "NEW", "createdAt": "2026-01-15T10:30:00.000Z" }
  ],
  "page": 1,
  "limit": 5,
  "total": 42,
  "totalPages": 9,
  "hasMore": true
}

Authentication

MethodHeaderBest for
API keyX-API-Key: <key>Server-to-server integrations and scripts
OAuth 2.0 access tokenAuthorization: Bearer <token>Apps that act for other users or organizations
Session tokenAuthorization: Bearer <token>The SalesOS web app

See Authentication.

Request format

  • Request bodies are JSON with Content-Type: application/json.
  • IDs are opaque strings; don't parse them.
  • Timestamps are ISO 8601 in UTC (2026-01-15T10:30:00.000Z).
  • Unknown body fields are rejected with 400.
  • Send an Idempotency-Key on POST and PATCH so a retry can't create a duplicate (idempotency).

Errors

Every error has the same shape, with a stable code to branch on:

{
  "statusCode": 403,
  "code": "API_KEY_SCOPE_INSUFFICIENT",
  "message": "This key lacks WRITE_LEADS",
  "timestamp": "2026-10-01T09:30:00.000Z",
  "path": "/v1/leads",
  "requestId": "6f1c…"
}

Next steps

Authentication

Authenticate with the SalesOS API using API keys, OAuth 2.0 access tokens or a user session.

On this page