Pular para o conteúdo
Maestron Maestron / Docs /
Acessar painel

Contatos

O recurso Contato representa uma pessoa registrada no CRM. Cada contato pertence a uma empresa (tenant), resolvida automaticamente a partir do token — ver Autenticação.

Identificadores de contato usam o prefixo cont_ (ex.: cont_01J9Z3K8).

Esquema do recurso

Seção intitulada “Esquema do recurso”
CampoTipoObrigatórioDescrição
idstringleituraIdentificador prefixado (cont_).
namestringsimNome completo do contato. Entre 2 e 150 caracteres.
emailstringnãoE-mail do contato. Formato válido, máx. 255 caracteres. Único por empresa.
phonestringnãoTelefone em formato livre. Máx. 30 caracteres.
documentstringnãoDocumento (CPF/CNPJ). Máx. 20 caracteres. Único por empresa quando informado.
positionstringnãoCargo do contato. Máx. 100 caracteres.
company_idstringnãoEmpresa CRM (comp_) à qual o contato está vinculado. Deve existir na mesma empresa (tenant).
owner_idstringnãoUsuário (user_) responsável pelo contato. Deve pertencer à mesma empresa (tenant).
tagsstring[]nãoLista de etiquetas. Cada etiqueta com até 50 caracteres.
notesstringnãoObservações. Máx. 5000 caracteres.
created_atstring (ISO-8601)leituraData de criação.
updated_atstring (ISO-8601)leituraData da última atualização.

Listar contatos

Seção intitulada “Listar contatos”

Retorna uma coleção paginada de contatos da empresa. Aceita os parâmetros padrão de paginação, busca e ordenação (ver Convenções). A busca (search) percorre name, email, phone e document.

GET /crm/contacts

Listar contatos

Lista os contatos da empresa com paginação, busca e ordenação.

Parâmetros de query

CampoTipoObrigatórioDescrição
page integer — Página atual (padrão: 1).
per_page integer — Itens por página (padrão: 20, máx: 100).
search string — Busca textual em nome, e-mail, telefone e documento.
sort string — Campo de ordenação (ex.: name, created_at).
direction string — Direção da ordenação: asc ou desc.
owner_id string — Filtra pelos contatos de um responsável (user_).
company_id string — Filtra pelos contatos vinculados a uma empresa CRM (comp_).
tag string — Filtra contatos que possuem a etiqueta informada.
created_from date — Filtra por data de criação (início).
created_to date — Filtra por data de criação (fim). 
curl -X GET https://api.maestron.com.br/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/crm/contacts', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/v1/crm/contacts",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/v1/crm/contacts");
var data = await response.Content.ReadAsStringAsync();
GET /crm/contacts HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contatos listados.",
  "data": [
    {
      "id": "cont_01J9Z3K8",
      "name": "Ana Souza",
      "email": "ana.souza@exemplo.com.br",
      "phone": "+55 11 98888-7777",
      "document": "123.456.789-09",
      "position": "Gerente de Compras",
      "company_id": "comp_01J9Z3K8",
      "owner_id": "user_01J9Z3K8",
      "tags": [
        "vip",
        "inbound"
      ],
      "notes": null,
      "created_at": "2026-06-18T10:12:00Z",
      "updated_at": "2026-06-18T10:12:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}
{
  "message": "Não autenticado."
}

Obter um contato

Seção intitulada “Obter um contato”

Retorna um único contato pelo seu identificador.

GET /crm/contacts/{id}

Obter contato

Retorna os dados de um contato específico.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_). 
curl -X GET https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/crm/contacts/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/v1/crm/contacts/{id}");
var data = await response.Content.ReadAsStringAsync();
GET /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contato retornado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Gerente de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "vip",
      "inbound"
    ],
    "notes": "Prefere contato por e-mail.",
    "created_at": "2026-06-18T10:12:00Z",
    "updated_at": "2026-06-18T10:12:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}

Criar contato

Seção intitulada “Criar contato”

Cria um novo contato na empresa. Apenas name é obrigatório. Quando informados, email e document devem ser únicos dentro da empresa.

POST /crm/contacts

Criar contato

Cria um contato na empresa.

Corpo (body)

