Skip to main content
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

​
id
string
required
UUID of the application. Must match the applicationId in the request body.

​
Request body

​
type
string
required
Decision type. One of:
  • application.approved
  • application.rejected
  • application.referred
​
timestamp
string
required
ISO 8601 timestamp of when the provider made the decision (not when you are relaying it to Klara).
​
application_id
string
required
UUID of the application. Must match the {id} in the URL path.
​
data
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.
​
success
boolean
true when the decision was accepted.
​
decision_type
string
Normalized decision type (approved, rejected, or referred) — the application. prefix is stripped. Only present on 201.
​
application_id
string
UUID of the application. Only present on 201.
​
already_recorded
boolean
true when the same decision type was already recorded. Only present on 200.
​
message
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"
    }
  }'
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'"]
  }
}
ErrorCause
Invalid JSON bodyRequest body is not valid JSON
Invalid request bodyBody failed schema validation — see details for per-field errors
application_id in body does not match URL parameterThe application_id field does not match the {id} in the URL
Application has not been submitted yetThe application is still in a writable state (created, sent, in_progress)
Invalid API keyAPI key is invalid, expired, or inactive
API key missing required scopesAPI key does not have the applications:write scope
Application not foundThe application does not exist or belongs to a different organization