Salvy API

https://docs.salvy.com.br/api-reference/
Admin
Salvy API is a REST-based platform that provides secure access to virtual phone numbers, employee...
Tokens:10,585
Snippets:38
Trust Score:7.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example GET Request using cURL

Source: https://docs.salvy.com.br/api-reference/introduction

An example of how to make a GET request to the Salvy API using the cURL command-line tool, including authentication and content type headers.

```shell
curl -X GET "https://api.salvy.com/resource" \
-H "Authorization: Bearer abc123def456gh789" \
-H "Content-Type: application/json"
```

--------------------------------

### Integration Source Example (JSON)

Source: https://docs.salvy.com.br/api-reference/employees/list

This snippet shows the structure for integration sources of an employee in the Salvy API, indicating the ID and platform of the integration.

```json
[
  { "id": "123", "platform": "api" }
]
```

--------------------------------

### Install Svix SDK for Node.js and Python

Source: https://docs.salvy.com.br/api-reference/webhooks/verifying-payloads

Provides commands to install the Svix SDK, essential for verifying webhook authenticity in Node.js and Python applications. Ensure you have npm or pip installed.

```shell
# Instalação para Node.js
npm install svix
```

```shell
# Instalação para Python
pip install svix
```

--------------------------------

### Collaborator Sources Example

Source: https://docs.salvy.com.br/api-reference/employees/sync

This snippet demonstrates the structure for defining sources of integration for collaborator data. It specifies an ID and the platform from which the data originates.

```json
[ { "id": "123", "platform": "api" } ]
```

--------------------------------

### Collaborator Snapshot via API Example

Source: https://docs.salvy.com.br/api-reference/employees/sync

This JSON snippet shows the structure of a collaborator snapshot obtained via the API, including work and personal emails, full name, and status.

```json
{
  "fullName": "João da Silva Santos",
  "workEmail": "joaosilva@empresa.com.br",
  "personalEmail": "joao04@gmail.com",
  "status": "active"
}
```

--------------------------------

### Employee Data Structure Example (JSON)

Source: https://docs.salvy.com.br/api-reference/employees/list

This snippet demonstrates the JSON structure for an employee object in the Salvy API. It includes essential fields like ID, name, contact information, status, and employment details.

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "fullName": "João da Silva",
  "socialName": "João",
  "status": "active",
  "workEmail": "user@example.com",
  "personalEmail": "user@example.com",
  "workPhoneNumber": "+5511999999999",
  "personalPhoneNumber": "+5511999999999",
  "cpf": "123.456.789-09",
  "cnpj": "12.345.678/0001-95",
  "rg": "12.345.678-9",
  "position": "Desenvolvedor",
  "area": "Engenharia",
  "managerFullName": "Maria dos Santos",
  "birthDate": "2023-10-05",
  "contractType": "clt",
  "contractEndDate": "2023-10-05",
  "admittedAt": "2023-10-05",
  "terminatedAt": "2023-10-05",
  "address": {},
  "customFields": [
    {
      "label": "teste",
      "type": "text",
      "value": "teste"
    }
  ],
  "bankAccount": {},
  "salaryCents": 500000,
  "sources": [
    { "id": "123", "platform": "api" }
  ],
  "assetCount": 10,
  "phoneAccountCount": 3,
  "externalPhoneAccountCount": 5
}
```

--------------------------------

### Custom Field Example (JSON)

Source: https://docs.salvy.com.br/api-reference/employees/list

This snippet illustrates the structure for custom fields associated with an employee in the Salvy API. It includes a label, type, and value for each custom field.

```json
[
  {
    "label": "teste",
    "type": "text",
    "value": "teste"
  }
]
```

--------------------------------

### Manual Collaborator Edit Example

Source: https://docs.salvy.com.br/api-reference/employees/sync

This JSON snippet demonstrates the structure for manually editing collaborator information, including full name, work email, and status.

```json
{
  "fullName": "João da Silva",
  "workEmail": "joaosilva@empresa.com.br",
  "status": "active"
}
```

--------------------------------

### GET /employees

Source: https://docs.salvy.com.br/api-reference/employees/list

Retrieves a list of employees with their detailed information. The response includes various attributes such as ID, names, contact details, employment status, contract information, and more.

```APIDOC
## GET /employees

