Public API Contact Update Endpoint

This endpoint lets an external system update a contact that already exists in a brayv.ai account. It accepts the same contact fields as the Lead Submission API, but it never creates a contact and never runs lead intake: no journey routing, no opportunity, no notifications. Use it to keep a contact current after the lead has arrived.

Endpoint

PATCH https://api.brayv.ai/v1/accounts/{account_id}/contacts
Authorization: Bearer {api_key}
Content-Type: application/json

Replace {account_id} with the brayv.ai account ID that owns the contact.

Authentication

Send the API key in the Authorization header:

Authorization: Bearer brayv_live_...

The same keys used for lead submission work here. A key is scoped to either one account or an organization that has access to the target account. Rate limits are shared with the lead endpoint, per key and per account.

Identifying the Contact

Every request must identify one contact with contact_id, phone, or both. contact_id is the brayv.ai contact ID returned by the lead endpoint. phone must use one of the accepted phone formats below.

phone is used only to find the contact. This endpoint cannot change a contact's phone number. Use brayv.ai to edit a phone number.

Accepted Phone Formats

Formatted numbers such as (555) 123-4567 are rejected with 422, even when contact_id is also present.

Response

{
  "status": "success",
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "matched_by": "contact_id",
  "updated_fields": ["hook", "city", "custom_fields"],
  "ignored_fields": [],
  "note_created": true,
  "idempotent_replay": false,
  "account_status": "active",
  "notice": null
}

Updatable Fields

All fields are optional. Send only what should change. These are the same fields the Lead Submission API accepts, with two exceptions: phone identifies the contact and is never written, and source cannot be changed.

Unknown fields are ignored and reported in ignored_fields.

Fields That Cannot Be Changed

How Updates Are Applied

Every update is recorded on the contact's activity history as Contact updated by Public contact API, listing the fields that changed and anything that was refused.

An Update That Changes Nothing

If a request carries no updatable field, no valid custom field, and no note, it is refused with 422 rather than answering 200 for a no-op. The ignored_fields list in the error says why each field was dropped.

{
  "detail": {
    "message": "Invalid contact update",
    "validation_errors": [
      { "field": "payload", "reason": "No updatable fields were provided" }
    ],
    "ignored_fields": [
      { "field": "Hook", "reason": "Unknown field" }
    ]
  }
}

Consent Behavior

The three consent flags are optional on this endpoint. Only the flags you send change anything; the others keep their current values.

Non-boolean values for any consent flag are ignored and logged.

Custom Fields

Send custom field values inside the custom_fields object, keyed by the custom field ID. Use the Custom Fields API to look up the IDs, types, and options for an account.

{
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "custom_fields": {
    "service_type": "Plumbing",
    "preferred_service_date": "2026-10-02"
  }
}

Validation is the same as the lead endpoint: values that do not match the field's type or options are ignored and logged, and the request still succeeds. Keys you do not send are left as they were.

Note

note adds a new note to the contact. It never edits an existing note.

{
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "note": {
    "content": "Customer rescheduled to Thursday afternoon.",
    "surface_to_agents": true
  }
}

A plain string is also accepted and leaves surface_to_agents at false. Content is trimmed to 1000 characters. If the contact already has a note with identical text, no duplicate is created and the note is reported in ignored_fields. Notes created this way are labelled Integration in brayv.ai. The visibility rules for surface_to_agents are the same as the Lead Submission API.

A request may consist of a note alone.

Idempotency

idempotency_key is optional. Repeated requests with the same API key, target account, and idempotency key within about 5 minutes return the original result with idempotent_replay: true instead of applying the update again.

Account Paused for a Payment Issue

If the target account is paused for a payment issue, the update still applies. The response reports account_status: "frozen" and a notice explaining that no outbound outreach will occur until billing is fixed.

Account Inactive

If the account's brayv.ai subscription has been cancelled, the request returns 403 Forbidden and nothing is changed. Have an account admin reactivate the subscription, then retry.

{
  "detail": {
    "code": "account_inactive",
    "message": "Account is inactive. Please have an account admin reactivate the Brayv subscription."
  }
}

Errors

Identifier mismatch example:

{
  "detail": {
    "code": "identifier_mismatch",
    "message": "The phone number does not belong to the contact identified by contact_id",
    "contact_id": "34726940-88ec-49e3-9529-6e0845703eda"
  }
}

Multiple matches example:

{
  "detail": {
    "code": "multiple_contacts",
    "message": "More than one contact has this phone number; send contact_id instead",
    "contact_ids": [
      "34726940-88ec-49e3-9529-6e0845703eda",
      "a1e2f0d5-6c8b-4d2a-9f3e-0b7c1d2e3f40"
    ]
  }
}

Full Example Payload

{
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "phone": "5551234567",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "street_address": "456 Oak Ave",
  "city": "Charlotte",
  "state": "NC",
  "zip_code": "28203",
  "tags": ["repeat-customer"],
  "hook": "Water heater replacement",
  "friendly_source": "Angi",
  "text_opt_in": true,
  "call_opt_in": true,
  "voice_ai_opt_in": true,
  "custom_fields": {
    "service_type": "Plumbing",
    "lead_priority": "High"
  },
  "note": {
    "content": "Customer confirmed the water heater is a 50-gallon gas unit.",
    "surface_to_agents": true
  },
  "idempotency_key": "angi-update-98765"
}

Example cURL

curl -X PATCH "https://api.brayv.ai/v1/accounts/ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer brayv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5551234567",
    "hook": "Water heater replacement",
    "tags": ["repeat-customer"],
    "custom_fields": {
      "service_type": "Plumbing"
    },
    "note": "Customer confirmed the water heater is a 50-gallon gas unit."
  }'