> ## 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.

# Update Application

> Update form field values on an application from your own system

Updates field values on an application — for example to pre-fill data you already hold before the applicant opens the form, or to sync a correction made in your system. Only `fields` can be updated through this endpoint; people, ownership, and documents are managed by the applicant in the Klara form.

```text theme={null}
PATCH /api/external/applications/{id}
```

## Authentication

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

```bash theme={null}
Authorization: Bearer klara_{client_id}.{secret}
```

## Path parameters

<ParamField path="id" type="string" required>
  UUID of the application.
</ParamField>

## Request body

<ParamField body="fields" type="object" required>
  Key-value map of field values to set, keyed by field ID (e.g., `company_name`). Must contain at least one key.

  Every key must be a **patchable** field of the application's configuration. Unknown field IDs, document-type fields, person-scoped fields (per-person fields like `full_name` or `date_of_birth`, which belong to person records), and confirmation attestations are rejected with a `400` listing the offending keys. Fields you don't include are left untouched.

  Use the [Field Catalog](/api-reference/field-catalog) to discover the patchable field IDs, their types, and allowed option values for your configuration.
</ParamField>

### Value validation

Values are validated when you write them:

* `select` values must be one of the field's configured option values; `multi_select` values must be an array of them
* `boolean` fields take a boolean, `text`/`date`/`phone` fields take a string, `address` fields take a structured address object
* format rules configured on the field (patterns, phone format, address completeness) are applied

A failing value returns `400` with a per-field message. Sending `null` (or an empty string) clears a field. Required/presence checks still run at submission, not here — you can pre-fill a subset of fields freely.

### Behavior

* **Writable states only** — updates are accepted while the application is in `created`, `sent`, or `in_progress`. Once submitted, the data is frozen and this endpoint returns `400`.
* **Status is never changed** — pre-filling an application you've just created does not move it to `in_progress`; that happens when the applicant starts working on it.
* **No webhooks are emitted** — your own updates are not echoed back to your webhook endpoints, even when they complete a stage.
* **Audited** — every update is recorded in the application's activity log, attributed to your API key.

## Response

Returns `200 OK` when the update is applied.

<ResponseField name="success" type="boolean">
  `true` when the update was applied.
</ResponseField>

<ResponseField name="application_id" type="string">
  UUID of the application.
</ResponseField>

<ResponseField name="updated_fields" type="string[]">
  The field IDs that were set.
</ResponseField>

## Examples

### Pre-filling company details

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://app.klara-ai.com/api/external/applications/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer klara_abc123def456.your-secret-here" \
    -H "Content-Type: application/json" \
    -d '{
      "fields": {
        "company_name": "Acme Financial Ltd",
        "company_number": "12345678",
        "company_country": "GB"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const applicationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://app.klara-ai.com/api/external/applications/${applicationId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer klara_abc123def456.your-secret-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fields: {
          company_name: 'Acme Financial Ltd',
          company_number: '12345678',
          company_country: 'GB'
        }
      })
    }
  );

  const data = await response.json();
  ```

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

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

  response = requests.patch(
      f'https://app.klara-ai.com/api/external/applications/{application_id}',
      headers={
          'Authorization': 'Bearer klara_abc123def456.your-secret-here',
          'Content-Type': 'application/json'
      },
      json={
          'fields': {
              'company_name': 'Acme Financial Ltd',
              'company_number': '12345678',
              'company_country': 'GB'
          }
      }
  )

  data = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "updated_fields": ["company_name", "company_number", "company_country"]
}
```

## Errors

<ResponseExample>
  ```json 400 Bad Request - Unsupported key theme={null}
  {
    "error": "Invalid request body. Only \"fields\" can be updated via this endpoint.",
    "details": {
      "_errors": ["Unrecognized key(s) in object: 'people'"]
    }
  }
  ```

  ```json 400 Bad Request - Unknown field ID theme={null}
  {
    "error": "Unknown or non-writable field ids: not_a_field"
  }
  ```

  ```json 400 Bad Request - Invalid value theme={null}
  {
    "error": "Invalid field values — industry: Please select a valid option"
  }
  ```

  ```json 400 Bad Request - Not writable theme={null}
  {
    "error": "Cannot update application in submitted status"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Application not found"
  }
  ```
</ResponseExample>

| Error                                                                   | Cause                                                                                                                                        |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Invalid JSON body`                                                     | Request body is not valid JSON                                                                                                               |
| `Invalid request body. Only "fields" can be updated via this endpoint.` | Body contains top-level keys other than `fields` (e.g., `people`, `ownership`), or `fields` is missing or empty                              |
| `Unknown or non-writable field ids: ...`                                | One or more keys in `fields` are not defined in the application's configuration, or are document-type, person-scoped, or confirmation fields |
| `Invalid field values — ...`                                            | One or more values failed validation (off-list option, wrong shape, or a format rule) — the message lists each failing field                 |
| `Cannot update application in {status} status`                          | The application has been submitted — data is frozen                                                                                          |
| `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                                                                        |