### Description
Retrieves a list of employees with their detailed information. The response includes various attributes such as ID, names, contact details, employment status, contract information, and more.

### Method
GET

### Endpoint
/employees

### Parameters
#### Query Parameters
(No query parameters specified)

#### Request Body
(No request body)

### Response
#### Success Response (200)
- **employees** (object[]) - Required - An array of employee objects. Each employee object contains the following fields:
  - **id** (string) - Required - Identificador do colaborador na plataforma Salvy (UUID)
  - **fullName** (string) - Required - Nome completo
  - **socialName** (string | null) - Required - Nome social
  - **status** (enum<string>) - Required - Situação do colaborador (Available options: `active`, `terminated`, `on-hold`)
  - **workEmail** (string | null) - Required - E-mail profissional
  - **personalEmail** (string | null) - Required - E-mail pessoal
  - **workPhoneNumber** (string | null) - Required - Telefone profissional
  - **personalPhoneNumber** (string | null) - Required - Telefone pessoal
  - **cpf** (string | null) - Required - Número do CPF
  - **cnpj** (string | null) - Required - CNPJ do colaborador
  - **rg** (string | null) - Required - RG do colaborador
  - **position** (string | null) - Required - Cargo do colaborador
  - **area** (string | null) - Required - Área do colaborador
  - **managerFullName** (string | null) - Required - Nome do gestor
  - **birthDate** (string | null) - Required - Data de nascimento
  - **contractType** (enum<string> | null) - Required - Tipo de contrato (Available options: `pj`, `clt`, `intern`, `apprentice`, `temporary`, `third-party`)
  - **contractEndDate** (string | null) - Required - Data de término do contrato
  - **admittedAt** (string | null) - Required - Data de admissão
  - **terminatedAt** (string | null) - Required - Data de desligamento
  - **address** (object | null) - Required - Endereço do colaborador
  - **customFields** (object[]) - Required - Campos personalizados do colaborador
  - **bankAccount** (object | null) - Required - Dados bancários do colaborador
  - **salaryCents** (number | null) - Required - Salário em centavos
  - **sources** (object[]) - Required - Fontes de integração do colaborador
  - **assetCount** (number) - Required - Quantidade de ativos vinculados ao colaborador
  - **phoneAccountCount** (number) - Required - Quantidade de linhas Salvy vinculadas ao colaborador
  - **externalPhoneAccountCount** (number) - Required - Quantidade de linhas de outras operadoras vinculadas ao colaborador

#### Response Example
```json
{
  "employees": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "fullName": "João da Silva",
      "socialName": "João",
      "status": "active",
      "workEmail": "user@example.com",
      "personalEmail": "user@example.com",
      "workPhoneNumber": "+5511999999999",
      "personalPhoneNumber": "+5511999999999",
      "cpf": "123.456.789-09",
      "cnpj": null,
      "rg": "12.345.678-9",
      "position": "Desenvolvedor",
      "area": "Engenharia",
      "managerFullName": "Maria dos Santos",
      "birthDate": "2023-10-05",
      "contractType": "clt",
      "contractEndDate": null,
      "admittedAt": "2023-10-05",
      "terminatedAt": null,
      "address": {},
      "customFields": [
        {
          "label": "teste",
          "type": "text",
          "value": "teste"
        }
      ],
      "bankAccount": {},
      "salaryCents": 500000,
      "sources": [
        { "id": "123", "platform": "api" }
      ],
      "assetCount": 10,
      "phoneAccountCount": 3,
      "externalPhoneAccountCount": 5
    }
  ]
}
```
```

--------------------------------

### General Request Structure

Source: https://docs.salvy.com.br/api-reference/introduction

Our API follows REST standards and utilizes standard HTTP methods for operations: GET for retrieval, POST for creation, PATCH for updates, and DELETE for removal.

```APIDOC
## General Request Structure

Our API follows REST standards and uses the following HTTP methods for operations:

