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:

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).

Create and delete in a batch

To create several contacts at once, send the list in contacts with type set to Contacts:

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.
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:

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).

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. 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. 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.

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

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.