---
title: "Registrar opt-out"
method: POST
path: "/v1/opt-outs"
tags: ["Opt-out"]
---

# Registrar opt-out

`POST /v1/opt-outs`

## Request

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

Registra que o telefone não quer mais receber mensagens da organização.
Registrar o mesmo telefone de novo devolve o registro existente.

Atenção: o envio hoje só é bloqueado por opt-out feito por palavra-chave
recebida no WhatsApp (ex. "SAIR", "PARAR", "STOP"). O opt-out registrado por
esta rota ou pela remoção LGPD ainda **não** é consultado no envio de
mensagens e campanhas. Filtre a lista do seu lado antes de enviar.

Permissão: `ADMIN`.

## Request body

- object
  - `phone` string, required: Telefone E.164 com `+`.
  - `reason` string: Motivo. Cortado em 80 caracteres.

## Response `201`

Opt-out registrado

- OptOutItem
  - `phone` string, required
  - `channel` string, required
  - `reason` string, nullable
  - `createdAt` string, nullable

## Other responses

- `400`: `INVALID_PHONE`: telefone fora do E.164.
- `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`.
- `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 `Opt-out` added
  - api tag `opt-outs` 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/opt-outs/post.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)