*   GET: To retrieve information.
*   POST: To create new resources.
*   PATCH: To update existing resources.
*   DELETE: To remove resources.
```

--------------------------------

### Reconciled Collaborator Data Example

Source: https://docs.salvy.com.br/api-reference/employees/sync

This JSON snippet illustrates the resulting structure after reconciling manual edits with API snapshot data, showing combined fields like full name, work email, personal email, and status.

```json
{
  "fullName": "João da Silva",
  "workEmail": "joaosilva@empresa.com.br",
  "personalEmail": "joao04@gmail.com",
  "status": "active"
}
```

--------------------------------

### GET /api/v2/virtual-phone-accounts/{id}

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/get-beta

This endpoint allows companies to retrieve a virtual phone number by its ID.

```APIDOC
## GET /api/v2/virtual-phone-accounts/{id}

### Description
Retrieve a specific virtual phone account using its unique identifier.

### Method
GET

### Endpoint
/api/v2/virtual-phone-accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the virtual phone account.

#### Query Parameters
None

#### Request Body
None

### Request Example
```curl
curl --request GET \
  --url https://api.salvy.com.br/api/v2/virtual-phone-accounts/{id} \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - A valid UUID string, in any version.
- **name** (string | null) - Identifier for the virtual number. Use this for easier management of virtual numbers.
- **phoneNumber** (string) - The virtual number, formatted according to the E.164 international standard.
- **status** (enum<string>) - The status of the virtual phone account. Available options: `active`, `canceled`.
- **createdAt** (string<date-time>) - The timestamp when the virtual phone account was created.
- **canceledAt** (string<date-time> | null) - The timestamp when the virtual phone account was canceled.
- **cancelReason** (string | null) - The reason for cancellation, if applicable.
- **redirectPhoneNumber** (string | null) - The designated number to receive calls directed to the virtual number, formatted according to the E.164 international standard.
- **redirectExpiresAt** (string<date-time> | null) - The expiration date for the call redirection.

#### Response Example
```json
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "name": "meu-número-virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": null,
  "cancelReason": null,
  "redirectPhoneNumber": "+5511999999999",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}
```

#### Error Responses
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **422** - Unprocessable Entity
- **500** - Internal Server Error
```

--------------------------------

### List Virtual Phone Accounts

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/list-beta

This snippet demonstrates how to list virtual phone accounts using a GET request to the Salvy BR API. It requires an Authorization header with a Bearer token. The response includes details of virtual phone accounts such as ID, name, phone number, status, and associated dates.

```cURL
curl --request GET \
  --url https://api.salvy.com.br/api/v2/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>'
```

```json
[
  {
    "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
    "name": "meu-número-virtual",
    "phoneNumber": "+551151231234",
    "status": "active",
    "createdAt": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "cancelReason": "<string>",
    "redirectPhoneNumber": "+5511999999999",
    "redirectExpiresAt": "2024-01-03T00:00:00Z"
  }
]
```

--------------------------------

### List Virtual Phone Accounts

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/list

This endpoint allows businesses to list their created virtual phone numbers. Note: This endpoint is deprecated and suggests using GET /api/v2/virtual-phone-accounts.

```APIDOC
## GET /api/v1/virtual-phone-accounts

### Description
This endpoint allows businesses to list their created virtual phone numbers.

### Method
GET

### Endpoint
/api/v1/virtual-phone-accounts

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer authentication header of the form `Bearer <token>`.

### Request Example
```curl
curl --request GET \
  --url https://api.salvy.com.br/api/v1/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - A valid UUID string.
- **identifier** (string) - Identifier for the virtual number.
- **phoneNumber** (string) - Virtual number in E.164 format.
- **status** (enum<string>) - Status of the virtual number (`active`, `canceled`).
- **createdAt** (string<date-time>) - Creation timestamp.
- **canceledAt** (string<date-time> | null) - Cancellation timestamp.
- **cancelReason** (string | null) - Reason for cancellation.
- **redirectPhoneNumber** (string | null) - Number to redirect calls to, in E.164 format.
- **redirectExpiresAt** (string<date-time> | null) - Call redirection expiration date.

