Create Application

Creates a new application and returns a unique link for the primary contact to complete their submission. You don’t need to specify a configuration — if config_id is omitted, your organization’s default configuration is used.

POST /api/external/applications

Authentication

Requires an API key with applications:create scope.

Authorization: Bearer klara_{client_id}.{secret}

Request body

object

required

The main contact who will complete the application.

Show primary_contact properties

string

required

Email address of the primary contact.

string

Full name of the primary contact.

string

required

ISO 3166-1 alpha-2 country code (e.g., GB for United Kingdom, IE for Ireland). Used to select the company registry for validation, so it must be a jurisdiction supported by your configuration.

string

Application config ID. Must belong to the organization associated with the API key. If omitted, your organization’s default configuration is used. Only pass this if your organization has multiple configurations and you need a specific one.

boolean

default:"false"

When true, generates a pre-authentication code that allows the participant to bypass email verification. The code expires after 72 hours.

string

Company registration number. Required, unless your configuration has company selection enabled — in that case you can omit it and the applicant picks their company from a registry search when they first open the application.

string

Name of the company being onboarded. Required when company_number is provided — it is checked against the registered name in the company registry (see note below).

Registry validation: when company_number is provided, it is validated against the company registry before the application is created (Companies House for GB, CRO for IE). The company must exist, be active, and the provided company_name must match the registered name — mismatches return a 400 with a suggestion of the registered name.

Response

Returns 201 Created on success.

string

Unique identifier (UUID) for the created application.

string

URL where the participant should be redirected to complete their application. If your organization has an active custom domain, the link uses it (e.g., https://onboarding.yourcompany.com/apply/...); otherwise it points at the default Klara host.

array

List of participants associated with this application.

Show participant properties

string

UUID of the participant.

string

Identifier used in the application URL.

string

Email address of the participant.

string

Participant role (primary).

string

Pre-authentication code (only present when pre_auth: true). Expires 72 hours after creation.

string

Warning message (only present if the invite email failed to send). The application is still created successfully — the email can be resent.

Examples

Basic request

curl -X POST https://app.klara-ai.com/api/external/applications \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "kyc-standard",
    "primary_contact": {
      "email": "sophie@acme.com",
      "name": "Sophie Mitchell"
    },
    "company_name": "Acme Financial Ltd",
    "company_number": "12345678",
    "country": "GB"
  }'

const response = await fetch('https://app.klara-ai.com/api/external/applications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer klara_abc123def456.your-secret-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    config_id: 'kyc-standard',
    primary_contact: {
      email: 'sophie@acme.com',
      name: 'Sophie Mitchell'
    },
    company_name: 'Acme Financial Ltd',
    company_number: '12345678',
    country: 'GB'
  })
});

const data = await response.json();

import requests

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

data = response.json()

Response:

{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://app.klara-ai.com/external/acme-corp/application/ABC123",
  "participants": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "link_slug": "7f3k9m2p4q8r1s5t",
      "email": "sophie@acme.com",
      "role": "primary"
    }
  ]
}

With pre-authentication

Include pre_auth: true to generate a code that bypasses email verification:

curl -X POST https://app.klara-ai.com/api/external/applications \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "kyc-standard",
    "primary_contact": {
      "email": "sophie@acme.com",
      "name": "Sophie Mitchell"
    },
    "company_name": "Acme Financial Ltd",
    "pre_auth": true
  }'

const response = await fetch('https://app.klara-ai.com/api/external/applications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer klara_abc123def456.your-secret-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    config_id: 'kyc-standard',
    primary_contact: {
      email: 'sophie@acme.com',
      name: 'Sophie Mitchell'
    },
    company_name: 'Acme Financial Ltd',
    pre_auth: true
  })
});

const data = await response.json();
// Redirect user to data.link within 72 hours

import requests

response = requests.post(
    'https://app.klara-ai.com/api/external/applications',
    headers={
        'Authorization': 'Bearer klara_abc123def456.your-secret-here',
        'Content-Type': 'application/json'
    },
    json={
        'config_id': 'kyc-standard',
        'primary_contact': {
            'email': 'sophie@acme.com',
            'name': 'Sophie Mitchell'
        },
        'company_name': 'Acme Financial Ltd',
        'pre_auth': True
    }
)

