Pessoas

Pessoas de até 200 empresas (ao vivo, por departamento e senioridade)

POST consome créditos

O preço desta operação para a sua conta fica em Configurações → Planos, já com o valor negociado do seu workspace.

Encontra quem trabalha HOJE em até 200 empresas numa chamada (busca ao vivo), filtrando por departamento e senioridade no mesmo vocabulário da base (Vendas, Marketing, C-Level, Gestão…; aliases como comercial, ti, cs, c_level, gerente, diretor são aceitos e normalizados). Só entra quem tem o emprego atual numa das empresas pedidas; sobrenome abreviado fica fora. Sócios (seniorities: ["Sócio"]) vêm do quadro societário da base e saem na mesma resposta com relationship: "socio".

Empresas em companies[], cada item com UM de cnpj, company_id, linkedin_url (página da empresa) ou domain; cnpj/linkedin_url soltos no corpo valem como uma empresa. Empresa sem página no LinkedIn nem site verificado na base conta em meta.companies_unresolved (não é erro). max_per_company (máx. 50) reparte as vagas entre as empresas; padrão = limit com uma empresa só, 10 com várias. job_titles.include casa palavra inteira do cargo; frase ("Diretor Financeiro") é aceita e só volta quem tem a frase inteira no cargo. Mais resultados: reenvie o mesmo corpo com cursor = meta.next_cursor.

Lista de empresas → lista de pessoas: com list_id (lista de empresas do workspace) a busca roda nas empresas da lista, página a página, e quem está na base é salvo numa lista de pessoas derivada; a resposta traz people_list_id, saved, with_contact_path e cursor em meta. Sem list_id, save_to_list: true salva as pessoas das empresas enviadas do mesmo jeito.

Decisores: decision_makers: true soma C-Level, Gestão, Liderança e Sócio (diretor/head = Liderança, VP = C-Level, gerente = Gestão). Já enriquecidos: exclude_enriched e exclude_list_ids tiram as pessoas antes da cobrança; a contagem volta em meta.excluded_already_enriched.

Toda pessoa volta com person_id, aceito em POST /api/v1/enrichment/person, listas e dossiê.

⚡ Consome créditos: preço por pessoa entregue (colaborador); a mesma pessoa entregue de novo em 30 dias não é cobrada; sócios sem custo. Nada encontrado ou nenhuma empresa buscável = sem débito. Veja seu price book em Configurações → Planos.

Idempotência: header x-idempotency-key (ou idempotency_key no body).

Rate limit: 20 req/min

01

Testar ao vivo

Autorização

Sua API key, gerada em /developer/api-keys. Gratuita para começar.

Sua requisição

curl -X POST 'https://tamz.ai/api/v1/people/discover' \
  -H 'Authorization: Bearer tamz_SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "companies": [
    {
      "cnpj": "12345678000190"
    },
    {
      "domain": "empresa.com.br"
    }
  ],
  "cnpj": "12345678000190",
  "departments": [
    "Vendas"
  ],
  "seniorities": [
    "Gestão"
  ],
  "limit": 10,
  "exclude_enriched": false
}'
02

Corpo da requisição

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

03

Exemplo de retorno

{
  "data": [
    {
      "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
      "relationship": "socio",
      "full_name": "string",
      "first_name": "string",
      "last_name": "string",
      "job_title": "string",
      "department": "Vendas",
      "seniority": "C-Level",
      "linkedin_url": "http://example.com",
      "location": "string",
      "started_on": "2023-04",
      "company": {
        "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
        "cnpj": "string",
        "name": "string"
      },
      "contact_path": true
    }
  ],
  "meta": {
    "credits_used": 0,
    "delivered": 0,
    "delivered_socios": 0,
    "delivered_colaboradores": 0,
    "available_estimate": 0,
    "companies_resolved": 0,
    "companies_unresolved": 0,
    "truncated": 0,
    "unresolved": [
      {
        "input": "string",
        "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
        "cnpj": "string",
        "reason": "not_found"
      }
    ],
    "skipped": {
      "left": 0,
      "abroad": 0,
      "abbreviated": 0,
      "off_filter": 0,
      "company_cap": 0
    },
    "next_cursor": "string",
    "partial": true,
    "excluded_already_enriched": 0,
    "people_list_id": "71f4479e-9064-4cbc-b6dc-44ea1330b2ff",
    "saved": 0,
    "save_error": "string",
    "source_list_id": "7c9f4ad0-76ac-4177-9877-b9faf1850d62",
    "not_saved": 0,
    "with_contact_path": 0,
    "without_contact_path": 0,
    "billed_credits": 0,
    "companies_in_page": 0,
    "credits_exhausted": true,
    "warning": "string",
    "cursor": "string",
    "meta": {}
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Use Authorization: Bearer tamz_xxx or X-API-Key header"
  }
}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits",
    "required": 10,
    "available": 3,
    "upgrade_path": "/settings/plans",
    "next_action": "Top up credits and retry — zero-result searches are never charged."
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 42
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
04

Respostas e códigos

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Começar grátis