Pessoas

Buscar pessoas

GET 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.

Pessoas de uma empresa: com company_cnpj_or_id a busca é ao vivo: só quem trabalha hoje na empresa, com linkedin_url em toda linha e id aceito em /api/v1/enrichment/person, listas e dossiê. Cobra por pessoa entregue (a mesma pessoa em 30 dias não paga de novo), não por registro. page × limit até 500 — além disso use POST /api/v1/people/discover com cursor. has_email/has_phone/has_linkedin junto com empresa → 400; q/company_state/company_city/company_cnae não se aplicam (aviso em meta.warnings) e fields=rich não traz identidade. Sócios (owners_only=true ou só seniority=Sócio) seguem na base com o preço por registro; Sócio junto com outras senioridades vem na mesma resposta (campo relationship), pelo preço por pessoa. meta.total é estimativa nesse modo.

Busca pessoas com filtros de cargo, senioridade, departamento e empresa (company_cnpj_or_id, company_state, company_city, company_cnae). state filtra a UF da empresa (alias depreciado de company_state). department/seniority/state são normalizados (acentos e aliases como TI→Tecnologia); valor desconhecido é 400 com os valores válidos — nunca zero silencioso. Parâmetro desconhecido é 400 UNKNOWN_PARAM. Retorna até 25 resultados por página (limit, padrão 10). Cobra por registro devolvido; zero resultados não debitam. Por padrão devolve o nível lean (nome, cargo, departamento, empresa) — passe fields=rich para linkedin_url, senioridade, cidade/UF e identidade por sobretaxa por linha. E-mail e telefone crus nunca saem daqui: use os endpoints de enriquecimento. meta sempre traz filters_applied + normalized_filters. Caminho oficial para volume (bulk): o fluxo de listas do MCP — tamz_create_list → tamz_add_to_list (até 500 ids por chamada; linhas já pagas na busca que as revelou) → tamz_list_items (até 200 linhas por página, releitura gratuita). Para audiências acima do teto diário, materialize a lista em vez de paginar este endpoint. tamz_list_filters expõe o vocabulário válido de department/seniority/UF para busca e MCP. Paginação anti-scraping: limit máximo 25 (padrão 10). Em 429 leia retry_after (segundos) e faça backoff exponencial a partir dele (teto 60s); em 402 (VOLUME_QUOTA_EXCEEDED) leia used/cap/reset_at e retome após reset_at — o teto diário é uniforme e não é elevado por cliente.

Decisores e exclusão: departments/seniorities/decision_makers seguem o formato do POST /people/discover (diretor/head = Liderança, VP = C-Level, gerente = Gestão). exclude_enriched tira quem já está na Carteira do workspace e exclude_list_ids tira quem está nas listas indicadas — quem sai não é cobrado; na busca ao vivo a contagem volta em meta.excluded_already_enriched.

01

Testar ao vivo

Parâmetros

Busca por nome ou cargo

Filtrar por cargo (pode repetir)

Nível hierárquico do vínculo. Valores exatos, com acento: C-Level · Liderança · Gestão · Sênior · Júnior · Sócio. Repita o parâmetro para somar níveis.

Área do vínculo, normalizada a partir do cargo. Valores exatos, com acento — atenção: é Vendas (não "Comercial") e Tecnologia (não "TI"). Repita o parâmetro para somar áreas.

UF da empresa vinculada (sigla de 2 letras, ex. SP; sp normaliza para SP). Alias depreciado de company_state — prefira o canônico. Valor que não seja UF é 400 com os valores válidos.

UF da empresa vinculada — filtro canônico (use no lugar de state). Sigla de 2 letras, ex. SP; caixa/acentos normalizados. Repita o parâmetro para somar UFs.

Cidade da empresa vinculada (caixa/acentos normalizados, ex. Curitiba). Repita o parâmetro para somar cidades.

CNPJ (14 dígitos) ou UUID da empresa para listar SÓ as pessoas vinculadas a ela. Repita o parâmetro para várias empresas (máx. 20). Identificador inválido é 400 invalid_company_identifier; nenhuma empresa encontrada é 404 company_not_found. Nunca cai para a base cheia. Com empresa, a busca é ao vivo (pessoas atuais), cobrada por pessoa entregue.

CNAE da empresa vinculada