CampoTipoObrigatórioDescrição
name string Sim Nome completo (2 a 150 caracteres).
email string — E-mail válido, único por empresa (máx. 255).
phone string — Telefone (máx. 30).
document string — Documento, único por empresa quando informado (máx. 20).
position string — Cargo (máx. 100).
company_id string — Empresa CRM vinculada (comp_).
owner_id string — Usuário responsável (user_).
tags string[] — Etiquetas (cada uma até 50 caracteres).
notes string — Observações (máx. 5000). 
curl -X POST https://api.maestron.com.br/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Gerente de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "vip",
      "inbound"
    ],
    "notes": "Prefere contato por e-mail."
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/contacts', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'Ana Souza',
        'email' => 'ana.souza@exemplo.com.br',
        'phone' => '+55 11 98888-7777',
        'document' => '123.456.789-09',
        'position' => 'Gerente de Compras',
        'company_id' => 'comp_01J9Z3K8',
        'owner_id' => 'user_01J9Z3K8',
        'tags' => vip,inbound,
        'notes' => 'Prefere contato por e-mail.',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Gerente de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": vip,inbound,
    "notes": "Prefere contato por e-mail.",
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/contacts",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Gerente de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "vip",
      "inbound"
    ],
    "notes": "Prefere contato por e-mail."
  }),
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"name\":\"Ana Souza\",\"email\":\"ana.souza@exemplo.com.br\",\"phone\":\"+55 11 98888-7777\",\"document\":\"123.456.789-09\",\"position\":\"Gerente de Compras\",\"company_id\":\"comp_01J9Z3K8\",\"owner_id\":\"user_01J9Z3K8\",\"tags\":[\"vip\",\"inbound\"],\"notes\":\"Prefere contato por e-mail.\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/crm/contacts", payload);
var data = await response.Content.ReadAsStringAsync();
POST /crm/contacts HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "name": "Ana Souza",
  "email": "ana.souza@exemplo.com.br",
  "phone": "+55 11 98888-7777",
  "document": "123.456.789-09",
  "position": "Gerente de Compras",
  "company_id": "comp_01J9Z3K8",
  "owner_id": "user_01J9Z3K8",
  "tags": [
    "vip",
    "inbound"
  ],
  "notes": "Prefere contato por e-mail."
}

Respostas

{
  "message": "Contato criado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Gerente de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "vip",
      "inbound"
    ],
    "notes": "Prefere contato por e-mail.",
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Já existe um contato com este e-mail nesta empresa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "name": [
      "O campo nome é obrigatório."
    ],
    "email": [
      "O campo e-mail deve ser um endereço de e-mail válido."
    ]
  }
}

Atualizar contato

Seção intitulada “Atualizar contato”

Atualiza parcialmente um contato. Apenas os campos enviados são alterados. As regras de unicidade de email e document continuam valendo, ignorando o próprio registro.

PATCH /crm/contacts/{id}

Atualizar contato

Atualiza parcialmente os dados de um contato.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_).

Corpo (body)

CampoTipoObrigatórioDescrição
name string — Nome completo (2 a 150 caracteres).
email string — E-mail válido, único por empresa (máx. 255).
phone string — Telefone (máx. 30).
document string — Documento, único por empresa quando informado (máx. 20).
position string — Cargo (máx. 100).
company_id string — Empresa CRM vinculada (comp_).
owner_id string — Usuário responsável (user_).
tags string[] — Etiquetas (cada uma até 50 caracteres).
notes string — Observações (máx. 5000). 
curl -X PATCH https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "position": "Diretora de Compras",
    "tags": [
      "vip",
      "inbound",
      "decisor"
    ]
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/v1/crm/contacts/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'position' => 'Diretora de Compras',
        'tags' => vip,inbound,decisor,
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "position": "Diretora de Compras",
    "tags": vip,inbound,decisor,
}
response = requests.patch(
    "https://api.maestron.com.br/v1/crm/contacts/{id}",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "position": "Diretora de Compras",
    "tags": [
      "vip",
      "inbound",
      "decisor"
    ]
  }),
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"position\":\"Diretora de Compras\",\"tags\":[\"vip\",\"inbound\",\"decisor\"]}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/v1/crm/contacts/{id}") { Content = payload });
var data = await response.Content.ReadAsStringAsync();
PATCH /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "position": "Diretora de Compras",
  "tags": [
    "vip",
    "inbound",
    "decisor"
  ]
}

Respostas

{
  "message": "Contato atualizado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "Ana Souza",
    "email": "ana.souza@exemplo.com.br",
    "phone": "+55 11 98888-7777",
    "document": "123.456.789-09",
    "position": "Diretora de Compras",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "vip",
      "inbound",
      "decisor"
    ],
    "notes": "Prefere contato por e-mail.",
    "created_at": "2026-06-18T10:12:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}
{
  "message": "Já existe um contato com este e-mail nesta empresa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O campo e-mail deve ser um endereço de e-mail válido."
    ]
  }
}

Remover contato

Seção intitulada “Remover contato”

Remove um contato da empresa.

DELETE /crm/contacts/{id}

Remover contato

Remove um contato da empresa.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_). 
curl -X DELETE https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/v1/crm/contacts/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.delete(
    "https://api.maestron.com.br/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.DeleteAsync("https://api.maestron.com.br/v1/crm/contacts/{id}");
var data = await response.Content.ReadAsStringAsync();
DELETE /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contato removido."
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}

A descrição completa de cada código de status está em Erros.