---
title: "Contatos e identificadores"
description: "Como gerenciar pela API do Signer os contatos da organização, inclusive em lote por CSV, e os identificadores (CPF, passaporte e outros) de um usuário."
canonical: "https://docs.lacunasoftware.com/articles/signer/integration/contacts"
locale: "pt-BR"
product: "Signer"
last_updated: "2026-10-22"
---

# Contatos e identificadores

Um contato é uma pessoa da agenda da organização: nome, e-mail, identificador, telefone e uma descrição. Na tela de criação de documentos, o Signer sugere os contatos para preencher os participantes. Esta página mostra como gerenciar os contatos e os identificadores de um usuário pela API.

## Contatos

Todas as rotas começam com `/api/organization/contacts`. Sem o parâmetro `organizationId` na query string, a organização é a da chave de API.

| Operação | Rota |
| --- | --- |
| Listar e pesquisar | `GET /api/organization/contacts?q=maria&limit=20&offset=0` |
| Criar | `POST /api/organization/contacts` |
| Consultar | `GET /api/organization/contacts/{contactId}` |
| Alterar | `PUT /api/organization/contacts/{contactId}` |
| Excluir | `DELETE /api/organization/contacts/{contactId}` |
| Criar em lote | `POST /api/organization/contacts/batch/create` |
| Excluir em lote | `POST /api/organization/contacts/batch/delete` |

O parâmetro `q` pesquisa o começo do nome ou do sobrenome, o começo do e-mail, do telefone e do identificador, e as palavras da descrição. A listagem devolve os contatos em `items` e o total em `totalCount`.

O corpo de criação e de alteração tem estes campos:

```json
POST /api/organization/contacts
{
  "name": "Maria Souza",
  "emailAddress": "maria.souza@mailinator.com",
  "identifier": "81976153069",
  "identifierType": "Cpf",
  "phone": "+55 11 91234-5678",
  "description": "Diretora financeira"
}
```

Os campos `name` e `emailAddress` são obrigatórios. O campo `identifierType` é obrigatório quando a instância aceita mais de um tipo de identificador. Os tipos estão em [O participante (`user`)](https://docs.lacunasoftware.com/articles/signer/integration/document-fields#participant-user).

### Criar e excluir em lote

Para criar vários contatos de uma vez, envie a lista em `contacts` com `type` igual a `Contacts`:

```json
POST /api/organization/contacts/batch/create
{
  "type": "Contacts",
  "contacts": [
    { "name": "Maria Souza", "emailAddress": "maria.souza@mailinator.com" },
    { "name": "João Lima", "emailAddress": "joao.lima@mailinator.com" }
  ]
}
```

Para criar os contatos a partir de um arquivo CSV:

1. Faça o upload do arquivo com `POST /api/uploads`, como no [passo 1 da criação de documentos](https://docs.lacunasoftware.com/articles/signer/integration/documents#1-upload-do-arquivo).
2. Envie o ID do upload em `uploadId`, com `type` igual a `Csv`.

O CSV tem as colunas `name`, `email`, `identifier` e `description`, sem diferenciar maiúsculas de minúsculas. Se o upload não existe, a API responde com o erro `UploadNotFound`. A resposta das duas formas é a lista dos contatos criados.

Para excluir vários contatos, envie a lista dos IDs no corpo:

```json
POST /api/organization/contacts/batch/delete
[ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "9b2c1e4d-8f3a-4c6b-a1d2-0e5f7a8b9c10" ]
```

### Quem pode gerenciar os contatos

Os administradores e gerentes da organização podem ver, criar, alterar e excluir contatos. Os operadores e os usuários básicos só podem ver e usar os contatos, a não ser que a instância permita que eles também os gerenciem (configuração `General:AllowBasicAndOperatorUsersToManageContacts`, em [Configurações do Signer](https://docs.lacunasoftware.com/articles/signer/on-premises/settings)).

### Rotas da interface web

A interface web usa duas rotas que não estão na referência da API (Swagger):

* As rotas terminadas em `/personal` (por exemplo `GET /api/organization/contacts/personal`) fazem o mesmo que as rotas sem o sufixo. A interface usa essas rotas para a conta pessoal do usuário.
* `GET /api/organization/contacts/participant-search?q=maria` pesquisa, sem repetir pessoas, os usuários da organização, os contatos (`includeContacts=true`) e os usuários de fora da organização (`includeExternalUsers=true`). A instância pode desligar as duas últimas buscas na seção `AdvancedSearch` das [Configurações do Signer](https://docs.lacunasoftware.com/articles/signer/on-premises/settings). Cada item informa a origem em `origin`: `Contact`, `OrganizationUser` ou `ExternalOrganizationUser`.

## Identificadores de um usuário

Quando a instância permite vários identificadores por usuário, um usuário pode ter, por exemplo, um CPF e um passaporte. Veja [Identificação de participantes](https://docs.lacunasoftware.com/articles/signer/concepts/participant-identification#multiple-identifiers). Estas rotas não estão na referência da API (Swagger).

| Operação | Rota |
| --- | --- |
| Listar | `GET /api/users/{userId}/identifiers` |
| Adicionar | `POST /api/users/{userId}/identifiers` |
| Alterar o valor | `PUT /api/users/{userId}/identifiers/{identifierId}` |
| Excluir | `DELETE /api/users/{userId}/identifiers/{identifierId}` |

Um usuário que entrou no Signer gerencia os próprios identificadores com as mesmas rotas sem `/users/{userId}`, por exemplo `GET /api/identifiers`. Essas rotas não aceitam chave de API. Para gerenciar os identificadores de outro usuário, a chave precisa do papel de administrador do sistema, como a [chave de API de administração](https://docs.lacunasoftware.com/articles/signer/on-premises/administration#criação-de-chave-de-api-de-administração).

Cada identificador tem `type` e `value`. A resposta também traz `id` e `isGrant`, que indica o identificador sincronizado com o Grant ID:

```json
POST /api/users/4d961566-9b03-450c-b144-930e0294bac2/identifiers
{
  "type": "Passport",
  "value": "AB123456"
}
```

Cada usuário tem no máximo um identificador de cada tipo. O `PUT` altera só o valor: para mudar o tipo, exclua o identificador e adicione outro. Erros comuns:

| Código | Quando |
| --- | --- |
| `InvalidIdentifierValue` | O valor não é válido para o tipo, por exemplo um CPF com dígito verificador errado. |
| `IdentifierAlreadyBeingUsedCode` | O usuário já tem um identificador desse tipo. |
| `IdentifierNotFound` | O `identifierId` não pertence ao usuário. |
| `CannotDeleteGrantIdentifier` | O identificador é do tipo padrão da instância e é sincronizado com o Grant ID. |