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

# Quickstart

> Make your first Klara API request in minutes

This guide walks you through creating your first application using the Klara API.

## Prerequisites

* A Klara organization account with admin access
* Access to your organization's API settings

<Tip>
  **New to Klara?** Use our sandbox environment at [sandbox.klara-ai.com](https://sandbox.klara-ai.com) to test your integration before going live. Sandbox uses separate API keys from production.
</Tip>

## Step 1: Generate an API key

1. Log in to your Klara dashboard
2. Navigate to **Settings → Integrations → API Keys**
3. Click **Create API Key**
4. Enter a name for your key (e.g., "Production API Key")
5. Copy the full API key immediately, it will only be shown once

<Warning>
  Store your API key securely. The secret portion is only displayed once at creation. If you lose it, you'll need to create a new key.
</Warning>

Your API key follows this format:

```text theme={null}
klara_{client_id}.{secret}
```

## Step 2: Create an Application

Make a POST request to create a new application. The API requires a primary contact and company information. An application is created using your organization's default configuration.

<CodeGroup>
  ```bash cURL theme={null}
  # Use sandbox.klara-ai.com for testing, app.klara-ai.com for production
  curl -X POST https://sandbox.klara-ai.com/api/external/applications \
    -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "Acme Financial Ltd",
      "company_number": "12345678",
      "country": "GB",
      "primary_contact": {
        "name": "Sophie Mitchell",
        "email": "sophie@acme.com"
      },
      "pre_auth": true
    }'
  ```

  ```javascript Node.js theme={null}
  // Use sandbox.klara-ai.com for testing, app.klara-ai.com for production
  const response = await fetch('https://sandbox.klara-ai.com/api/external/applications', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer klara_abc123def456.your-secret-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company_name: 'Acme Financial Ltd',
      company_number: '12345678',
      country: 'GB',
      primary_contact: {
        name: 'Sophie Mitchell',
        email: 'sophie@acme.com'
      },
      pre_auth: true
    })
  });

  const data = await response.json();
  console.log(data.link); // Redirect user here
  ```

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

  # Use sandbox.klara-ai.com for testing, app.klara-ai.com for production
  response = requests.post(
      'https://sandbox.klara-ai.com/api/external/applications',
      headers={
          'Authorization': 'Bearer klara_abc123def456.your-secret-here',
          'Content-Type': 'application/json'
      },
      json={
          'company_name': 'Acme Financial Ltd',
          'company_number': '12345678',
          'country': 'GB',
          'primary_contact': {
              'name': 'Sophie Mitchell',
              'email': 'sophie@acme.com'
          },
          'pre_auth': True
      }
  )

  data = response.json()
  print(data['link'])  # Redirect user here
  ```
</CodeGroup>

### Request fields

| Field                   | Required | Description                                                                                                                                              |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `company_name`          | Yes      | Name of the company being onboarded, must match the registered name                                                                                      |
| `country`               | Yes      | ISO country code (e.g., `GB`, `IE`)                                                                                                                      |
| `company_number`        | Yes\*    | Registration number. \*Can be omitted if your configuration has company selection enabled. The applicant then picks their company from a registry search |
| `primary_contact.email` | Yes      | Email address of the primary contact                                                                                                                     |
| `primary_contact.name`  | No       | Full name of the primary contact                                                                                                                         |

<Note>
  When a `company_number` is provided, it is validated against the company registry (Companies House for `GB`, CRO for `IE`). The company must be active and the `company_name` must match the registered name.
</Note>

## Step 3: Handle the response

A successful request returns:

```json theme={null}
{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://app.klara-ai.com/external/your-org/apply/ABC123?auth_code=X7K9M2P4Q8R1S5T3",
  "participants": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "link_slug": "7f3k9m2p4q8r1s5t",
      "email": "sophie@acme.com",
      "role": "primary"
    }
  ],
  "pre_auth_code": "X7K9M2P4Q8R1S5T3"
}
```

## Step 4: Redirect the user

Redirect the user to the `link` URL. If you used `pre_auth: true`, they'll land directly on the submission form without needing to verify their email.

<Tip>
  The pre-auth code expires after 72 hours. If the user doesn't access the link in time, they'll be prompted to verify their email instead.
</Tip>

## Step 5: Re-entry with refreshed pre-auth

If a user leaves the form and comes back later via your platform, you don't need to create a new application. Instead, refresh the pre-auth code on the existing one:

1. User starts the application but leaves before completing it
2. User returns to your platform and wants to continue
3. Your backend calls `POST /api/external/applications/{id}/pre-auth` to get a fresh link
4. Redirect the user, they're authenticated instantly with the new code

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.klara-ai.com/api/external/applications/550e8400-e29b-41d4-a716-446655440000/pre-auth \
    -H "Authorization: Bearer klara_abc123def456.your-secret-here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://sandbox.klara-ai.com/api/external/applications/${applicationId}/pre-auth`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer klara_abc123def456.your-secret-here'
      }
    }
  );

  const data = await response.json();
  // Redirect user to data.link
  ```

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

  response = requests.post(
      f'https://sandbox.klara-ai.com/api/external/applications/{application_id}/pre-auth',
      headers={
          'Authorization': 'Bearer klara_abc123def456.your-secret-here'
      }
  )

  data = response.json()
  # Redirect user to data['link']
  ```
</CodeGroup>

<Tip>
  See the full [Refresh Pre-Auth](/api-reference/refresh-pre-auth) API reference for response details and error handling.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn more about API key management and security.
  </Card>

  <Card title="API Reference" icon="code" href="api-reference/create-application">
    See the full API specification with all parameters.
  </Card>
</CardGroup>