> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Application

> Attach or update integration metadata on a form submission

# Update Application

Updates the `metadata` on an existing application. `metadata` is a free-form key/value object for your own integration data — Gomry never interprets these keys. Use it to tag applications with anything your system needs: a cohort, an external funnel stage, a CRM record ID.

**Required scope:** `applications:write`

The application's internal `status` (`Draft`, `Pending`, `Accepted`, `Rejected`) is **not** writable through this endpoint — it drives acceptance/rejection emails and list membership inside Gomry. Track your own funnel stages as keys inside `metadata` instead.

## Path Parameters

<ParamField path="applicationId" type="string" required>
  The unique identifier of the application.
</ParamField>

## Request Body

The body uses **strict validation**: only `metadata` is accepted, and any other field is rejected with a `400` error.

<ParamField body="metadata" type="object" required>
  Key/value pairs to **merge** onto the application's existing metadata. Keys you don't include are left untouched. Set a key's value to `null` to remove that key. Keys are client-defined and never interpreted by Gomry.
</ParamField>

### Merge behaviour

Each `PATCH` merges — it does not replace the whole bag. To keep a changelog, read the current value, append, and write it back:

```json theme={null}
{
  "metadata": {
    "funnel_stage": "Interview",
    "stage_history": [
      { "stage": "Submitted", "at": "2026-05-01" },
      { "stage": "Interview", "at": "2026-05-20" }
    ]
  }
}
```

## Response

Returns the updated application, including its `metadata` and `history` (the internal status change log — see [Get Application](/api-reference/applications/get-application)).

<ResponseField name="data" type="object">
  The updated application object (same schema as [List Applications](/api-reference/applications/list-applications), plus `history`).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"metadata": {"target_cohort": "Fall 2025", "funnel_stage": "Interview"}}' \
    "https://www.gomry.com/api/v1/applications/AbCdEfGhIjKlMnOpQrSt"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://www.gomry.com/api/v1/applications/AbCdEfGhIjKlMnOpQrSt",
    {
      method: "PATCH",
      headers: {
        "X-API-KEY": "your_api_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        metadata: { target_cohort: "Fall 2025", funnel_stage: "Interview" },
      }),
    }
  );
  const { data } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "AbCdEfGhIjKlMnOpQrSt",
      "form_id": "FORM_ID",
      "contact_id": "CONTACT_ID",
      "status": "Accepted",
      "metadata": {
        "target_cohort": "Fall 2025",
        "funnel_stage": "Interview"
      },
      "history": [
        { "status": "Pending", "changed_by": "USER_ID", "changed_at": "2026-05-01T12:00:00.000Z" },
        { "status": "Accepted", "changed_by": "USER_ID", "changed_at": "2026-05-20T09:00:00.000Z" }
      ],
      "updated_at": "2026-06-03T10:30:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Validation failed",
    "details": {
      "formErrors": [],
      "fieldErrors": {}
    }
  }
  ```
</ResponseExample>