API Reference

Authentication

Pass your API key in the Authorization header:

curl -H "Authorization: Bearer sk_solid_your_api_key" \
     https://api.solidnumber.com/api/v1/crm/contacts

Get your API key: Quickstart guide | Full auth docs

API Categories

Quick Examples

GET /api/v1/crm/contacts?limit=10&search=john

POST /api/v1/crm/deals
{
  "title": "Kitchen Remodel",
  "stage": "New",
  "amount": 1200000,
  "contact_id": 42
}

POST /api/v1/sms/send
{
  "to_phone": "+18015551234",
  "message": "Thanks for your inquiry! We'll call you within the hour."
}

POST /api/v1/chat/message
{
  "message": "Draft a proposal for contact 42 based on their last call",
  "conversation_id": "session_abc"
}

# 1. Dashboard mints (auth required — Bearer or session)
POST /api/v1/auth/install-token
Authorization: Bearer <user_jwt>

→ { "token": "ist_xxx...", "expires_at": "...", "company_id": 99999 }

# 2. CLI installer redeems (token IS the auth, no other header)
POST /api/v1/auth/install-token/exchange
Content-Type: application/json
{ "token": "ist_xxx...", "label": "CLI" }

→ { "access_token": "...", "refresh_token": "...", "user": { ... } }

Rate Limits

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. On exhaustion you get 429 Too Many Requests with a Retry-After header (seconds).

Pagination

All list endpoints use offset/limit pagination. Defaults: limit=50, offset=0. Max limit is 200 per request.

GET /api/v1/crm/contacts?limit=50&offset=0

{
  "items": [ ... 50 contacts ... ],
  "total": 1247,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

For exports over 10K rows, use solid CLI with --all --format csv — it auto-paginates and streams.

Errors

Every error response shares the same envelope: HTTP status + JSON body with code, message, and an optional details array for validation failures.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": "validation_error",
  "message": "Field 'amount' must be a positive integer (cents)",
  "details": [
    { "field": "amount", "error": "must_be_positive", "received": -500 }
  ],
  "request_id": "req_01JABCDEFGH123456789"
}

Idempotency

Every POST that creates a resource (orders, payments, invoices, messages) accepts an Idempotency-Key header. Retry-safe: the same key replays the first response for 24 hours. Different key + same payload creates a new resource.

curl -X POST https://api.solidnumber.com/api/v1/orders/ \
  -H "Authorization: Bearer sk_solid_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 42, "amount": 120000}'

Sandbox & Test Mode

Webhooks

Subscribe to events via POST /api/v1/webhooks. Every outbound payload is HMAC-SHA256 signed — verify the X-Solid-Signature header against your webhook secret before trusting the body.

# Node.js verification
const crypto = require('crypto')
const sig = req.headers['x-solid-signature']
const expected = crypto
  .createHmac('sha256', process.env.SOLID_WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex')
if (sig !== expected) return res.status(401).send('bad signature')

Retries: exponential backoff, 5 attempts over ~24h. Full webhook docs →

Versioning

The API is versioned via URL path (/api/v1/). Breaking changes get a new major version. Deprecated endpoints return a Sunset header with the removal date (minimum 6 months notice).

• Non-breaking additions (new endpoints, new optional fields, new enum values) ship to v1 without notice.
• Breaking changes (removed endpoints, required-field changes, enum removals) ship as v2 with parallel v1 support for 12 months.
• Multi-tenancy is foundational — every endpoint auto-scopes to the company_id of your API key. You cannot cross-read tenants.

OpenAPI Specification

We publish OpenAPI 3.0 specs in machine-readable form so you can generate typed SDKs, render interactive docs (Swagger UI, Redoc, Stoplight), validate requests, and run contract tests against the API. There are two specs — one public, one auth-gated — covering different surface areas.

Generate a client

# TypeScript client from the public spec
npx @hey-api/openapi-ts \
  -i https://solidnumber.com/api/mcp/openapi.json \
  -o ./src/solid-client

# Python client (openapi-python-client)
openapi-python-client generate \
  --url https://solidnumber.com/api/mcp/openapi.json

For the full REST spec, download the JSON from the dashboard and pass the local path to the same generators. First-party SDKs (JS/Python/Go/Ruby) are on the SDK roadmap — if you only need a typed client today, codegen from the spec is the path.

Tools & SDKs