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"
}

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.

Tools & SDKs