> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Busca de Expansão

> Encontra empresas em expansão para um ou mais mercados usando filtros firmográficos e de sinal ou uma consulta em linguagem natural, com explicações opcionais de correspondência geradas por IA, fundamentadas nos sinais reais de cada empresa.



## OpenAPI

````yaml pt-openapi POST /expansions/search
openapi: 3.0.0
info:
  description: >-
    A API Pubrio entrega inteligência de expansão de mercado — sinais em tempo
    real que indicam quando uma empresa entra em um novo mercado — além dos
    dados de empresas e pessoas por trás desses sinais. Pesquise, consulte e
    enriqueça contas e contatos, e assine sinais de movimentação tipados e
    datados em mais de 200 mercados.
  version: 1.0.0
  title: Pubrio OpenAPI
  termsOfService: https://pubrio.com/pt-BR/terms-of-service
  contact:
    email: king.lai@pubrio.com
    name: King Lai
    url: https://pubrio.com/pt-BR/get-in-touch
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.pubrio.com
security:
  - pubrio_api_key: []
tags:
  - name: Profile
    description: Informações do perfil da equipe e estatísticas de uso
  - name: Enrichment
    description: Enriqueça registros de pessoas e empresas com dados B2B detalhados
  - name: Lookalike
    description: Encontre empresas semelhantes a uma empresa específica
  - name: Search
    description: Pesquise pessoas, empresas, vagas, notícias e anúncios com filtros
  - name: Lookup
    description: >-
      Consulte informações detalhadas de pessoas, empresas, vagas, notícias,
      anúncios e tecnologias específicas
  - name: LinkedIn
    description: >-
      Consulte dados de pessoas e empresas por meio de URLs de perfil do
      LinkedIn
  - name: Redeem
    description: >-
      Resgate créditos para desbloquear detalhes de contato de pessoas
      (individual e em lote)
  - name: Channels
    description: >-
      Gerencie templates de canais de outreach (criar, atualizar, excluir,
      listar)
  - name: Monitor
    description: >-
      Crie e gerencie monitores de dados com webhooks, estatísticas e
      processamento
  - name: Filters
    description: >-
      Obtenha os valores de filtro disponíveis para os parâmetros de busca
      (tecnologias, localizações, verticais etc.)
  - name: API Keys
    description: >-
      Liste e inspecione logs de requisições da API e análises de uso das chaves
      de API
  - name: Insights
    description: Insights agregados de sinais para empresas (vagas, notícias, anúncios).
  - name: Export
    description: Exportações de dados em massa (consomem créditos).
  - name: Expansion
    description: >-
      Inteligência de expansão de mercado de empresas: sinais, estágios,
      mercados e exportações.
externalDocs:
  description: >-
    A API Pubrio é usada para pesquisar, pré-visualizar e enriquecer contatos e
    contas. O banco de dados Pubrio oferece dados extensos de contatos B2B e
    inteligência de vendas.
  url: https://docs.pubrio.com