data = response.json()
# Redirect user to data['link'] within 72 hours

Response:

{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://app.klara-ai.com/external/acme-corp/application/ABC123",
  "participants": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "link_slug": "7f3k9m2p4q8r1s5t",
      "email": "sophie@acme.com",
      "role": "primary"
    }
  ],
  "pre_auth_code": "X7K9M2P4Q8R1S5T3"
}

When using pre-authentication, redirect the user to the link within the 72-hour window. If the code expires, the user will be prompted to verify their email instead — no error occurs, they just go through the standard verification flow.

To bypass the authentication with the pre_auth_code, go to an incognito tab so it does redirect you to the dashboard and then add a query param to the link as shown here:{link}?auth_code={pre_auth_code}

Need to re-issue a pre-auth code after it expires or gets consumed? Use the Refresh Pre-Auth endpoint instead of creating a new application.

With company selection

If your configuration has company selection enabled, you don’t need to know the applicant’s company number — omit company_number (and optionally company_name) and the applicant picks their company from a registry search when they first open the application. country is still required and must be a country your configuration supports.

curl -X POST https://app.klara-ai.com/api/external/applications \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_contact": {
      "email": "sophie@acme.com",
      "name": "Sophie Mitchell"
    },
    "country": "GB"
  }'

const response = await fetch('https://app.klara-ai.com/api/external/applications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer klara_abc123def456.your-secret-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    primary_contact: {
      email: 'sophie@acme.com',
      name: 'Sophie Mitchell'
    },
    country: 'GB'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://app.klara-ai.com/api/external/applications',
    headers={
        'Authorization': 'Bearer klara_abc123def456.your-secret-here',
        'Content-Type': 'application/json'
    },
    json={
        'primary_contact': {
            'email': 'sophie@acme.com',
            'name': 'Sophie Mitchell'
        },
        'country': 'GB'
    }
)

data = response.json()

Company selection is a configuration-level setting. If it’s not enabled for your configuration, omitting company_number returns 400 company_number is required. Contact us to enable it.

Errors

{
  "error": "primary_contact.email is required"
}

{
  "error": "company_number is required"
}

{
  "error": "The company name and company number you have provided do not match the details in the registry. Did you mean 'ACME FINANCIAL LTD'?"
}

{
  "error": "Invalid API key"
}

{
  "error": "Config not available for this organization"
}

{
  "error": "The company registry (Companies House) is temporarily unavailable. Please try again in a few minutes.",
  "retryable": true
}

Status	Error	Cause
`400`	`primary_contact.email is required`	The primary contact email is missing
`400`	`Invalid email address for primary_contact.email`	The provided email address is not valid
`400`	`Invalid config_id`	The config ID does not exist
`400`	`No active configuration found for this organization`	`config_id` was omitted and the organization has no configuration to default to
`400`	`company_number is required`	`company_number` was omitted and the configuration does not have company selection enabled
`400`	`country is required for this application configuration`	Company selection is enabled but no `country` was provided
`400`	`Country '{country}' is not supported by this application configuration`	The country is not in the configuration’s allowed list
`400`	`Company search is not available for country '{country}'`	Company selection is enabled but no registry supports name search for this country
`400`	Registry rejection message	The company was not found, is not active, or the `company_name` doesn’t match the registered name
`401`	`Invalid API key`	API key is invalid, expired, or inactive
`401`	`API key missing required scopes: applications:create`	API key doesn’t have the `applications:create` scope
`403`	`Config not available for this organization`	The config belongs to a different organization
`502`	`Registry validation failed`	The registry lookup failed unexpectedly — safe to retry
`503`	Registry temporarily unavailable	The company registry is down. The response includes `"retryable": true` — retry after a few minutes

Overview

Applications

Reference

Create Application

Authentication

Request body

Response

Examples

Basic request

With pre-authentication

With company selection

Errors

​Authentication

​Request body

​Response

​Examples

​Basic request

​With pre-authentication

​With company selection

​Errors

Authentication

Request body

Response

Examples

Basic request

With pre-authentication

With company selection

Errors