---
title: "Contacts and identifiers"
description: "How to manage the organization's contacts through the Signer API, including in a batch from a CSV file, and a user's identifiers (CPF, passport and others)."
canonical: "https://docs.lacunasoftware.com/en-us/articles/signer/integration/contacts"
locale: "en"
product: "Signer"
last_updated: "2026-10-22"
---

# Contacts and identifiers

A contact is a person in the organization's address book: name, e-mail, identifier, phone and a description. On the document creation screen, the Signer suggests contacts to fill in the participants. This page shows how to manage contacts and a user's identifiers through the API.

## Contacts

All routes start with `/api/organization/contacts`. Without the `organizationId` query string parameter, the organization is the API key's organization.

| Operation | Route |
| --- | --- |
| List and search | `GET /api/organization/contacts?q=maria&limit=20&offset=0` |
| Create | `POST /api/organization/contacts` |
| Get | `GET /api/organization/contacts/{contactId}` |
| Update | `PUT /api/organization/contacts/{contactId}` |
| Delete | `DELETE /api/organization/contacts/{contactId}` |
| Create in a batch | `POST /api/organization/contacts/batch/create` |
| Delete in a batch | `POST /api/organization/contacts/batch/delete` |

The `q` parameter searches the start of the first or last name, the start of the e-mail, phone and identifier, and the words of the description. The list returns the contacts in `items` and the total in `totalCount`.

The create and update body has these fields:

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

The `name` and `emailAddress` fields are required. The `identifierType` field is required when the instance accepts more than one identifier type. The types are in [The participant (`user`)](https://docs.lacunasoftware.com/en-us/articles/signer/integration/document-fields#participant-user).

### Create and delete in a batch

To create several contacts at once, send the list in `contacts` with `type` set to `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" }
  ]
}
```

To create the contacts from a CSV file:

1. Upload the file with `POST /api/uploads`, as in [step 1 of document creation](https://docs.lacunasoftware.com/en-us/articles/signer/integration/documents#1-upload-the-file).
2. Send the upload ID in `uploadId`, with `type` set to `Csv`.

The CSV has the `name`, `email`, `identifier` and `description` columns, case-insensitive. If the upload does not exist, the API responds with the `UploadNotFound` error. Both forms return the list of created contacts.

To delete several contacts, send the list of IDs in the body:

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

### Who can manage contacts

The organization's administrators and managers can view, create, update and delete contacts. Operators and basic users can only view and use contacts, unless the instance also lets them manage contacts (the `General:AllowBasicAndOperatorUsersToManageContacts` setting, in [Signer settings](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/settings)).

### Web interface routes

The web interface uses two routes that are not in the API reference (Swagger):

* Routes ending in `/personal` (for example `GET /api/organization/contacts/personal`) do the same as the routes without the suffix. The interface uses them for the user's personal account.
* `GET /api/organization/contacts/participant-search?q=maria` searches, without repeating people, the organization's users, the contacts (`includeContacts=true`) and users outside the organization (`includeExternalUsers=true`). The instance can turn the last two searches off in the `AdvancedSearch` section of the [Signer settings](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/settings). Each item gives its source in `origin`: `Contact`, `OrganizationUser` or `ExternalOrganizationUser`.

## A user's identifiers

When the instance allows multiple identifiers per user, a user can have, for example, a CPF and a passport. See [Participant identification](https://docs.lacunasoftware.com/en-us/articles/signer/concepts/participant-identification#multiple-identifiers). These routes are not in the API reference (Swagger).

| Operation | Route |
| --- | --- |
| List | `GET /api/users/{userId}/identifiers` |
| Add | `POST /api/users/{userId}/identifiers` |
| Change the value | `PUT /api/users/{userId}/identifiers/{identifierId}` |
| Delete | `DELETE /api/users/{userId}/identifiers/{identifierId}` |

A signed-in user manages their own identifiers with the same routes without `/users/{userId}`, for example `GET /api/identifiers`. These routes do not accept an API key. To manage another user's identifiers, the key needs the system administrator role, like the [administration API key](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#creating-an-administration-api-key).

Each identifier has `type` and `value`. The response also has `id` and `isGrant`, which marks the identifier synchronized with Grant ID:

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

Each user has at most one identifier of each type. The `PUT` changes only the value: to change the type, delete the identifier and add another one. Common errors:

| Code | When |
| --- | --- |
| `InvalidIdentifierValue` | The value is not valid for the type, for example a CPF with a wrong check digit. |
| `IdentifierAlreadyBeingUsedCode` | The user already has an identifier of this type. |
| `IdentifierNotFound` | The `identifierId` does not belong to the user. |
| `CannotDeleteGrantIdentifier` | The identifier is of the instance's default type and is synchronized with Grant ID. |