Contacts

Um contact é uma pessoa dentro de uma company do tipo organization — o roster de funcionários daquele cliente (comprador, financeiro, etc). Uma company do tipo individual (pessoa física) não tem contacts — ela já é a própria pessoa.

Escopo: customers.view para leitura, customers.manage para escrita — ver Escopos & Permissões.

Esquema

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	leitura	Identificador do contact.
company_id	string (UUID)	sim (na criação)	Company organização a que este contact pertence. Não muda depois de criado.
name	string	sim	Máx. 200 caracteres.
role	string | null	não	Cargo.
email	string | null	não
phone	string | null	não
whatsapp	string | null	não
department	string | null	não
is_primary	boolean	não	Marcar como principal desmarca os demais contacts da mesma company.
birthday	string (data) | null	não
notes	string | null	não	Máx. 5000 caracteres.
address_street, address_number, address_complement, address_neighborhood, address_city, address_state, address_zipcode	string | null	não	Endereço próprio do contact.
created_at	string (ISO-8601)	leitura
updated_at	string (ISO-8601)	leitura

Listar contacts

GET /crm/contacts Copiar para LLM

Listar contacts

Retorna os contacts da empresa, paginado. Filtre por company_id para listar só os de uma company.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
company_id	string	—	Restringe aos contacts desta company.
per_page	integer	—	Entre 1 e 100. Padrão 20.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/api/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/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/api/v1/crm/contacts",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/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/api/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

200 · Sucesso401 · Não autenticado403 · Sem escopo

{
  "message": "Contacts.",
  "data": [
    {
      "id": "c3d4e5f6-3333-4a5b-8c9d-0e1f2a3b4c5d",
      "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Maria Compras",
      "role": "Compradora",
      "email": "maria@acme.com",
      "phone": null,
      "whatsapp": null,
      "department": null,
      "is_primary": true,
      "birthday": null,
      "notes": null,
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

Obter um contact

GET /crm/contacts/{id} Copiar para LLM

Obter contact

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/api/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/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/api/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/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/api/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

200 · Sucesso401 · Não autenticado404 · Não encontrado

{
  "message": "Contact.",
  "data": {
    "id": "c3d4e5f6-3333-4a5b-8c9d-0e1f2a3b4c5d",
    "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Maria Compras"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Criar contact

POST /crm/contacts Copiar para LLM

Criar contact

idempotency_key é opcional — ver Sandbox & Idempotência.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
company_id	string	Sim	Company organização a vincular.
name	string	Sim
role	string	—
email	string	—
phone	string	—
is_primary	boolean	—
idempotency_key	string	—

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/api/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Maria Compras",
    "role": "Compradora",
    "email": "maria@acme.com"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/contacts', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'company_id' => 'a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d',
        'name' => 'Maria Compras',
        'role' => 'Compradora',
        'email' => 'maria@acme.com',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Maria Compras",
    "role": "Compradora",
    "email": "maria@acme.com",
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/contacts",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Maria Compras",
    "role": "Compradora",
    "email": "maria@acme.com"
  }),
});
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(
    "{\"company_id\":\"a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d\",\"name\":\"Maria Compras\",\"role\":\"Compradora\",\"email\":\"maria@acme.com\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/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

{
  "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
  "name": "Maria Compras",
  "role": "Compradora",
  "email": "maria@acme.com"
}

Respostas

201 · Criado401 · Não autenticado403 · Sem escopo422 · Validação — company inexistente ou pessoa física

{
  "message": "Contact criado.",
  "data": {
    "id": "c3d4e5f6-3333-4a5b-8c9d-0e1f2a3b4c5d",
    "company_id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Maria Compras",
    "role": "Compradora",
    "is_primary": false,
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Um company pessoa física não tem contatos.",
  "data": null
}

Atualizar contact

PATCH /crm/contacts/{id} Copiar para LLM

Atualizar contact

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
role	string	—

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X PATCH https://api.maestron.com.br/api/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "Gerente de Compras"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/api/v1/crm/contacts/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'role' => 'Gerente de Compras',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "role": "Gerente de Compras",
}
response = requests.patch(
    "https://api.maestron.com.br/api/v1/crm/contacts/{id}",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/contacts/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "role": "Gerente de Compras"
  }),
});
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(
    "{\"role\":\"Gerente de Compras\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/api/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

{
  "role": "Gerente de Compras"
}

Respostas

200 · Atualizado401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Contact atualizado.",
  "data": {
    "id": "c3d4e5f6-3333-4a5b-8c9d-0e1f2a3b4c5d",
    "role": "Gerente de Compras"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Remover contact

Quando o contact está vinculado a negócios do CRM, strategy decide o destino desses negócios.

DELETE /crm/contacts/{id} Copiar para LLM

Remover contact

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
strategy	string	—	unlink (padrão) desvincula os negócios; delete_leads apaga os negócios ligados; migrate transfere para outro contact.
migrate_to_contact_id	string	—	Obrigatório quando strategy = migrate.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X DELETE https://api.maestron.com.br/api/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/api/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/api/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/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/api/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

200 · Removido401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Contact removido.",
  "data": null
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Para o detalhamento de cada código de status, consulte Erros.