#### Response Example
```json
[
  {
    "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
    "identifier": "meu-número-virtual",
    "phoneNumber": "+551151231234",
    "status": "active",
    "createdAt": "2023-11-07T05:31:56Z",
    "canceledAt": null,
    "cancelReason": null,
    "redirectPhoneNumber": "+5511999999999",
    "redirectExpiresAt": "2024-01-03T00:00:00Z"
  }
]
```
```

--------------------------------

### Retrieve Virtual Phone Account by ID (cURL)

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/get-beta

This snippet demonstrates how to retrieve a specific virtual phone account using its ID via a cURL GET request. It requires an 'Authorization' header with a Bearer token. The response includes details of the virtual phone account or an error code.

```cURL
curl --request GET \
  --url https://api.salvy.com.br/api/v2/virtual-phone-accounts/{id} \
  --header 'Authorization: Bearer <token>'
```

```JSON
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "name": "meu-número-virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": "2023-11-07T05:31:56Z",
  "cancelReason": "<string>",
  "redirectPhoneNumber": "+5511999999999",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}
```

--------------------------------

### POST /api/v2/virtual-phone-accounts

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create-beta

This endpoint allows companies to create virtual phone numbers for use in situations like WhatsApp Business registration.

```APIDOC
## POST /api/v2/virtual-phone-accounts

### Description
This endpoint allows companies to create virtual phone numbers for use in situations like WhatsApp Business registration.

### Method
POST

### Endpoint
/api/v2/virtual-phone-accounts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string | null) - Required - Name of the virtual number. Use this to easily manage the virtual numbers.
  Example: `"Meu Número Virtual"`
- **areaCode** (number) - Required - Area code (DDD) associated with the virtual number.
  Example: `11`

### Request Example
```json
{
  "name": "Meu Número Virtual",
  "areaCode": 11
}
```

### Response
#### Success Response (200)
- **id** (string) - Required - A valid UUID string, in any version.
  Examples: `"123e4567-e89b-12d3-a456-426614174000"`, `"123e4567-e89b-12d3-a456-426614174001"
- **name** (string | null) - Required - Name of the virtual number. Use this to easily manage the virtual numbers.
  Example: `"Meu Número Virtual"`
- **phoneNumber** (string) - Required - Newly created virtual number, formatted according to the international E.164 standard.
  Examples: `"+5511999999999"`, `"+551139999999"
- **status** (enum<string>) - Required - Available options: `active`, `canceled`
- **createdAt** (string<date-time>) - Required
- **canceledAt** (string<date-time> | null) - Required
- **cancelReason** (string | null) - Required

#### Response Example
```json
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "name": "Meu Número Virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": null,
  "cancelReason": null
}
```

### Authorizations
- **Authorization** (string) - Header - Required - Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.
```

--------------------------------

### Create Virtual Phone Account using cURL

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create

This snippet demonstrates how to create a virtual phone account by sending a POST request to the Salvy API's /api/v1/virtual-phone-accounts endpoint. It includes necessary headers for authorization and content type, and a JSON payload with account details.

```cURL
curl --request POST \
  --url https://api.salvy.com.br/api/v1/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "identifier": "meu-número-virtual",
  "areaCode": 11,
  "redirectPhoneNumber": "11912341234",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}'
```

--------------------------------

### Manual Webhook Verification

Source: https://docs.salvy.com.br/api-reference/webhooks/verifying-payloads

An alternative to SDK verification is manual verification. This involves using the security key provided during application registration and the `svix-signature` header to implement validation logic.

```APIDOC
## Manual Webhook Verification

### Description
Manually verifies the authenticity of incoming webhooks using cryptographic standards.

### Method
* Manual signature verification

### Parameters
#### Request Headers
- **svix-signature** (string) - Required - The signature of the webhook request.

#### Security Key
* **Security Key**: Provided during application registration.

### Steps
1. Obtain the security key.
2. Capture the `svix-signature` header value.
3. Implement validation logic based on cryptographic standards.

