Data Handling

Pagination & Idempotency

Navigate large datasets efficiently with cursor-based pagination and protect against duplicate operations with idempotency keys.

Pagination

All list endpoints accept limit and offset query parameters to control the result set.

limit

Range: 1–100, default: 50

offset

Starting position, default: 0

Meta Object

Every paginated response includes an additive meta object alongside the data array.

Field	Type	Description
`limit`	`number`	Number of items requested (1–100).
`offset`	`number`	Starting position of the current page.
`total`	`number`	Total number of items matching the query.
`has_more`	`boolean`	Whether more items exist beyond this page.
`next_offset`	`number \| null`	Offset to use for the next page, or null if no more pages.

Example Response

GET /api/v1/leads?limit=2&offset=4

{
  "leads": [
    { "id": "ld_abc123", "name": "Jane Doe" },
    { "id": "ld_def456", "name": "John Smith" }
  ],
  "meta": {
    "limit": 2,
    "offset": 4,
    "total": 142,
    "has_more": true,
    "next_offset": 6
  }
}

Idempotency

POST (create) endpoints accept an optional Idempotency-Key header to prevent duplicate operations caused by network retries or application errors.

Max Length

200 characters

TTL

24 hours

Scope

Per account

How Idempotency Works

Send with Key

Include an Idempotency-Key header with a unique value (e.g., UUID) in your POST request.

Key is Stored

SyncFlo stores the key and response for 24 hours, scoped to your account.

Replay on Retry

If the same key is reused within 24 hours, the original response is replayed without re-executing.

Idempotent Request Example

POST with Idempotency Key

curl -X POST https://dashboard.syncflo.xyz/api/v1/leads \
  -H "Authorization: Bearer sfk_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "phone": "+919876543210" }'

# First request  → 201 Created (operation executed)
# Retry request  → 201 Created (response replayed)
#   includes header: Idempotent-Replayed: true

The replayed response includes an Idempotent-Replayed: true header so your application can detect replays.

Tips

Use UUIDs (v4) as idempotency keys for maximum uniqueness.

Generate a new idempotency key for each distinct operation — never reuse keys across different intents.

For pagination, prefer small page sizes (10–25) for real-time UIs and larger sizes (50–100) for background sync jobs.

Always check has_more before requesting the next page to avoid unnecessary API calls.

Essentials

Technical API