Conventions

​

Errors

{
  "error": {
    "code": "validation_error",
    "message": "caller_id must be E.164 format",
    "fields": {
      "caller_id": "Expected +<country><number>"
    }
  }
}

​

Error codes

​

Idempotency

curl -X POST https://api.lumisreach.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 9b8cfa7a-1c2d-4a88-b3c0-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{"caller_id": "+14155551234", "destination": "+14155556789"}'

​

Semantics

• First request with a key. We run the handler and persist the response under the key.
• Repeat with the same key and same body. We replay the saved response verbatim, including status code. The replay carries an Idempotency-Replay: true response header so you can tell.
• Repeat with the same key but a different body. We return 409 idempotency_conflict with the original key’s request id in fields.conflicts_with.

​

TTL

​

Best practices

• Use a new key for each new logical operation. Reusing keys across different calls drops traffic.
• The key is scoped to the API key it was submitted under. Rotating keys resets the idempotency window.
• Idempotency only protects the LumisReach side. Don’t rely on it for cross-process transactions (for example, a call placed plus a Stripe charge).

​

When to set one

• Retrying a request after a network timeout — critical.
• Background jobs that may re-run after a worker crash — critical.
• Interactive UIs with a double-click-vulnerable button — nice to have.

​

Pagination

{
  "data": [ /* items */ ],
  "meta": {
    "cursor": "opaque-string",
    "total_results": 42,
    "page_size": 20
  }
}

​

Example

# First page
curl "https://api.lumisreach.com/v1/calls?limit=50" \
  -H "Authorization: Bearer $KEY"

# Next page
curl "https://api.lumisreach.com/v1/calls?limit=50&cursor=eyJpZCI6MTIzfQ" \
  -H "Authorization: Bearer $KEY"

​

Limits

• limit default is 20, max 100.
• Cursors are valid for 24 hours from issuance. Requesting an expired cursor returns 400 validation_error with fields.cursor.
• Ordering is by creation time, newest first for every list endpoint. Use ?order=asc where supported to reverse.