### Response
* **Verification Status**: Indicates whether the webhook signature is valid.
* **Official Svix Documentation**: For detailed instructions on the manual verification process.
```

--------------------------------

### Create Virtual Phone Account

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create-beta

Creates a new virtual phone number for use with services like WhatsApp Business. Requires an authorization token and specifies the desired area code and a name for the number. The response includes the created number's details.

```cURL
curl --request POST \
  --url https://api.salvy.com.br/api/v2/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Meu Número Virtual",
  "areaCode": 11
}'
```

--------------------------------

### Webhook Request Format

Source: https://docs.salvy.com.br/api-reference/webhooks/introduction

This snippet shows the standard JSON format for all Salvy webhook requests. It includes the event type, a timestamp, and event-specific data.

```json
{
  "type": "event.name",
  "timestamp": "2025-09-03T12:34:56Z",
  "data": {
    // Dados específicos do evento
  }
}
```

--------------------------------

### Salvy API Base URL

Source: https://docs.salvy.com.br/api-reference/introduction

All API requests must be made to the following base URL. Ensure you use HTTPS for secure communication.

```APIDOC
## Base URL

All requests to the API should be made to the following base URL:

```
https://api.salvy.com.br
```

Ensure you use HTTPS for all your requests to guarantee communication security.
```

--------------------------------

### Authentication Header Format

Source: https://docs.salvy.com.br/api-reference/introduction

Specifies the required format for the Authorization header to authenticate API requests using a Bearer Token.

```text
Authorization: Bearer <seu_token>
```

--------------------------------

### List Collaborators

Source: https://docs.salvy.com.br/api-reference/employees/sync

Retrieves a list of collaborators from the Salvy platform. This endpoint returns detailed information about each collaborator, including their personal and professional details, employment status, and contract information.

```APIDOC
## GET /collaborators

### Description
Retrieves a list of collaborators with their detailed information.

### Method
GET

### Endpoint
/collaborators

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter collaborators by their status (e.g., `active`, `terminated`, `on-hold`).
- **position** (string) - Optional - Filter collaborators by their job position.
- **area** (string) - Optional - Filter collaborators by their department or area.

### Request Example
```json
{
  "example": "GET /collaborators?status=active&area=Engineering"
}
```

### Response
#### Success Response (200)
- **id** (string) - Identificador do colaborador na plataforma Salvy (UUID).
- **fullName** (string) - Nome completo.
- **socialName** (string | null) - Nome social.
- **status** (enum<string>) - Situação do colaborador (`active`, `terminated`, `on-hold`).
- **workEmail** (string | null) - E-mail profissional.
- **personalEmail** (string | null) - E-mail pessoal.
- **workPhoneNumber** (string | null) - Telefone profissional (E.164 format).
- **personalPhoneNumber** (string | null) - Telefone pessoal (E.164 format).
- **cpf** (string | null) - Número do CPF.
- **cnpj** (string | null) - CNPJ do colaborador.
- **rg** (string | null) - RG do colaborador.
- **position** (string | null) - Cargo do colaborador.
- **area** (string | null) - Área do colaborador.
- **managerFullName** (string | null) - Nome do gestor.
- **birthDate** (string | null) - Data de nascimento (ISO 8601 format).
- **contractType** (enum<string> | null) - Tipo de contrato (`pj`, `clt`, `intern`, `apprentice`, `temporary`, `third-party`).
- **contractEndDate** (string | null) - Data de término do contrato (ISO 8601 format).
- **admittedAt** (string | null) - Data de admissão (ISO 8601 format).
- **terminatedAt** (string | null) - Data de desligamento (ISO 8601 format).
- **address** (object | null) - Endereço do colaborador.
- **customFields** (object[]) - Campos personalizados do colaborador.
- **bankAccount** (object | null) - Dados bancários do colaborador.
- **bankAccount.bank** (string | null) - Banco.
- **bankAccount.branch** (string | null) - Agência.
- **bankAccount.accountNumber** (string | null) - Número da conta.
- **bankAccount.accountType** (enum<string> | null) - Tipo de conta (`checking`, `savings`, `salary`, `payment`).
- **bankAccount.pixKey** (string | null) - Chave PIX.
- **salaryCents** (number | null) - Salário em centavos.
- **sources** (object[]) - Fontes de integração do colaborador.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "fullName": "João da Silva",
  "socialName": "João",
  "status": "active",
  "workEmail": "user@example.com",
  "personalEmail": "user@example.com",
  "workPhoneNumber": "+5511999999999",
  "personalPhoneNumber": "+5511999999999",
  "cpf": "123.456.789-09",
  "cnpj": null,
  "rg": "12.345.678-9",
  "position": "Desenvolvedor",
  "area": "Engenharia",
  "managerFullName": "Maria dos Santos",
  "birthDate": "2000-01-01",
  "contractType": "clt",
  "contractEndDate": null,
  "admittedAt": "2022-01-01",
  "terminatedAt": null,
  "address": {},
  "customFields": [
    {
      "label": "teste",
      "type": "text",
      "value": "teste"
    }
  ],
  "bankAccount": {
    "bank": "Banco do Brasil",
    "branch": "1234",
    "accountNumber": "123456",
    "accountType": "checking",
    "pixKey": "joao04@gmail.com"
  },
  "salaryCents": 500000,
  "sources": [
    { "id": "123", "platform": "api" }
  ]
}
```
```

