Breadcrumbs

Gestão de Pessoas

Endpoints para criação, atualização e consulta de registros de pessoa na base da plataforma.

Todas as requisições exigem o cabeçalho Authorization veja Autenticação e Segurança.

Índice desta página

Criar Pessoa

Cria um novo registro de pessoa na base da plataforma.

Request 

POST https://api.cvortex.com/v1/person

Header: Authorization

Parâmetros de body

Nome

Tipo

Descrição

Obrigatório

contactsToAdd

array

Lista de contatos a serem adicionados. Cada item contém fieldLabel e value.

Não

contactsToRemove

array

Lista de contatos a serem removidos.

Não

details

array

Detalhes adicionais da pessoa. Cada item contém fieldUUID, fieldLabel e value.

Não

fields

array

Informações principais da pessoa. Cada item contém fieldLabel e value.

Sim

Estrutura dos arrays contactsToAdd, contactsToRemove, details, fields

Nome

Tipo

Descrição

Obrigatório

fieldLabel

string

Nome do campo

Sim

fieldUUID

string

Identificador único do campo (para details)

Não

value

string

Valor associado ao campo

Sim

Para a lista completa de tipos de contato aceitos em Contact Type (WHATSAPP, WEBCHAT, TELEGRAM, INSTAGRAM, MESSENGER, etc.), veja Canais e Mensagens.

Exemplo de Payload

JSON
{
  "contactsToAdd": [
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "EMAIL" },
        { "fieldLabel": "Value", "value": "email@empresas.com" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "MOBILE_PHONE" },
        { "fieldLabel": "Value", "value": "34999999999" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "LANDLINE_PHONE" },
        { "fieldLabel": "Value", "value": "3499999999" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "WHATSAPP" },
        { "fieldLabel": "Value", "value": "34999999999" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "WEBCHAT" },
        { "fieldLabel": "Value", "value": "67f7c6440732aa3e366e5000" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "TELEGRAM" },
        { "fieldLabel": "Value", "value": "nome.sobrenome" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "INSTAGRAM" },
        { "fieldLabel": "Value", "value": "nome.sobrenome10" }
      ]
    },
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "MESSENGER" },
        { "fieldLabel": "Value", "value": "9478174898924321" }
      ]
    }
  ],
  "contactsToRemove": [],
  "details": [
    {
      "fieldUUID": "bfb0d1bbc08448278a6c9315a4443fc6",
      "fieldLabel": "nome da mae",
      "value": "Nome Sobrenome Materno"
    },
    {
      "fieldUUID": "50da4da8174747e7887920aca05eef7d",
      "fieldLabel": "nome do pai",
      "value": "Nome Sobrenome Paterno"
    },
    {
      "fieldUUID": "6ef81032d05b44e4846f92647b1860d6",
      "fieldLabel": "data de nascimento",
      "value": "-220309200000"
    }
  ],
  "fields": [
    { "fieldLabel": "Document", "value": "012.345.678-89" },
    { "fieldLabel": "Full Name", "value": "Nome Sobrenome" }
  ]
}

Response

Código

Descrição

200

Pessoa criada com sucesso
JSON
{
    "document": "012.345.678-89",
    "easyId": "15787",
    "fullName": "Nome Sobrenome",
    "id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
    "personDetails": [
        {
            "Created at": 1747938561046,
            "Created by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
            "Deleted": false,
            "Person Id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
            "Updated at": 1747938561046,
            "Updated by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
            "_id": "d5c04eb8-6664-4a02-bfa1-440bcd60f857",
            "_version": "0",
            "data de nascimento": -220309200000,
            "nome da mae": "Nome Sobrenome Materno",
            "nome do pai": "Nome Sobrenome Paterno"
        }
    ]
}

Atualizar Pessoa

Atualiza um registro existente de pessoa.

Request 

PUT https://api.cvortex.com/v1/person

Header: Authorization

Parâmetros de body

Nome

Tipo

Descrição

Obrigatório

contactsToAdd

array

Lista de contatos a serem adicionados. Cada item contém fieldLabel e value.

Não

contactsToRemove

array

Lista de contatos a serem removidos.

Não

details

array

Detalhes adicionais da pessoa. Cada item contém fieldUUID, fieldLabel e value.

Não

fields

array

Deve conter ao menos o Id da pessoa (fieldLabel: "Id"). Pode conter outros dados a atualizar.

Sim

Estrutura dos arrays contactsToAdd, contactsToRemove, details, fields

Nome

Tipo

Descrição

Obrigatório

fieldLabel

string

Nome do campo

Sim

fieldUUID

string

Identificador único do campo (somente em details)

Não

value

string

Valor associado ao campo

Sim

Exemplo de Payload

JSON
{
  "contactsToAdd": [
    {
      "fields": [
        { "fieldLabel": "Contact Type", "value": "WHATSAPP" },
        { "fieldLabel": "Value", "value": "34999999999" }
      ]
    }
  ],
  "contactsToRemove": [],
  "details": [],
  "fields": [
    { "fieldLabel": "Id", "value": "4b640da5-8f61-4a9d-8871-9714c3096fb4" }
  ]
}

Response

Código

Descrição

200

