---
title: "Atualizar contato"
method: PATCH
path: "/v1/contacts/{phone}"
tags: ["Contatos"]
---

# Atualizar contato

`PATCH /v1/contacts/{phone}`

## Request

- Base URL: `https://api.ararahq.com`
- URL: `https://api.ararahq.com/v1/contacts/{phone}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/contacts/:phone/patch.ts> (a function with typed inputs; its response is checked against the schema)

Atualiza só os campos enviados. Campo omitido não muda. Permissão: `CONTACTS_WRITE`.

## Path parameters

- `phone` string, required

## Request body

- ContactPatchRequest
  - `name` string, nullable: Até 255 caracteres. Vazio é ignorado.
  - `email` string, nullable: Até 255 caracteres. String vazia remove o email.
  - `tags` string[], nullable: Substitui a lista inteira. Até 20 tags.

## Response `200`

Contato atualizado

- ContactResponse
  - `id` string, uuid, required
  - `name` string, required
  - `phone` string, required
  - `email` string, nullable
  - `attributes` object, nullable
  - `tags` string[], required
  - `createdAt` string, required
  - `lifecycle` string, required: Estágio do contato: `NEW`, `ENGAGED`, `SILENT`, `DORMANT` ou `OPTED_OUT`.
  - `source` string, required: De onde o contato veio (ex. `API`).
  - `outboundCount` integer, required
  - `inboundCount` integer, required
  - `firstSeenAt` string, nullable
  - `lastOutboundAt` string, nullable
  - `lastInboundAt` string, nullable
  - `lastMessageAt` string, nullable
  - `optOutAt` string, nullable: Quando o contato pediu para não receber.
  - `lastTemplateName` string, nullable: Último template enviado ao contato.

## Other responses

- `400`: Requisição inválida: `VALIDATION_ERROR` (campo obrigatório ausente ou regra do corpo), `INVALID_JSON` (JSON malformado ou tipo errado), `INVALID_PATH_PARAM` ou `INVALID_IDEMPOTENCY_KEY`.
- `401`: Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`.
- `403`: Dois casos, com corpos diferentes: - Autenticação: header `Authorization` ausente, Bearer que não começa com `ara_`, chave sem a permissão da rota ou rota que não aceita chave de API. Corpo no formato padrão do Spring, sem `error.code`. - Regra de negócio, no formato `{ "error": { ... } }`: `PLAN_FEATURE_LOCKED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_NOT_ACTIVATED`, `NO_DEDICATED_NUMBER`, `ORGANIZATION_SUSPENDED`, `NUMBER_BLOCKED`, `FRAUD_SUSPECTED`, `RESOURCE_FORBIDDEN`, `VIEWER_READ_ONLY`.
- `422`: A requisição é válida, mas uma regra de negócio impede: `RECIPIENT_OPTED_OUT`, `INVALID_RECIPIENT`, `TEMPLATE_PAUSED`, `TEMPLATE_NOT_SENDABLE`, `TEMPLATE_VARIABLES_MISMATCH`, `CONVERSATION_WINDOW_CLOSED`, `SENDER_NOT_ALLOWED`, `UNPROCESSABLE_ENTITY` ou um código de diagnóstico `ararahq-*` com `details.diagnostic`.
- `429`: `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave).

## Changes

- **2026-10-12** `d576cd28afc0`: 3 info
  - api tag `Contatos` added
  - api tag `contacts` removed
  - added the non-success response with the status `429`
- **2026-09-15** `372d8c2e735d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ararahq/apis/ararahq-api/changes/v1/contacts/:phone/patch.md)

---

[API](https://skmtc.dev/ararahq/apis/ararahq-api.md) - [All operations](https://skmtc.dev/ararahq/apis/ararahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ararahq/apis/ararahq-api/revisions/d576cd28afc0?raw)