Record Decision

Records a decision on a submitted application. Use this endpoint when a downstream provider (e.g. a bank, payment provider, or credit bureau) returns an outcome for an application and you want Klara to have a canonical record of that decision.

POST /api/external/applications/{id}/decision

Authentication

Requires an API key with applications:write scope. The application must belong to the organization associated with the API key.

Authorization: Bearer klara_{client_id}.{secret}

Path parameters

string

required

UUID of the application. Must match the applicationId in the request body.

Request body

string

required

Decision type. One of:

application.approved
application.rejected
application.referred

string

required

ISO 8601 timestamp of when the provider made the decision (not when you are relaying it to Klara).

string

required

UUID of the application. Must match the {id} in the URL path.

object

Free-form object containing any provider-specific context you want stored alongside the decision — for example a provider reference number, reason codes, or reviewer notes. Stored verbatim.

Provider decisions can only be recorded against applications that have been submitted. Calling this endpoint for an application still in created, sent, or in_progress state returns 400.

Idempotency

Recording the same decision type twice for an application is a safe no-op. The second call returns 200 OK with already_recorded: true and does not create a duplicate record. Different decision types are all recorded in order — e.g. a referred decision followed later by an approved decision will both be stored.

Response

Returns 201 Created when a new decision is recorded, or 200 OK if the decision was already recorded.

boolean

true when the decision was accepted.

string

Normalized decision type (approved, rejected, or referred) — the application. prefix is stripped. Only present on 201.

string

UUID of the application. Only present on 201.

boolean

true when the same decision type was already recorded. Only present on 200.

string

Human-readable explanation. Only present on 200.

Examples

Approving an application

curl -X POST https://app.klara-ai.com/api/external/applications/550e8400-e29b-41d4-a716-446655440000/decision \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "application.approved",
    "timestamp": "2026-04-20T14:32:00Z",
    "application_id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "providerRef": "MOD-1234",
      "notes": "Clear"
    }
  }'

const applicationId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://app.klara-ai.com/api/external/applications/${applicationId}/decision`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer klara_abc123def456.your-secret-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'application.approved',
      timestamp: new Date().toISOString(),
      application_id: applicationId,
      data: {
        providerRef: 'MOD-1234',
        notes: 'Clear'
      }
    })
  }
);

const data = await response.json();

import requests
from datetime import datetime, timezone

application_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.post(
    f'https://app.klara-ai.com/api/external/applications/{application_id}/decision',
    headers={
        'Authorization': 'Bearer klara_abc123def456.your-secret-here',
        'Content-Type': 'application/json'
    },
    json={
        'type': 'application.approved',
        'timestamp': datetime.now(timezone.utc).isoformat(),
        'application_id': application_id,
        'data': {
            'providerRef': 'MOD-1234',
            'notes': 'Clear'
        }
    }
)

data = response.json()

Response (new decision):

{
  "success": true,
  "decision_type": "approved",
  "application_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response (already recorded):

{
  "success": true,
  "message": "Provider decision 'approved' was already recorded for this application",
  "already_recorded": true
}

Referring for manual review

curl -X POST https://app.klara-ai.com/api/external/applications/550e8400-e29b-41d4-a716-446655440000/decision \
  -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "application.referred",
    "timestamp": "2026-04-20T14:32:00Z",
    "application_id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "reasonCodes": ["PEP_MATCH", "HIGH_RISK_JURISDICTION"],
      "reviewerQueue": "enhanced-dd"
    }
  }'

Errors

{
  "error": "Invalid request body",
  "details": {
    "type": ["Invalid enum value. Expected 'application.approved' | 'application.rejected' | 'application.referred'"]
  }
}

{
  "error": "application_id in body does not match URL parameter"
}

{
  "error": "Application has not been submitted yet"
}

{
  "error": "Invalid API key"
}

{
  "error": "Application not found"
}

Error	Cause
`Invalid JSON body`	Request body is not valid JSON
`Invalid request body`	Body failed schema validation — see `details` for per-field errors
`application_id in body does not match URL parameter`	The `application_id` field does not match the `{id}` in the URL
`Application has not been submitted yet`	The application is still in a writable state (`created`, `sent`, `in_progress`)
`Invalid API key`	API key is invalid, expired, or inactive
`API key missing required scopes`	API key does not have the `applications:write` scope
`Application not found`	The application does not exist or belongs to a different organization

Overview

Applications

Reference

Authentication

Path parameters

Request body

Idempotency

Response

Examples

Approving an application

Referring for manual review

Errors

​Authentication

​Path parameters

​Request body

​Idempotency

​Response

​Examples

​Approving an application

​Referring for manual review

​Errors

Authentication

Path parameters

Request body

Idempotency

Response

Examples

Approving an application

Referring for manual review

Errors