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

# First API Call

> Make your first API call in 2 minutes

Let's create a customer using your test key. No real data will be stored — everything is simulated in test mode.

## 1. Create a customer

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kemycard.com/v1/customers \
    -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "external_reference": "user-001",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone_country_code": "+33",
      "phone": "612345678",
      "date_of_birth": "1990-05-15",
      "address": "123 Main Street",
      "city": "Paris",
      "state": "IDF",
      "postal_code": "75001",
      "country": "FRA"
    }'
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.kemycard.com/v1/customers');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer sk_test_YOUR_API_KEY',
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'external_reference' => 'user-001',
          'first_name' => 'John',
          'last_name' => 'Doe',
          'email' => 'john@example.com',
          'phone_country_code' => '+33',
          'phone' => '612345678',
          'date_of_birth' => '1990-05-15',
          'address' => '123 Main Street',
          'city' => 'Paris',
          'state' => 'IDF',
          'postal_code' => '75001',
          'country' => 'FRA',
      ]),
      CURLOPT_RETURNTRANSFER => true,
  ]);
  $response = json_decode(curl_exec($ch), true);
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.kemycard.com/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_reference: 'user-001',
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com',
      phone_country_code: '+33',
      phone: '612345678',
      date_of_birth: '1990-05-15',
      address: '123 Main Street',
      city: 'Paris',
      state: 'IDF',
      postal_code: '75001',
      country: 'FRA',
    }),
  });
  const data = await response.json();
  ```

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

  response = requests.post(
      'https://api.kemycard.com/v1/customers',
      headers={
          'Authorization': 'Bearer sk_test_YOUR_API_KEY',
      },
      json={
          'external_reference': 'user-001',
          'first_name': 'John',
          'last_name': 'Doe',
          'email': 'john@example.com',
          'phone_country_code': '+33',
          'phone': '612345678',
          'date_of_birth': '1990-05-15',
          'address': '123 Main Street',
          'city': 'Paris',
          'state': 'IDF',
          'postal_code': '75001',
          'country': 'FRA',
      },
  )
  data = response.json()
  ```
</CodeGroup>

## 2. Response

```json theme={null}
{
  "success": true,
  "data": {
    "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_reference": "user-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_country_code": "+33",
    "phone": "612345678",
    "date_of_birth": "1990-05-15",
    "address": "123 Main Street",
    "city": "Paris",
    "state": "IDF",
    "postal_code": "75001",
    "country": "FRA",
    "verification_level": "basic",
    "kyc_status": "not_started",
    "poa_status": "not_started",
    "verified_identity": null,
    "identity_mismatch": null,
    "status": "active",
    "restriction_reason": null,
    "metadata": null,
    "created_at": "2026-06-28T14:30:00+00:00",
    "updated_at": null
  },
  "meta": {
    "request_id": "a4f8e2c1b3d97056",
    "mode": "test",
    "timestamp": "2026-06-28T14:30:00+00:00"
  }
}
```

<Check>
  Notice `"mode": "test"` in the `meta` object — this confirms you're using test mode. No data was written to the database.
</Check>

## 3. What's next?

Now that you have a customer, here's the typical flow:

<Steps>
  <Step title="Browse the card catalog">
    Check available card products with `GET /cards/products` to find the right product for your use case.
  </Step>

  <Step title="Verify identity (KYC)">
    Submit a KYC verification to upgrade the customer from `basic` to `verified`.
  </Step>

  <Step title="Issue a card">
    Create a virtual Mastercard or Visa card for the verified customer.
  </Step>

  <Step title="Fund the card">
    Top up the card from your ops balance.
  </Step>
</Steps>

<Card title="Full flow guide" icon="route" href="/guides/customer-to-card" horizontal>
  Follow the complete guide: from customer creation to card issuance.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.