--------------------------------

### Create Virtual Phone Account

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create

This endpoint allows businesses to create virtual phone numbers for various use cases, such as registration with WhatsApp Business. It is deprecated and recommends using the /api/v2/virtual-phone-accounts endpoint.

```APIDOC
## POST /api/v1/virtual-phone-accounts

### Description
Allows businesses to create virtual phone numbers for use cases like WhatsApp Business registration. This endpoint is deprecated in favor of the v2 version.

### Method
POST

### Endpoint
/api/v1/virtual-phone-accounts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **areaCode** (number) - Required - The area code (DDD) associated with the virtual number. Must be between 11 and 99.
- **redirectPhoneNumber** (string) - Required - The phone number (including DDD) to which incoming calls will be redirected.
- **identifier** (string | null) - Optional - An identifier for the virtual number to facilitate management.
- **redirectExpiresAt** (string<datetime>) - Optional - The expiration date for call redirection. Defaults to 72 hours if not provided.

### Request Example
```json
{
  "identifier": "meu-número-virtual",
  "areaCode": 11,
  "redirectPhoneNumber": "11912341234",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}
```

### Response
#### Success Response (200)
- **id** (string) - A valid UUID string representing the unique ID of the virtual phone account.
- **identifier** (string | null) - The identifier provided for the virtual phone number.
- **phoneNumber** (string) - The newly created virtual phone number, formatted in E.164 standard.
- **status** (enum<string>) - The status of the virtual phone account. Possible values: `active`, `canceled`.
- **createdAt** (string<date-time>) - The timestamp when the virtual phone account was created.
- **canceledAt** (string<date-time> | null) - The timestamp when the virtual phone account was canceled.
- **cancelReason** (string | null) - The reason for cancellation, if applicable.
- **redirectPhoneNumber** (string | null) - The phone number designated to receive calls directed to the virtual number.
- **redirectExpiresAt** (string<date-time> | null) - The expiration date for the call redirection.

#### Response Example
```json
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "identifier": "meu-número-virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": null,
  "cancelReason": null,
  "redirectPhoneNumber": "+5511912341234",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}
```

### Error Handling
- **401**: Unauthorized
- **403**: Forbidden
- **404**: Not Found
- **409**: Conflict
- **422**: Unprocessable Entity
- **500**: Internal Server Error
```

--------------------------------

### Virtual Phone Account Creation Response

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create-beta

Represents a successful response when a virtual phone number is created via the Salvy API. It details the newly generated account, including its unique ID, name, phone number, status, and relevant timestamps.

```JSON
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "name": "Meu Número Virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": "2023-11-07T05:31:56Z",
  "cancelReason": "<string>"
}
```

--------------------------------

### Collaborator API Request Body Parameters

Source: https://docs.salvy.com.br/api-reference/employees/sync

Defines the parameters for the collaborator creation/update API request body, including integrationId, fullName, status, and optional fields like emails, phone numbers, CPF, position, area, manager, and dates.

```json
{
  "integrationId": "123",
  "fullName": "João da Silva",
  "status": "active",
  "socialName": "João",
  "workEmail": "joaosilva@empresa.com.br",
  "personalEmail": "joao04@gmail.com",
  "workPhoneNumber": "+5541923456789",
  "personalPhoneNumber": "+5541987654321",
  "cpf": "198.099.750-07",
  "position": "Desenvolvedor",
  "area": "Engenharia",
  "managerFullName": "Maria dos Santos",
  "birthDate": "1990-04-15",
  "admittedAt": "2020-05-27",
  "terminatedAt": "2021-01-20",
  "address": {}
}
```