Pessoa atualizada com sucesso
JSON
{
    "id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
    "fullName": "Nome Sobrenome",
    "document": "012.345.678-89",
    "easyId": "15787",
    "personDetails": [
        {
            "nome do pai": "Nome Sobrenome Paterno",
            "data de nascimento": -220309200000,
            "Updated by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
            "Deleted": false,
            "Created by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
            "_id": "d5c04eb8-6664-4a02-bfa1-440bcd60f857",
            "Updated at": 1747938561046,
            "nome da mae": "Nome Sobrenome Materno",
            "Person Id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
            "_version": "0",
            "Created at": 1747938561046
        }
    ]
}

Buscar pessoa (v1)

Permite buscar uma pessoa pelo seu nome e documento.

Request 

GET https://api.cvortex.com/v1/person

Header: Authorization

Parâmetros de URI

Parâmetro

Descrição

Obrigatório

document

Documento completo da pessoa

Não

eqFullName

Nome completo da pessoa (exato)

Não

fullName

Parte do nome da pessoa (busca parcial)

Não

email

E-mail da pessoa

Não

jobTitle

Cargo da pessoa

Não

Response

JSON
[
  {
    "document": "string",
    "easyId": "string",
    "email": "string",
    "jobTitle": "string",
    "fullName": "string",
    "id": "string"
  }
]

Buscar pessoa (v2)

Permite consultar registros de pessoas a partir de um identificador, como documento. Retorna os dados principais da pessoa e seus detalhes associados.

Request 

GET https://api.cvortex.com/v2/person?document=012.345.678-89

Header: Authorization

Parâmetros de URI

Nome

Tipo

Descrição

Obrigatório

document

string

Documento da pessoa (ex: CPF)

Sim

Response

Código

Descrição

200

Operação realizada com sucesso
JSON
[
  {
    "id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
    "fullName": "Nome Sobrenome",
    "document": "012.345.678-89",
    "easyId": "15787",
    "personDetails": [
      {
        "nome do pai": "Nome Sobrenome Paterno",
        "data de nascimento": -220309200000,
        "Updated by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
        "Deleted": false,
        "Created by": "59105e3f-c1a1-4ed1-a4ed-50d4ac408be3",
        "_id": "d5c04eb8-6664-4a02-bfa1-440bcd60f857",
        "Updated at": 1747938561046,
        "nome da mae": "Nome Sobrenome Materno",
        "Person Id": "4b640da5-8f61-4a9d-8871-9714c3096fb4",
        "_version": "0",
        "Created at": 1747938561046
      }
    ]
  }
]

Encontrar pessoa por nome, documento ou contato

Permite buscar uma pessoa por nome, documento ou contatos, usando um único parâmetro de busca livre.

Request 

GET https://api.cvortex.com/v1/person/value?limit=[LIMIT]&value=[VALOR]

Header: Authorization

Parâmetros de query

Nome

Tipo

Descrição

Obrigatório

limit

inteiro

Limite de resultados

Não

value

string

Valor para busca (nome, e-mail, etc.)

Sim

Response

Código

Descrição

200

Operação realizada com sucesso

Exemplo 

GET https://api.cvortex.com/v1/person/value?limit=1&value=nome
JSON
[
  {
    "id": "3e3e58bf-67bb-4de4-8ab7-42644642971e",
    "fullName": "Nome Sobrenome",
    "easyId": "91",
    "active": true,
    "createdAt": 1680224990213,
    "updatedAt": 1696013284498,
    "createdBy": "default-user",
    "updatedBy": "d447a00a-53ad-4714-88b3-d81b6632fd19",
    "deleted": false,
    "contacts": [
      {
        "id": "fff3580e-0ba0-431c-b944-60f90726ebb4",
        "contactType": "MOBILE_PHONE",
        "value": "34999999999",
        "channelType": "VOICE",
        "createdAt": 1680224990398,
        "active": true,
        "deleted": false
      }
    ]
  }
]

Contar pessoas

Permite contar a quantidade de pessoas conforme os filtros informados.

Request 

GET https://api.cvortex.com/v1/person/co

Header: Authorization

Parâmetros de URI

Parâmetro

Descrição

Obrigatório

document

Documento completo da pessoa

Não

eqFullName

Nome completo da pessoa (exato)

Não

fullName

Parte do nome da pessoa (busca parcial)

Não

email

E-mail da pessoa

Não

jobTitle

Cargo da pessoa

Não

Response 

number

Unificar pessoas (merge)

Une duas pessoas na plataforma. A pessoa de destino recebe todos os atendimentos e contatos da pessoa que está sendo unificada (juntada). A pessoa juntada é excluída após o processo, e a operação não pode ser desfeita.

Request 

POST https://api.cvortex.com/v1/person/merge/{personId}/{personIdToMerge}

Header: Authorization

Parâmetros de URI

Parâmetro

Descrição

Obrigatório

personId

ID da pessoa que vai permanecer ativa

Sim

personIdToMerge

ID da pessoa que será unificada na de cima (e excluída ao final)

Sim

Atenção: esta operação é irreversível confirme os IDs antes de executar.

Exemplo 

POST https://api.cvortex.com/v1/person/merge/3e3e58bf-67bb-4de4-8ab7-42644642971e/6e6e58bf-67bb-4de4-8ab7-42644642971f