paths:
  /expansions/search:
    post:
      tags:
        - Expansion
      summary: Busca de expansão
      description: >-
        Encontra empresas em expansão para um ou mais mercados usando filtros
        firmográficos e de sinal ou uma consulta em linguagem natural, com
        explicações opcionais de correspondência geradas por IA, fundamentadas
        nos sinais reais de cada empresa.
      operationId: expansions_search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                froms:
                  $ref: '#/components/schemas/expansion_froms'
                tos:
                  $ref: '#/components/schemas/expansion_tos'
                exclude_froms:
                  $ref: '#/components/schemas/expansion_exclude_froms'
                exclude_tos:
                  $ref: '#/components/schemas/expansion_exclude_tos'
                stages:
                  allOf:
                    - $ref: '#/components/schemas/expansion_stages'
                  description: >-
                    Os valores diferenciam maiúsculas de minúsculas e **não são
                    validados**. Um valor não reconhecido é descartado
                    silenciosamente em vez de rejeitado: em `stages`,
                    `freshness`, `scopes` e `momentum`, o filtro inteiro é
                    descartado e você obtém resultados *sem filtro*, enquanto em
                    `signal_types` e `signal_strengths` o filtro é aplicado e
                    não corresponde a *nada*. De qualquer forma, a resposta
                    parece normal. Resolva os slugs válidos em [Expansion
                    Reference](/pt/api-reference/endpoint/expansions/types) e
                    compare `data.pagination.total_entries` com uma chamada sem
                    filtro caso um conjunto de resultados pareça incorreto.
                momentum:
                  allOf:
                    - $ref: '#/components/schemas/expansion_momentum'
                  description: >-
                    Trajetória do movimento da empresa no mercado. `advancing`
                    indica ganho de terreno, `steady` indica estabilidade,
                    `pulling_back` cobre retração e contração.


                    **Não** use aqui os valores de `directions` em [Expansion
                    Reference](/pt/api-reference/endpoint/expansions/types).
                    Esses (`advancing`, `steady`, `retreating`, `new`) são os
                    valores de *resposta* retornados em `stage.direction`;
                    apenas os três listados acima são aceitos como *filtro*.
                    Enviar `retreating` ou `new` desativa o filtro
                    silenciosamente e retorna resultados sem filtro.
                freshness:
                  allOf:
                    - $ref: '#/components/schemas/expansion_freshness'
                  description: >-
                    Os valores diferenciam maiúsculas de minúsculas e **não são
                    validados**. Um valor não reconhecido é descartado
                    silenciosamente em vez de rejeitado: em `stages`,
                    `freshness`, `scopes` e `momentum`, o filtro inteiro é
                    descartado e você obtém resultados *sem filtro*, enquanto em
                    `signal_types` e `signal_strengths` o filtro é aplicado e
                    não corresponde a *nada*. De qualquer forma, a resposta
                    parece normal. Resolva os slugs válidos em [Expansion
                    Reference](/pt/api-reference/endpoint/expansions/types) e
                    compare `data.pagination.total_entries` com uma chamada sem
                    filtro caso um conjunto de resultados pareça incorreto.
                scopes:
                  $ref: '#/components/schemas/expansion_scopes'
                ahead_of_pace:
                  type: boolean
                  example: false
                  description: >-
                    Restringe a pares que avançam mais rápido que o ritmo típico
                    daquele mercado.
                signal_types:
                  allOf:
                    - $ref: '#/components/schemas/expansion_signal_type_slugs'
                  description: >-
                    Os valores diferenciam maiúsculas de minúsculas e **não são
                    validados**. Um valor não reconhecido é descartado
                    silenciosamente em vez de rejeitado: em `stages`,
                    `freshness`, `scopes` e `momentum`, o filtro inteiro é
                    descartado e você obtém resultados *sem filtro*, enquanto em
                    `signal_types` e `signal_strengths` o filtro é aplicado e
                    não corresponde a *nada*. De qualquer forma, a resposta
                    parece normal. Resolva os slugs válidos em [Expansion
                    Reference](/pt/api-reference/endpoint/expansions/types) e
                    compare `data.pagination.total_entries` com uma chamada sem
                    filtro caso um conjunto de resultados pareça incorreto.
                signal_strengths:
                  allOf:
                    - $ref: '#/components/schemas/signal_strengths'
                  description: >-
                    Os valores diferenciam maiúsculas de minúsculas e **não são
                    validados**. Um valor não reconhecido é descartado
                    silenciosamente em vez de rejeitado: em `stages`,
                    `freshness`, `scopes` e `momentum`, o filtro inteiro é
                    descartado e você obtém resultados *sem filtro*, enquanto em
                    `signal_types` e `signal_strengths` o filtro é aplicado e
                    não corresponde a *nada*. De qualquer forma, a resposta
                    parece normal. Resolva os slugs válidos em [Expansion
                    Reference](/pt/api-reference/endpoint/expansions/types) e
                    compare `data.pagination.total_entries` com uma chamada sem
                    filtro caso um conjunto de resultados pareça incorreto.
                min_signal_count:
                  type: integer
                  example: 3
                  description: >-
                    Número mínimo de sinais de expansão que uma empresa deve ter
                    na janela — "muito ativa / com forte presença".
                only_contraction:
                  $ref: '#/components/schemas/only_contraction'
                min_markets:
                  type: integer
                  example: 3
                  description: >-
                    Número mínimo de novos mercados que uma empresa deve ter
                    entrado na janela.
                home_country_code:
                  type: array
                  items:
                    type: string
                  example:
                    - SG
                  description: >-
                    Filtra pelo país de origem da empresa (ISO 3166-1 alpha-2).
                    Faz interseção com `froms` quando ambos são informados.
                industries:
                  $ref: '#/components/schemas/industries'
                exclude_industries:
                  $ref: '#/components/schemas/exclude_industries'
                verticals:
                  $ref: '#/components/schemas/verticals'
                vertical_categories:
                  $ref: '#/components/schemas/vertical_categories'
                vertical_sub_categories:
                  $ref: '#/components/schemas/vertical_sub_categories'
                technologies:
                  $ref: '#/components/schemas/technologies'
                employees:
                  $ref: '#/components/schemas/employees'
                revenues:
                  $ref: '#/components/schemas/revenues'
                founded_dates:
                  $ref: '#/components/schemas/founded_dates'
                keywords:
                  $ref: '#/components/schemas/keywords'
                companies:
                  $ref: '#/components/schemas/expansion_companies'
                job_locations:
                  $ref: '#/components/schemas/locations'
                job_exclude_locations:
                  $ref: '#/components/schemas/job_exclude_locations'
                job_posted_dates:
                  $ref: '#/components/schemas/posted_dates'
                job_titles:
                  $ref: '#/components/schemas/people_titles'
                advertisement_target_locations:
                  $ref: '#/components/schemas/advertisement_target_locations'
                advertisement_exclude_target_locations:
                  $ref: '#/components/schemas/advertisement_exclude_target_locations'
                advertisement_search_terms:
                  $ref: '#/components/schemas/advertisement_search_terms'
                advertisement_start_dates:
                  $ref: '#/components/schemas/advertisement_start_dates'
                advertisement_end_dates:
                  $ref: '#/components/schemas/advertisement_end_dates'
                news_categories:
                  $ref: '#/components/schemas/news_categories'
                news_published_dates:
                  $ref: '#/components/schemas/published_dates'
                transitioned_dates:
                  type: array
                  items:
                    type: string
                    format: date
                  example:
                    - '2026-04-01'
                    - '2026-06-29'
                  description: >-
                    Intervalo de datas ISO para a janela da linha do tempo. O
                    padrão são os últimos 90 dias. Uma `query` em linguagem
                    natural também pode definir esse intervalo a partir de
                    expressões de calendário ("this year", "last year", "Q2
                    2026").
                window_days:
                  $ref: '#/components/schemas/window_days'
                query:
                  type: string
                  example: fintech companies expanding into the UK
                  description: >-
                    Consulta em linguagem natural que a Pubrio interpreta em
                    filtros de expansão + empresa.
                is_explain_match:
                  type: boolean
                  example: true
                  description: >-
                    Inclui explicações geradas por IA sobre por que cada empresa
                    corresponde à busca, fundamentadas nos sinais reais da
                    empresa. Funciona melhor combinado a uma consulta em
                    linguagem natural. O número de sinais citados e o tamanho do
                    lote escalam com `per_page`; fontes de alto volume (vagas
                    publicadas, campanhas publicitárias) são resumidas como uma
                    contagem por janela (ex.: "12 job postings") em vez de
                    listadas individualmente.
                sort_by:
                  $ref: '#/components/schemas/expansion_sort_by'
                is_include_metadata:
                  allOf:
                    - $ref: '#/components/schemas/expansion_is_include_metadata'
                  description: >-
                    Retorna o payload completo de detalhes. O tráfego via chave
                    de API é enxuto por padrão: o bloco `model`, os valores de
                    confiança (`stage.confidence` em Company Expansion Detail,
                    `confidence_score` em `other_markets[]` e em `markers[]` de
                    Rankings) e os campos `established_min` /
                    `share_of_detected` / `has_known_office` são todos omitidos,
                    a menos que este valor seja `true`.
                page:
                  $ref: '#/components/schemas/page'
                per_page:
                  $ref: '#/components/schemas/per_page'
                is_enable_similarity_search:
                  type: boolean
                  description: >-
                    Ativa a correspondência por texto livre para `verticals`,
                    `vertical_categories`, `vertical_sub_categories` e
                    `technologies`; esses filtros são descartados a menos que
                    este valor seja `true`.
                  example: true
              anyOf:
                - title: From Markets
                  required:
                    - froms
                - title: To Markets
                  required:
                    - tos
                - title: Plain-language Query
                  required:
                    - query
                - title: Companies
                  required:
                    - companies
      responses:
        '200':
          description: >-
            Lista paginada de empresas em expansão no(s) mercado(s). `filters`
            reflete os critérios aplicados (ou interpretados a partir da
            linguagem natural); cada empresa inclui um `match_summary` quando
            `is_explain_match` é `true`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    description: >-
                      Metadados da busca: os filtros efetivamente aplicados,
                      mais a consolidação de mercado (agregado, escopo
                      geográfico, principais origens/destinos/setores, linha do
                      tempo). As respostas via chave de API incluem a
                      consolidação apenas quando `is_include_metadata` é `true`.
                    properties:
                      filters:
                        type: object
                        description: >-
                          Filtros efetivamente aplicados (reflete uma consulta
                          em linguagem natural interpretada quando `query` foi
                          usado).
                      relaxed_filters:
                        type: array
                        description: >-
                          Filtros flexíveis descartados automaticamente quando
                          uma consulta em linguagem natural não encontrou
                          nenhuma correspondência; `null` caso contrário.
                        items:
                          type: string
                      nl_note:
                        type: string
                        description: >-
                          Nota legível exibida quando uma consulta em linguagem
                          natural não expressa nenhum critério reconhecível;
                          nesse caso, a lista fica vazia.
                      nl_note_code:
                        type: string
                        description: >-
                          Código legível por máquina para `nl_note` (ex.:
                          `expansion.search.no_criteria`).
                      aggregate:
                        type: object
                        description: >-
                          Consolidação em nível de mercado. Presente quando os
                          metadados são solicitados.
                      country_code:
                        type: string
                      country_codes:
                        type: array
                        items:
                          type: string
                      direction:
                        type: string
                      is_global:
                        type: boolean
                      is_multi:
                        type: boolean
                      transitioned_dates:
                        type: array
                        items:
                          type: string
                      top_origins:
                        type: array
                        items:
                          type: object
                      top_destinations:
                        type: array
                        items:
                          type: object
                      top_industries:
                        type: array
                        items:
                          type: object
                      timeline:
                        type: array
                        items:
                          type: object
                  data:
                    type: object
                    description: >-
                      Contêiner de resultado (envelope padrão de busca): a lista
                      de empresas mais a paginação.
                    properties:
                      pagination:
                        type: object
                        description: >-
                          Página, itens por página, total de entradas e total de
                          páginas.
                      companies:
                        type: array
                        description: >-
                          A lista de empresas. Cada item traz um `stage`
                          aninhado; `match_summary` é incluído quando
                          `is_explain_match` é `true`. As respostas via chave de
                          API também incluem `presence` (`level`: established |
                          emerging | none | no_data; `matched_rule`: office |
                          headcount | share) e um objeto `read` cujo `code` é
                          scaling | deepening | active | establishing (`null`
                          quando não há presença local a reportar).
                        items:
                          type: object
              example:
                metadata:
                  filters:
                    tos:
                      - GB
                    verticals:
                      - Financial Services
                data:
                  pagination:
                    page: 1
                    per_page: 25
                    total_entries: 87
                    total_pages: 4
                    total_display_pages: 4
                    is_timeout: false
                  companies:
                    - expansion_id: '6845525'
                      domain_search_id: 8f3c1b04-2e7a-4d19-9c55-6ab21f0e7d3c
                      country_code: GB
                      target_country_code: GB
                      domain: example.com
                      company_name: Example Corp
                      home_country_code: CN
                      industry: Consumer Electronics
                      founded_year: 2015
                      employees_count: 320
                      stage:
                        slug: expanding
                        expansion_score: 0.72
                        scope: entering_new_market
                        direction: advancing
                        freshness: fresh
                        signal_count: 27
                        distinct_type_count: 3
                        last_transition_at: '2026-06-27T14:32:10.000Z'
                      presence:
                        level: established
                        local_people_count: 12
                        matched_rule: headcount
                        has_known_office: true
                        established_min: 10
                        share_of_detected: 0.54
                      read:
                        code: establishing
        '400':
          $ref: '#/components/responses/general_error'
        '429':
          $ref: '#/components/responses/rate_limit_error'
        '500':
          $ref: '#/components/responses/server_error'
components:
  schemas:
    expansion_froms:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: >-
        Mercados de origem (ISO 3166-1 alfa-2). De onde a empresa está se
        expandindo — seus países de origem/sede. Use sozinho para encontrar
        empresas crescendo a partir desses mercados; combine com `tos` para um
        corredor origem→destino específico.
    expansion_tos:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: >-
        Mercados de destino (ISO 3166-1 alfa-2). Para onde a empresa está se
        expandindo. Use sozinho para encontrar todas as empresas entrando nesses
        mercados; combine com `froms` para um corredor origem→destino
        específico.
    expansion_exclude_froms:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: Mercados de origem a excluir (ISO 3166-1 alfa-2).
    expansion_exclude_tos:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: Mercados de destino a excluir (ISO 3166-1 alfa-2).
    expansion_stages:
      type: array
      items:
        type: string
        enum:
          - exploring
          - committing
          - expanding
          - scaling
      example:
        - committing
        - expanding
      description: >-
        Filtra por um ou mais estágios de expansão. Consulte a base de
        conhecimento Sinais de Expansão para as definições dos estágios.
    expansion_momentum:
      type: array
      items:
        type: string
        enum:
          - advancing
          - steady
          - pulling_back
      example:
        - advancing
        - steady
      description: >-
        Trajetória pela qual filtrar. Somente `advancing`, `steady` e
        `pulling_back` são aceitos; os valores de `directions` em [Expansion
        Reference](/pt/api-reference/endpoint/expansions/types) existem apenas
        do lado da resposta.
    expansion_freshness:
      type: array
      items:
        type: string
        enum:
          - fresh
          - cooling
          - stale
          - cold
      example:
        - fresh
        - cooling
      description: >-
        Filtra pela recência da evidência: fresh (~30 dias), cooling (~30-60
        dias), stale (~60-90 dias), cold (>90 dias).
    expansion_scopes:
      type: array
      items:
        type: string
        enum:
          - entering_new_market
          - expanding_within_presence
          - established_only
      example:
        - entering_new_market
      description: Filtra pelo escopo de entrada no mercado.
    expansion_signal_type_slugs:
      type: array
      items:
        type: string
        enum:
          - AD
          - AUDIENCE
          - DNS
          - ENTITY
          - EVENT
          - EVENT_PLUS
          - EXEC
          - HIRE
          - INFRA
          - IP
          - NEWS
          - OFFICE
          - PARTNER
          - PRODUCT
          - REG
          - SCALE
          - TECH
      example:
        - EXEC
        - HIRE
      description: >-
        Filtra para tipos de sinal específicos. Consulte o catálogo de Tipos de
        Sinal na base de conhecimento para definições e níveis (`DNS` e `INFRA`
        são sinais de nível Premier).
    signal_strengths:
      type: array
      items:
        type: string
        enum:
          - low
          - medium
          - high
          - very_high
      example:
        - high
      description: >-
        Filtra por faixa de confiança da evidência: `low`, `medium` ou `high`.
        Note que isso é diferente do `signal_strength_slug` por sinal retornado
        nos registros de sinal (que varia de `low` a `very_high`); qualquer
        outro valor aqui não corresponde a nada.
    only_contraction:
      type: boolean
      example: false
      description: >-
        Quando verdadeiro, retorna apenas expansões marcadas como contração
        (empresas reduzindo suas operações).
    industries:
      type: array
      items:
        type: string
      example:
        - software
        - financial services
      description: Filtra pelo nome do setor (correspondência por texto livre).
    exclude_industries:
      type: array
      items:
        type: string
      example:
        - tobacco
      description: Setores a excluir (correspondência por texto livre).
    verticals:
      type: array
      items:
        type: integer
      description: >-
        Uma lista de `vertical_id` usada para buscar empresas em um vertical ou
        setor específico. Para encontrar o ID, chame o endpoint `vertical` na
        aba Filters.


        Este filtro suporta `is_enable_similarity_search`; uma vez habilitado,
        você pode inserir qualquer texto livre, por exemplo `["AI"]`.
    vertical_categories:
      type: array
      items:
        type: integer
      description: >-
        Uma lista de `vertical_category_id` usada para buscar empresas em uma
        categoria vertical específica. Para encontrar o ID, chame o endpoint
        `vertical category` na aba Filters.


        Este filtro suporta `is_enable_similarity_search`; uma vez habilitado,
        você pode inserir qualquer texto livre, por exemplo `["Information
        Technology"]`.
    vertical_sub_categories:
      type: array
      items:
        type: integer
      description: >-
        Uma lista de `vertical_sub_category_id` usada para buscar empresas em
        uma subcategoria vertical específica. Para encontrar o ID, chame o
        endpoint `vertical sub category` na aba Filters.


        Este filtro suporta `is_enable_similarity_search`; uma vez habilitado,
        você pode inserir qualquer texto livre, por exemplo `["Software"]`.
    technologies:
      type: array
      items:
        type: integer
      description: >-
        Uma lista de `tag_id` usada para buscar tecnologias específicas
        utilizadas pelas empresas. Para encontrar o ID, chame o endpoint
        `technology` na aba Filters.


        Este filtro suporta `is_enable_similarity_search`; uma vez habilitado,
        você pode inserir qualquer texto livre, por exemplo `["Shopify"]`.
    employees:
      type: array
      items:
        type: array
        items:
          type: string
      example:
        - - 1
          - 10
        - - 11
          - 20
        - - 10001
      description: >-
        O intervalo numérico de funcionários que trabalham na empresa. Isso
        permite encontrar empresas com base no número de funcionários. Você pode
        adicionar múltiplos intervalos para expandir os resultados da busca. 

         Consulte os endpoints de `company size` na aba Filters para mais informações.
    revenues:
      type: array
      items:
        type: integer
      example:
        - 0
        - 100000
      description: Intervalo mínimo e máximo da receita da empresa.
    founded_dates:
      type: array
      items:
        type: integer
      example:
        - 2018
        - 2024
      description: >-
        Intervalo de anos de fundação da empresa. O valor máximo de fundação é o
        ano atual.
    keywords:
      type: array
      items:
        type: string
      example:
        - ecommerce
        - ai
        - fintech
      description: >-
        Uma lista de palavras-chave para filtrar empresas por relevância,
        especialidades ou descrições.
    expansion_companies:
      type: array
      items:
        type: string
      example:
        - stripe.com
        - https://www.linkedin.com/company/airbnb
        - b7d92a56-31f8-4c0b-ae43-19c8e5f24b70
      description: >-
        Restringe a empresas específicas usando qualquer combinação de
        `domain_search_id`, domínio da empresa ou URL de perfil de rede social
        da empresa. Domínios e URLs são resolvidos para a empresa de melhor
        classificação.
    locations:
      type: array
      items:
        type: string
      example:
        - US
        - SG
        - CN
      description: >-
        O padrão ISO 3166-1 alpha-2 (cca2) é usado para filtrar localizações.
        Consulte os endpoints `location` na aba Filters para mais informações.
    job_exclude_locations:
      allOf:
        - $ref: '#/components/schemas/exclude_locations'
      description: >-
        Localizações geográficas a serem excluídas dos resultados de vagas de
        emprego.
    posted_dates:
      type: array
      items:
        type: string
      example:
        - '2025-01-01'
        - '2025-01-10'
      description: >-
        Intervalo de datas de publicação. O valor máximo é o dia atual. Os
        limites do dia seguem o fuso horário do seu workspace.
    people_titles:
      type: array
      items:
        type: string
      example:
        - sales manager
        - marketing manager
      description: |-
        Cargos associados aos indivíduos que você deseja localizar. 

         Os resultados também incluirão cargos que contenham terminologia semelhante, mesmo que não correspondam exatamente. Por exemplo, buscar por `software engineer` pode retornar resultados de indivíduos com o cargo `senior software engineer`.
    advertisement_target_locations:
      allOf:
        - $ref: '#/components/schemas/target_locations'
      description: Localizações geográficas alvo para anúncios.
    advertisement_exclude_target_locations:
      allOf:
        - $ref: '#/components/schemas/exclude_target_locations'
      description: Localizações geográficas a serem excluídas da segmentação de anúncios.
    advertisement_search_terms:
      type: array
      items:
        type: string
      example:
        - asus
      description: >-
        Palavras-chave usadas para buscar no conteúdo ou nos títulos dos
        anúncios.
    advertisement_start_dates:
      type: array
      items:
        type: string
        format: date
      example:
        - '2025-12-25'
        - '2025-12-25'
      description: Intervalo de data de início para filtragem de anúncios.
    advertisement_end_dates:
      type: array
      items:
        type: string
        format: date
      example:
        - '2025-12-25'
        - '2025-12-25'
      description: Intervalo de data de término para filtragem de anúncios.
    news_categories:
      type: array
      items:
        type: string
      example:
        - launches
      description: >-
        Lista de `category slugs` para buscar categorias de notícias
        específicas. Para encontrar um slug, chame o endpoint `news categories`
        na aba Filters.
    published_dates:
      type: array
      items:
        type: string
      example:
        - '2025-01-01'
        - '2025-01-10'
      description: >-
        Intervalo de datas de publicação. O valor máximo é o dia atual. Os
        limites do dia seguem o fuso horário do seu workspace.
    window_days:
      type: integer
      example: 90
      description: >-
        Opcional. Tamanho da janela móvel em dias. Usado quando um intervalo
        explícito de `transitioned_dates` não é fornecido; se ambos forem
        omitidos, uma janela padrão é usada.
    expansion_sort_by:
      type: string
      enum:
        - recent
        - expansion_score
        - signal_count
        - company_ranking
      example: expansion_score
      description: >-
        Ordenação dos resultados. Omita para a ordem de relevância padrão: pares
        corroborados primeiro (2 ou mais tipos de sinal distintos), depois pares
        com evidência repetida (3 ou mais sinais), depois o restante — os
        transicionados mais recentemente primeiro dentro de cada nível. `recent`
        — pura recência (transicionados mais recentemente primeiro).
        `expansion_score` — maior pontuação de expansão primeiro. `signal_count`
        — pares com mais sinais primeiro. `company_ranking` — classificação
        geral da empresa segundo a Pubrio (quanto menor, mais em destaque), em
        ordem crescente.
    expansion_is_include_metadata:
      type: boolean
      example: true
      description: >-
        As respostas com chave de API são enxutas por padrão. Defina como true
        para incluir o bloco completo de `metadata` (agregados, principais
        origens/destinos, principais setores, linha do tempo) e o detalhamento
        do modelo por empresa.
    page:
      type: integer
      example: 1
      default: 1
      description: >-
        Número da página, começando em 1. O teto é o `max_search_page` da sua
        assinatura (`max_company_search_page` para busca de empresas), retornado
        por [Profile](/pt/api-reference/endpoint/profile/profile). Excedê-lo
        retorna **HTTP 416**.
    per_page:
      type: integer
      example: 25
      default: 25
      maximum: 25
      description: >-
        Registros por página. O padrão é 25, que também é o teto na maioria dos
        planos — o limite é o `max_search_per_page` da sua assinatura, retornado
        por [Profile](/pt/api-reference/endpoint/profile/profile). Excedê-lo
        retorna **HTTP 416** com o código `41676` (ou `41613` na busca de
        empresas e pessoas), não um conjunto de resultados limitado.
    exclude_locations:
      type: array
      items:
        type: string
      example:
        - CN
        - US
        - RU
        - CA
      description: >-
        O padrão ISO 3166-1 alpha-2 (cca2) é usado para excluir localizações que
        não precisam ser retornadas. Consulte os endpoints `location` na aba
        Filters para mais informações.
    target_locations:
      type: array
      items:
        type: string
      example:
        - TW
        - AE
        - 'NO'
      description: >-
        Filtra anúncios para incluir aqueles direcionados a localizações
        específicas por código de país. Use isso para encontrar anúncios que
        estão sendo exibidos em países específicos. Combina-se com
        `filter_conditions` usando o operador OR - o anúncio deve ter como alvo
        pelo menos uma das localizações especificadas.
    exclude_target_locations:
      type: array
      items:
        type: string
      example:
        - IS
        - GB
        - FR
        - IE
        - ES
      description: >-
        Filtra anúncios para excluir aqueles direcionados a localizações
        específicas por código de país. Use isso para excluir anúncios que estão
        sendo exibidos em países específicos. Quando especificado em
        `filter_conditions` com o operador 'or', o anúncio não deve ter como
        alvo nenhuma das localizações excluídas.
  responses:
    general_error:
      description: >-
        Requisição inválida. A requisição estava malformada ou continha
        parâmetros inválidos. Verifique o código de erro e a mensagem para mais
        detalhes.
      content:
        application/json:
          schema:
            required:
              - code
              - message
              - details
            type: object
            properties:
              code:
                example: 40001
                type: integer
              message:
                example: >-
                  Os erros e códigos variam de acordo com o cenário; consulte a
                  documentação para mais informações.
                type: string
              details:
                type: object
    rate_limit_error:
      description: >-
        Limite de requisições excedido. Foram feitas requisições em excesso em
        um determinado período de tempo. Tente novamente após a janela do limite
        de requisições ser reiniciada.
      content:
        application/json:
          schema:
            required:
              - error
            type: object
            properties:
              error:
                example: >-
                  Limite de requisições excedido. Aguarde e tente novamente mais
                  tarde.
                type: string
    server_error:
      description: >-
        Erro interno do servidor. Ocorreu um erro inesperado no servidor. Entre
        em contato com o suporte caso o erro persista.
      content:
        application/json:
          schema:
            required:
              - error
            type: object
            properties:
              error:
                example: Ocorreu um erro inesperado no servidor.
                type: string
  securitySchemes:
    pubrio_api_key:
      type: apiKey
      name: pubrio-api-key
      description: >-
        Um token de API exclusivo que representa as ações que você realiza por
        meio da API e as permissões e operações correspondentes. Você pode
        criá-lo na seção
        [Configurações](https://dashboard.pubrio.com/#/settings/).
      in: header

````