--------------------------------

### Webhook Verification using Svix SDK

Source: https://docs.salvy.com.br/api-reference/webhooks/verifying-payloads

The recommended method for verifying webhook authenticity is by using the Svix SDK, available for multiple programming languages. Follow the official Svix documentation for detailed implementation steps.

```APIDOC
## Webhook Verification using Svix SDK

### Description
Verifies the authenticity of incoming webhooks using the Svix SDK.

### Method
* SDK-based verification

### Parameters
* **Svix SDK**: Available for Node.js, Python, and other languages.
* **Official Svix Documentation**: For detailed implementation instructions.

### Request Example
```
# Installation for Node.js
npm install svix

# Installation for Python
pip install svix
```

### Response
* **Verification Status**: Indicates whether the webhook signature is valid.
```

--------------------------------

### Collaborator Management API

Source: https://docs.salvy.com.br/api-reference/employees/sync

Endpoint for creating or updating collaborator information. It prioritizes `integrationId` for existing collaborators and uses `workEmail` or `fullName` if `integrationId` is not provided. If no match is found, a new collaborator record is created.

```APIDOC
## POST /collaborators

### Description
Creates or updates collaborator information. If an `integrationId` is provided, it searches for an existing collaborator. Otherwise, it searches by `workEmail` or `fullName`. If found, the collaborator is updated; otherwise, a new collaborator is created.

### Method
POST

### Endpoint
/collaborators

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer authentication header of the form `Bearer <token>`.

#### Request Body
- **integrationId** (string) - Required - Unique identifier of your choice for this collaborator.
- **fullName** (string) - Required - Full name of the collaborator.
- **status** (enum<string>) - Required - Status of the collaborator. Available options: `active`, `terminated`, `on-hold`.
- **socialName** (string) - Optional - Social name of the collaborator.
- **workEmail** (string) - Optional - Professional email address.
- **personalEmail** (string) - Optional - Personal email address.
- **workPhoneNumber** (string) - Optional - Professional phone number.
- **personalPhoneNumber** (string) - Optional - Personal phone number.
- **cpf** (string) - Optional - CPF number.
- **position** (string) - Optional - Collaborator's position.
- **area** (string) - Optional - Collaborator's area.
- **managerFullName** (string) - Optional - Manager's full name.
- **birthDate** (string) - Optional - Collaborator's birth date (YYYY-MM-DD).
- **admittedAt** (string) - Optional - Admission date (YYYY-MM-DD).
- **terminatedAt** (string) - Optional - Termination date (YYYY-MM-DD).
- **address** (object) - Optional - Collaborator's address details.

### Request Example
```json
{
  "integrationId": "123",
  "fullName": "João da Silva",
  "workEmail": "joaosilva@empresa.com.br",
  "status": "active",
  "personalEmail": "joao04@gmail.com",
  "position": "Developer",
  "admittedAt": "2020-05-27"
}
```

### Response
#### Success Response (200 or 201)
- **fullName** (string) - The full name of the collaborator.
- **workEmail** (string) - The professional email of the collaborator.
- **personalEmail** (string) - The personal email of the collaborator.
- **status** (string) - The current status of the collaborator.
- **integrationId** (string) - The integration ID associated with the collaborator.

#### Response Example
```json
{
  "fullName": "João da Silva",
  "workEmail": "joaosilva@empresa.com.br",
  "personalEmail": "joao04@gmail.com",
  "status": "active",
  "integrationId": "123"
}
```
```

--------------------------------

### Successful Virtual Phone Account Creation Response

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/create

This JSON object represents a successful response (HTTP 200) from the Salvy API after creating a virtual phone account. It contains the unique ID, identifier, assigned phone number, status, and timestamps for creation and cancellation.

```json
{
  "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
  "identifier": "meu-número-virtual",
  "phoneNumber": "+551151231234",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "canceledAt": "2023-11-07T05:31:56Z",
  "cancelReason": "<string>",
  "redirectPhoneNumber": "+5511999999999",
  "redirectExpiresAt": "2024-01-03T00:00:00Z"
}
```

