Skip to main content
Creates a new RFI request for document collection and returns a unique link for the primary contact to complete their submission. 
POST /api/external/rfi-requests

​
Authentication

Requires an API key with rfi:create scope. 
Authorization: Bearer klara_{client_id}.{secret}

​
Request body

​
company_name
string
required
Name of the company being onboarded.
​
country
string
required
ISO 3166-1 alpha-2 country code (e.g., GB for United Kingdom, IE for Ireland).
​
company_number
string
required
Company registration number. Required for UK (GB) jurisdictions. For UK companies, this is the Companies House registration number.
​
primary_contact
object
required
The main contact who will complete the RFI submission.
​
agent_id
string
UUID of a specific RFI agent to use. If omitted, the organization’s default active agent is used.
​
pre_authenticated
boolean
default:"false"
When true, generates a pre-authentication code that allows the participant to skip email verification. The code expires after 10 minutes.

​
Response

​
success
boolean
Indicates whether the request was created successfully.
​
request_id
string
Unique identifier (UUID) for this RFI request.
​
link
string
URL where the participant should be redirected to complete their submission. If pre_authenticated was true, this URL includes the auth code as a query parameter.
​
expires_at
string
ISO 8601 timestamp when the RFI request expires (default: 14 days). After this date, the submission link will no longer be valid.
​
status
string
Current status of the RFI request. Newly created requests have status active.
​
participants
array
List of participants associated with this request.
​
pre_auth_code
string
Pre-authentication code (only present when pre_authenticated: true). This is a 16-character alphanumeric code.
​
pre_auth_expires_at
string
ISO 8601 timestamp when the pre-auth code expires (only present when pre_authenticated: true). Codes expire 10 minutes after creation.

​
Examples

​
Basic request (UK company)

curl -X POST https://app.klara-ai.com/api/external/rfi-requests \
  -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": "[email protected]",
      "role": "CEO"
    }
  }'
Response: 
{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://app.klara-ai.com/external/acme-corp/rfi/ABC123",
  "expires_at": "2026-02-12T00:00:00Z",
  "status": "active",
  "participants": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "email": "[email protected]",
      "name": "Sophie Mitchell",
      "role": "primary"
    }
  ]
}

​
Non-UK company (no company_number required)

curl -X POST https://app.klara-ai.com/api/external/rfi-requests \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Dublin Ventures Ltd",
    "country": "IE",
    "primary_contact": {
      "name": "John Murphy",
      "email": "[email protected]"
    }
  }'

​
Pre-authenticated request

Include pre_authenticated: true to generate a link that bypasses email verification: 
curl -X POST https://app.klara-ai.com/api/external/rfi-requests \
  -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": "[email protected]",
      "role": "CEO"
    },
    "pre_authenticated": true
  }'
Response: 
{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://app.klara-ai.com/external/acme-corp/rfi/ABC123?auth_code=X7K9M2P4Q8R1S5T3",
  "expires_at": "2026-02-12T00:00:00Z",
  "status": "active",
  "participants": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "email": "[email protected]",
      "name": "Sophie Mitchell",
      "role": "primary"
    }
  ],
  "pre_auth_code": "X7K9M2P4Q8R1S5T3",
  "pre_auth_expires_at": "2026-01-29T12:10:00Z"
}
When using pre-authentication, redirect the user to the link within the 10-minute 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.

​
UK Company Validation

For UK companies (country: "GB"), the API validates the company against the Companies House registry:
  • The company_number must be a valid Companies House registration number
  • The company must exist and be active in the registry
  • Company details are automatically enriched from Companies House data
If validation fails, the API returns a 400 Bad Request with details about the validation error.

​
Errors

{
  "error": "Missing required fields",
  "required": ["company_name", "country", "primary_contact.name", "primary_contact.email"],
  "example": {
    "company_name": "Acme Financial Ltd",
    "company_number": "12345678",
    "country": "GB",
    "primary_contact": {
      "name": "Sophie Mitchell",
      "email": "[email protected]",
      "role": "CEO"
    }
  }
}
ErrorCause
Missing required fieldsOne or more required request parameters are missing
company_number is required for UK jurisdictionsUK companies must include Companies House registration number
Missing required field: countryThe country field was not provided
Invalid API keyAPI key is invalid, expired, or inactive
API key missing required scopesAPI key doesn’t have the rfi:create scope
Companies House validation errorUK company not found or inactive in registry