---
title: "Submit a contact-record form"
method: POST
path: "/v1/contacts/record/submit"
tags: ["contacts"]
---

# Submit a contact-record form

`POST /v1/contacts/record/submit`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/contacts/record/submit`
- Auth: none declared

Completes a contact_record_request the assistant broadcast: writes the record the guardian confirmed, then unblocks the waiting command. A create or update writes display name and notes, never a channel; a merge moves the donor's channels to the survivor and deletes the donor. A cancelled submission unblocks the command without writing.

## Request body

- object
  - `requestId` string, required: The contact_record_request id broadcast by the assistant
  - `operation` 'create' | 'update' | 'delete' | 'merge': Required unless cancelled is true
  - `contactId` string: Required to update or delete, and the survivor of a merge
  - `donorContactId` string: The contact merged away. Required for a merge.
  - `displayName` string
  - `notes` string, nullable
  - `expectedChannels` object[]: The channels the delete confirmation listed. The delete is refused if the contact's channels changed since.
    - `type` string, required
    - `address` string, required
  - `cancelled` boolean: The guardian dismissed the form. Unblocks the waiting command without writing.

## Response `200`

Successful response

- object
  - `accepted` boolean, required
  - `error` string
  - `duplicate` boolean: Another client answered this form first. Nothing is wrong, but none of this submission's values were written.

## Changes

- **2026-09-03** `48d611686235`: 2 info
  - added the new optional request property `donorContactId`
  - added the new `merge` enum value to the request property `operation`
- **2026-08-31** `1c0b7dd0195a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vellum-ai/apis/vellum-gateway-api/changes/v1/contacts/record/submit/post.md)

---

[API](https://skmtc.dev/vellum-ai/apis/vellum-gateway-api.md) - [All operations](https://skmtc.dev/vellum-ai/apis/vellum-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vellum-ai/apis/vellum-gateway-api/revisions/48d611686235?raw)