> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantcompliance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From signing in to ingesting your first customer in under five minutes.

This guide walks you through issuing an API key, ingesting a customer,
and reading the result back.

## 1. Issue an API key

<Steps>
  <Step title="Open the Developers settings">
    Sign in to Instant Compliance and navigate to
    **Settings → Developers**. You will need the `org.api-keys` permission
    (Administrators have this by default; ask your Compliance Officer
    otherwise).
  </Step>

  <Step title="Create a key">
    Click **Create key**, give it a recognisable label (e.g.
    `Zapier — HubSpot production`), pick the scopes the integration needs,
    and click **Create key**.

    | Scope             | Grants                                |
    | ----------------- | ------------------------------------- |
    | `customers:write` | Create and update customer records.   |
    | `customers:read`  | Read customer details and KYC status. |
    | `aml:read`        | Read AML status and category flags.   |

    For an "ingest customers + read status back" integration: tick all
    three.
  </Step>

  <Step title="Copy the plaintext key">
    The key is shown **once** in the format `ic_live_…`. Copy it
    immediately into your integration's secret manager. We will never be
    able to show it again — if you lose it, revoke the key and issue a
    new one.
  </Step>
</Steps>

## 2. Send your first request

Verify the key works by listing customers (returns an empty list if you
have not ingested anyone yet):

<CodeGroup>
  ```bash curl theme={null}
  curl https://app.instantcompliance.ai/api/v1/customers \
    -H "Authorization: Bearer ic_live_..."
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://app.instantcompliance.ai/api/v1/customers', {
    headers: { Authorization: `Bearer ${process.env.IC_API_KEY}` }
  });
  console.log(await res.json());
  ```

  ```python Python theme={null}
  import os, requests

  r = requests.get(
    'https://app.instantcompliance.ai/api/v1/customers',
    headers={'Authorization': f"Bearer {os.environ['IC_API_KEY']}"}
  )
  print(r.json())
  ```
</CodeGroup>

You should receive `{ "object": "list", "data": [], "has_more": false, "next_cursor": null, "limit": 50 }`.

## 3. Ingest a customer

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://app.instantcompliance.ai/api/v1/customers \
    -H "Authorization: Bearer ic_live_..." \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "externalId": "crm-7741",
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://app.instantcompliance.ai/api/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.IC_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      externalId: 'crm-7741',
      fullName: 'Jane Doe',
      email: 'jane@example.com'
    })
  });
  ```

  ```python Python theme={null}
  import os, uuid, requests

  requests.post(
    'https://app.instantcompliance.ai/api/v1/customers',
    headers={
      'Authorization': f"Bearer {os.environ['IC_API_KEY']}",
      'Idempotency-Key': str(uuid.uuid4())
    },
    json={
      'externalId': 'crm-7741',
      'fullName': 'Jane Doe',
      'email': 'jane@example.com'
    }
  )
  ```
</CodeGroup>

Response (`201 Created`):

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "crm-7741",
  "type": "INDIVIDUAL",
  "full_name": "Jane Doe",
  "email": "jane@example.com",
  "kyc_status": "NOT_STARTED",
  "added_via": "INTEGRATION",
  "...": "..."
}
```

<Note>
  **No KYC is triggered and no credits are charged.** The customer record
  is created so your back-office team can review it, complete the risk
  questions, and start verification from inside Instant Compliance.
</Note>

## 4. Read status back

Once your compliance team has verified the customer, poll for the
result. Use `updated_since` so each poll only returns records that
changed since the previous run:

```bash theme={null}
curl "https://app.instantcompliance.ai/api/v1/customers?updated_since=2026-06-23T00:00:00Z" \
  -H "Authorization: Bearer ic_live_..."
```

When `kyc_status` becomes `VERIFIED` and `aml.status` becomes `CLEAR`,
the customer is fully cleared. See
[Customer lifecycle](/concepts/customer-lifecycle) for the full state
machine.

## Next steps

<CardGroup cols={2}>
  <Card title="Upsert by external_id" icon="arrows-rotate" href="/guides/upsert-by-external-id">
    The right way to wire create-or-update from your CRM.
  </Card>

  <Card title="Polling for status" icon="clock-rotate-left" href="/guides/polling-status">
    Get a robust polling loop right the first time.
  </Card>

  <Card title="Zapier integration" icon="bolt" href="/guides/zapier-integration">
    No-code recipe for HubSpot, Pipedrive, Salesforce, etc.
  </Card>

  <Card title="Idempotency" icon="shield-check" href="/concepts/idempotency">
    Make every retry safe.
  </Card>
</CardGroup>