--------------------------------

### Salvy API Base URL

Source: https://docs.salvy.com.br/api-reference/introduction

The base URL for all API requests to the Salvy platform. All communications should use HTTPS for security.

```text
https://api.salvy.com.br
```

--------------------------------

### List Virtual Phone Accounts

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/list-beta

This endpoint allows companies to list the virtual phone numbers they have created. It requires Bearer token authentication.

```APIDOC
## GET /api/v2/virtual-phone-accounts

### Description
This endpoint allows companies to list the virtual phone numbers they have created.

### Method
GET

### Endpoint
/api/v2/virtual-phone-accounts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl --request GET \
  --url https://api.salvy.com.br/api/v2/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - A valid UUID string.
- **name** (string | null) - Identifier for the virtual number.
- **phoneNumber** (string) - The virtual number, formatted according to the E.164 international standard.
- **status** (enum<string>) - Status of the virtual number (active, canceled).
- **createdAt** (string<date-time>) - Creation timestamp.
- **canceledAt** (string<date-time> | null) - Cancellation timestamp.
- **cancelReason** (string | null) - Reason for cancellation.
- **redirectPhoneNumber** (string | null) - The phone number designated to receive calls directed to the virtual number.
- **redirectExpiresAt** (string<date-time> | null) - The expiration date for call redirection.

#### Response Example
```json
[
  {
    "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
    "name": "meu-número-virtual",
    "phoneNumber": "+551151231234",
    "status": "active",
    "createdAt": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "cancelReason": null,
    "redirectPhoneNumber": "+5511999999999",
    "redirectExpiresAt": "2024-01-03T00:00:00Z"
  }
]
```

#### Error Responses
- **401**: Unauthorized
- **403**: Forbidden
- **404**: Not Found
- **422**: Unprocessable Entity
- **500**: Internal Server Error
```

--------------------------------

### API Authorization Header

Source: https://docs.salvy.com.br/api-reference/employees/sync

Specifies the required authorization header for API requests using Bearer token authentication. The token should be appended to 'Bearer '.

```string
Bearer <token>
```

--------------------------------

### Retrieve Virtual Phone Accounts (cURL)

Source: https://docs.salvy.com.br/api-reference/virtual-phone-accounts/list

This snippet demonstrates how to retrieve a list of virtual phone accounts using cURL. It requires an authorization token in the header. The response is a JSON array containing details of each virtual phone account, including ID, phone number, status, and timestamps.

```cURL
curl --request GET \
  --url https://api.salvy.com.br/api/v1/virtual-phone-accounts \
  --header 'Authorization: Bearer <token>'
```

```JSON
[
  {
    "id": "0140a8c6-3815-45b7-9e60-8e137cad845c",
    "identifier": "meu-número-virtual",
    "phoneNumber": "+551151231234",
    "status": "active",
    "createdAt": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "cancelReason": "<string>",
    "redirectPhoneNumber": "+5511999999999",
    "redirectExpiresAt": "2024-01-03T00:00:00Z"
  }
]
```

--------------------------------

### Authentication - Bearer Token

Source: https://docs.salvy.com.br/api-reference/introduction

Salvy API uses Bearer Token-based authentication for secure access. Include a valid authentication token in the 'Authorization' HTTP header for each API request.

```APIDOC
## Authentication

The Salvy API uses **Bearer Token** based authentication to ensure secure access to its resources. For each request to the API, it is necessary to include a valid authentication token in the `Authorization` HTTP header.

### Header Format

The token must be sent in the following format:

```
Authorization: Bearer <your_token>
```

*   Replace `<your_token>` with the token provided by Salvy.
*   The prefix `Bearer` is mandatory and must be followed by a space before the token.

### Request Example

Here is an example of a request using `curl`:

```bash
curl -X GET "https://api.salvy.com/resource" \
-H "Authorization: Bearer abc123def456gh789" \
-H "Content-Type: application/json"
```

### Authentication Errors

If the token is not provided or is invalid, the API will return an error with the status code `HTTP 401 Unauthorized`. Check if:

*   The token is correct.
*   The token has not expired.
*   The Authorization header follows the specified format.
```
Tokens:
Raw