Usando a Expansion API

Este guia rápido leva você do zero à leitura de sinais de expansão ao vivo em poucas chamadas. Ele pressupõe que você já tem uma chave de API da Pubrio — veja Autenticação para criar uma.

Pré-requisitos

Uma chave de API da Pubrio (veja Autenticação).
O domain_search_id de uma empresa. Você pode obter um a partir do endpoint Company Search.

Todos os endpoints de Expansion são POST e aceitam um corpo JSON. Inclua suas credenciais em cada requisição conforme descrito em Autenticação.

Passo 1 — Consultar a expansão de uma empresa

Comece com uma única empresa e liste todos os mercados para os quais ela está se expandindo.

POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}

Passo 2 — Interpretar o resultado

Cada entrada em markets_summary descreve um mercado no qual a empresa está ativa:

stage_slug — o quão longe a empresa avançou ali (exploring → scaling).
signal_count / distinct_type_count — quantas evidências sustentam o mercado, e em quantos tipos de sinal.
latest_signal_at — a atualidade do sinal mais recente.
signal_velocity_30d / signal_velocity_90d — a velocidade com que a atividade está aumentando.
rank_now — a posição atual do mercado para essa empresa (1 = mais forte).
is_home_market — se este é o país-sede da empresa.

Para identificar os movimentos mais recentes ou filtrar por trajetória, use os endpoints de descoberta (freshness, momentum) mostrados a seguir.

Passo 3 — Explorar um mercado inteiro

Para trabalhar primeiro pelo mercado em vez de pela empresa, use Expansion Market Detail. Ele é paginado com os parâmetros padrão page / per_page. Geografia é uma relação direcionada de → para, expressa com duas listas: froms (mercados de origem / sede) e tos (mercados de destino). Escolha o padrão que corresponde à sua pergunta:

POST /expansions/search
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "tos": ["GB"],
  "page": 1,
  "per_page": 25
}

Leia metadata.pagination para paginar pelos resultados:

{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}

Solicite a próxima página incrementando page. O per_page é limitado pelo seu plano — solicitar explicitamente mais do que seu limite retorna um erro em vez de truncar silenciosamente. Dois padrões que vale a pena conhecer:

Ordenação — os resultados retornam em ordem de relevância (empresas corroboradas por múltiplos tipos de sinal primeiro, depois as mais recentes). Passe sort_by: "recent" para ordenação puramente por data, ou expansion_score / signal_count / company_ranking.
Respostas enxutas — respostas com chave de API omitem o resumo do mercado (metadata.aggregate, principais origens/destinos, timeline) e o detalhe do modelo por padrão. Passe is_include_metadata: true quando quiser incluí-los.

Passo 4 — Investigar a evidência

Quando você quiser os sinais individuais por trás do movimento de uma empresa, chame Company Signal Events.

POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}

Esse endpoint retorna total_entries e total_pages — solicite as páginas de 1 até total_pages (ou seja, continue enquanto page for menor que total_pages).

Referência de filtros

A maioria dos endpoints de Expansion aceita estes filtros. Seus valores válidos estão listados em How Expansion Signals Work:

Filtro	Finalidade
`stages`	Limita a um ou mais estágios de expansão.
`freshness`	Limita pela atualidade da evidência.
`momentum`	Limita pela trajetória (`advancing`/`steady`/`pulling_back`).
`scopes`	Limita pelo escopo de entrada no mercado.
`signal_types`	Limita a tipos de sinal específicos.
`froms`	Mercados de origem / sede (expandindo de).
`tos`	Mercados de destino (expandindo para).
`companies`	Restringe a empresas específicas por `domain_search_id`, domínio ou URL do LinkedIn.

O filtro companies aceita qualquer combinação de tipos de identificador — sem necessidade de resolver para IDs primeiro:

POST /expansions/search
{ "companies": ["stripe.com", "airbnb.com"] }

POST /expansions/search
{ "companies": ["https://www.linkedin.com/company/stripe"] }

POST /expansions/search
{ "companies": ["550e8400-e29b-41d4-a716-446655440002"] }

Não confunda fluxo com trajetória. O fluxo (a direção do movimento entre mercados) é definido por froms / tos — não existe um filtro de requisição direction separado. A trajetória (como o movimento está progredindo) é o filtro momentum, e aparece nas respostas como o campo direction.

Base de Conhecimento

Guias

Conceitos

Estudos de Caso

Pré-requisitos

Passo 1 — Consultar a expansão de uma empresa

Passo 2 — Interpretar o resultado

Passo 3 — Explorar um mercado inteiro

Passo 4 — Investigar a evidência

Referência de filtros

Próximos passos

Exemplo Prático

Endpoints de Expansion

​Pré-requisitos

​Passo 1 — Consultar a expansão de uma empresa

​Passo 2 — Interpretar o resultado

​Passo 3 — Explorar um mercado inteiro

​Passo 4 — Investigar a evidência

​Referência de filtros

​Próximos passos

Exemplo Prático

Endpoints de Expansion

Pré-requisitos

Passo 1 — Consultar a expansão de uma empresa

Passo 2 — Interpretar o resultado

Passo 3 — Explorar um mercado inteiro

Passo 4 — Investigar a evidência

Referência de filtros

Próximos passos