Apenas sócios (true/false). Com empresa, true mantém a listagem de sócios da base (preço por registro).

Apenas com email disponível (true/false). Não se aplica com company_cnpj_or_id (busca ao vivo): 400.

Apenas com LinkedIn disponível (true/false). Não se aplica com company_cnpj_or_id (busca ao vivo): 400.

Apenas com telefone disponível (true/false). Não se aplica com company_cnpj_or_id (busca ao vivo): 400.

Mesmo filtro de department (somam), no formato do POST /people/discover. Aceita aliases (comercial, ti, cs…). Repita o parâmetro para somar áreas.

Mesmo filtro de seniority (somam). Aceita aliases: diretor/head = Liderança, VP = C-Level, gerente = Gestão. Repita o parâmetro para somar níveis.

true = decisores: soma C-Level, Gestão, Liderança e Sócio às senioridades pedidas (diretor/head = Liderança, VP = C-Level, gerente = Gestão). Com departamento pedido, Sócio não entra (peça explicitamente se quiser). Aceita só true ou false.

Palavras que excluem o cargo (repita o parâmetro; termos com menos de 2 letras são ignorados). Só com company_cnpj_or_id (busca ao vivo); sem empresa → 400.

Máximo de pessoas por empresa, de 1 a 25. Só com company_cnpj_or_id (busca ao vivo); sem empresa → 400. Padrão: page × limit.

true = tira quem o workspace já recebeu (Carteira) nos canais de exclude_enriched_channels, antes de cobrar. Padrão false. Com company_cnpj_or_id vale só na página 1 — para continuar, use POST /api/v1/people/discover com cursor. Não se aplica à listagem de sócios por empresa (owners_only ou só Sócio) → 400.

Canais que contam como "já enriquecido" com exclude_enriched=true: a pessoa sai se já recebeu algum deles. Padrão: todos. Repita o parâmetro ou separe por vírgula.

Tira quem já está nestas listas do workspace (UUIDs). Repita o parâmetro ou separe por vírgula; máximo 20. Lista de outro workspace é ignorada.

Página (1-based). Com empresa: page × limit ≤ 500.

Registros por página: 1 a 25 (padrão 10). Cada registro devolvido é cobrado no nível lean.

Nível de campos da resposta. lean (padrão) devolve só o cadastro que identifica o registro, cobrado por linha. rich acrescenta os campos firmográficos/LinkedIn e cobra uma sobretaxa por linha no mesmo débito.

Autorização

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

Sua requisição

curl -X GET 'https://tamz.ai/api/v1/people' \
  -H 'Authorization: Bearer tamz_SUA_API_KEY'
02

Exemplo de retorno

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "Izadora Lima",
      "cpf": "01683398114",
      "idade": 41,
      "sexo": "F",
      "job_title": "Commercial Executive Director",
      "seniority": "C-Level",
      "department": "Vendas",
      "linkedin_url": "https://www.linkedin.com/in/izadora-lima",
      "pic_url": "https://media.licdn.com/dms/image/v2/…",
      "location_city": "sao paulo",
      "location_state": "SP",
      "has_email": true,
      "has_phone": false,
      "contact_path": true,
      "company": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "cnpj": "84453844000188",
        "name": "Tellerina Comercio De Presentes S.A.",
        "segment": "Outras Industrias",
        "porte": "Demais",
        "revenue_range": "R$100M+",
        "state": "SP"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "offset": 0,
    "total": 187069,
    "has_more": true,
    "filters_applied": {
      "department": [
        "Tecnologia"
      ],
      "company_state": [
        "SP"
      ]
    },
    "normalized_filters": {
      "department": [
        "Tecnologia"
      ],
      "company_state": [
        "SP"
      ]
    },
    "credits_used": 0,
    "source": "live",
    "total_is_estimate": true,
    "live": {},
    "excluded_already_enriched": 0
  }
}
{
  "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": "VOLUME_QUOTA_EXCEEDED",
    "message": "Daily row quota reached (15000). Resets at 2026-09-04T00:00:00.000Z.",
    "used": 15000,
    "cap": 15000,
    "reset_at": "2026-09-04T00:00:00.000Z",
    "upgrade_path": "/settings/plans",
    "next_action": "Narrow filters, reduce page size, or continue after reset_at."
  }
}

{
  "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"
  }
}
03

Respostas e códigos

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Começar grátis