Polling for status - Instant Compliance API

Prefer webhooks. They push KYC/KYB and AML events to you in real time, signed and retried — no polling loop to run. Reach for polling when you can’t host an HTTPS endpoint, or as a periodic backstop alongside webhooks.

Polling is a robust way to learn that a customer’s KYC or AML status changed. Done well, it is deterministic (never misses a record) and frugal (only one or two API calls per polling interval).

The pattern in one paragraph

Track a “high water mark” timestamp in your own database. Each poll asks for customers updated after that timestamp, walks all pages, and advances the watermark to the latest updated_at you saw. That’s it.

Implementation

async function pollChangedCustomers({ watermark, apiKey }) {
  let cursor = null;
  let newWatermark = watermark;

  do {
    const url = new URL('https://app.instantcompliance.ai/api/v1/customers');
    url.searchParams.set('limit', '100');
    url.searchParams.set('updated_since', watermark);
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });

    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') ?? 30);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`Poll failed: ${res.status}`);

    const { data, has_more, next_cursor } = await res.json();
    for (const customer of data) {
      await upsertIntoYourCrm(customer);
      if (customer.updated_at > newWatermark) {
        newWatermark = customer.updated_at;
      }
    }
    if (!has_more) break;
    cursor = next_cursor;
  } while (true);

  return newWatermark;
}

Persist newWatermark after the loop completes. On the next run, start from where you left off.

How often should I poll?

Use case	Interval
Customer-facing status display	1–5 minutes
Internal compliance dashboard	5–15 minutes
CRM sync	15–60 minutes
Daily reporting	Once per day

A 5-minute poll on a typical org generates ~12 calls/hour — well below the 60/min burst limit.

Edge cases

Resume from crash. Persist the watermark after the records are written to your store, not before. Re-runs are safe because every customer write is idempotent against your own primary key.
Clock skew. Always use the server’s updated_at value, never Date.now(), as the watermark. Otherwise drift between your clock and ours causes drops or duplicates.
Large catch-up after a long outage. The loop handles it — there’s no hard limit on backfill except rate limits. Pace your daily quota.

Prefer webhooks

Webhooks push the same events to your endpoint with HMAC signatures and automatic retries — the data.customer payload mirrors the DTO this loop reads, so switching is drop-in. Use polling as a periodic backstop if you want belt-and-braces, or as the primary path only when you can’t host an endpoint.

​The pattern in one paragraph

​Implementation

​How often should I poll?

​Edge cases

​Prefer webhooks

The pattern in one paragraph

Implementation

How often should I poll?

Edge cases

Prefer webhooks