> ## 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 vagas
> Encontre vagas abertas por empresa, cargo, função, senioridade, país e data de publicação — e leia a classificação que a Pubrio adiciona a cada vaga.
O [Job Search](/pt/api-reference/endpoint/companies/job_search) retorna vagas abertas capturadas pela Pubrio, uma linha por vaga, cada uma vinculada à empresa que a publicou. Cada linha carrega a vaga bruta (título, localização, URL, data de publicação) além de três campos que a Pubrio deriva do título: `functions`, `seniority_rank` e `location_id`.
```bash theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["stripe.com"],
"seniority_ranks": [4, 5],
"launch_dates": ["2026-08-01", "2026-08-31"],
"per_page": 25
}'
```
## Quando usar
* **Sinais de contratação para uma conta** — passe a empresa e veja para o que estão contratando, onde e em qual nível.
* **Prospecção por cargo** — busque em um país empresas abrindo vagas sênior de engenharia ou vendas, depois vá para [People Search](/pt/api-reference/endpoint/people/search) com o `domain_search_id` de cada linha.
* **Sincronização incremental** — faça polling com `created_at` definido como o timestamp de ingestão mais recente que você tem armazenado.
Se você quiser um total corrente em vez de linhas, use [Job Insights](/pt/api-reference/endpoint/companies/job_insights). Se você quiser ser avisado quando uma empresa publicar uma vaga, crie um [Monitor](/pt/developer-guides/examples/tracking-job-postings) com `signal_types: ["jobs"]`.
## Restringir a uma empresa
As buscas mais rápidas nomeiam a empresa. Os três identificadores resolvem para o mesmo registro e podem ser combinados:
| Chave | Valor | Observações |
| --------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| `domains` | `["stripe.com"]` | URLs como `https://www.stripe.com/jobs` são normalizadas para o domínio |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` | Apenas páginas de empresa |
| `companies` | `["5378845d-7726-4817-aba9-ced8c5f41dee"]` | `domain_search_id` de qualquer resposta anterior |
Buscas sem empresa são permitidas — `{"locations": ["SG"], "seniority_ranks": [5]}` funciona — mas contam contra o índice inteiro. `total_entries` então é uma estimativa, e `is_timeout` pode ser `true` em filtros muito amplos.
## Filtros
### Texto
| Chave | Tipo | Corresponde a |
| -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `titles` | `string[]` | Títulos de vagas. Correspondência em nível de palavra, então `["engineer"]` também retorna `Senior Software Engineer`. Qualquer título listado. |
| `search_term` | `string` | Texto livre contra o título da vaga. |
| `search_terms` | `string[]` | Vários termos de texto livre, qualquer um dos quais pode corresponder. |
### Classificação
| Chave | Tipo | Corresponde a |
| ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `functions` | `string[]` | Slugs de função derivados do título: `engineering`, `sales`, `marketing`, `finance`, `product_management`, … Qualquer slug listado. Veja [Funções de cargo](/pt/api-reference/enums#job-functions). |
| `seniority_ranks` | `integer[]` | `1` junior · `2` senior · `3` manager · `4` director · `5` executive. Veja [Níveis de senioridade](/pt/api-reference/enums#seniority-ranks). |
Os dois se comportam de forma diferente com entradas inválidas. Um slug desconhecido em `functions` retorna **zero** linhas. Um valor de `seniority_ranks` fora de 1–5 é **ignorado** e retorna todas as linhas. Nenhum dos dois gera um erro.
### Datas
| Chave | Tipo | Corresponde a |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `launch_dates` | `[from, to]` | A data de lançamento da vaga — `posting_date` quando o publicador fornece uma, caso contrário o dia em que a Pubrio a viu pela primeira vez. Limites de dia em UTC; concilia com o Job Insights, então **use este por padrão.** |
| `posted_dates` | `[from, to]` | Apenas `posting_date`. Os limites de dia seguem o fuso horário do seu workspace. |
| `created_at` | data ou timestamp ISO | Ingerida neste instante ou depois (UTC). Passe o `created_at` exato da sua linha armazenada mais recente para polling incremental. |
Ambas as janelas são inclusivas. `launch_dates` com um único elemento corresponde àquele dia específico.
### Localização
| Chave | Tipo | Corresponde a |
| ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locations` | `string[]` | País da vaga, ISO alpha-2. |
| `exclude_locations` | `string[]` | País da vaga a excluir. |
| `location_ids` | `integer[]` | País da vaga pelo `location_id` da Pubrio, os mesmos números que o endpoint [Locations](/pt/api-reference/endpoint/locations/locations) e o `location_id` de cada linha carregam. |
| `company_locations` | `string[]` | País da **sede da empresa**, que pode ser diferente de onde a vaga está localizada. |
### Paginação e ordem
| Chave | Padrão | Observações |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `per_page` | 25 | Limitado pelo `max_search_per_page` do seu plano. |
| `page` | 1 | Limitado por `max_search_page`; o `total_display_pages` da resposta informa o limite. |
| `is_ascending_order` | `false` | As linhas são ordenadas por `created_at`, das mais recentes para as mais antigas. `true` inverte para as mais antigas primeiro. |
## Como é uma linha
```json theme={null}
{
"job_id": "4418496a-6a4f-4432-8910-50153e9ba27c",
"job_search_id": "4418496a-6a4f-4432-8910-50153e9ba27c",
"created_at": "2026-08-30T00:02:52.531Z",
"last_modified": "2026-09-01T16:08:09.324Z",
"title": "Finance and Strategy Partner",
"job_url": "https://www.linkedin.com/jobs/view/4460586030",
"location": "United States",
"location_id": 357,
"country": "United States",
"country_code": "US",
"posting_date": "2026-08-29",
"source_type": "linkedin",
"functions": ["consulting"],
"seniority_rank": 5,
"base_salary": null,
"experience_requirement": null,
"education_requirement": null,
"employment_type": null,
"companies": {
"domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
"company_name": "Stripe",
"linkedin_name": "stripe",
"country_code": "US",
"company_url": "https://stripe.com/",
"domain": "stripe.com",
"logo_url": "https://buckets.pubrio.com/company-logo/....jpg"
}
}
```
* `functions` é `null` e `seniority_rank` é `0` quando o título não pôde ser classificado. Filtre por eles mesmo assim — linhas não classificadas simplesmente não correspondem.
* `posting_date` é a data do publicador; `created_at` é quando a Pubrio viu a vaga pela primeira vez e é a chave de ordenação padrão.
* `job_id` e `job_search_id` são o mesmo valor; passe qualquer um deles para [Job Lookup](/pt/api-reference/endpoint/companies/job_lookup).
### Leia `metadata` antes de confiar em um resultado
```json theme={null}
"metadata": {
"profile": null,
"filters": { "domains": ["stripe.com"], "seniority_ranks": [4, 5], "per_page": 25, "language": "en" },
"ignored_fields": []
}
```
`ignored_fields` lista qualquer chave do corpo que o endpoint não reconheceu. Um erro de digitação como `"seniorty_ranks"` não falha a requisição — ele silenciosamente a amplia. Verifique se esse array está vazio em qualquer coisa automatizada.
## Receitas
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["stripe.com", "adyen.com", "checkout.com"],
"functions": ["engineering", "data_science"],
"seniority_ranks": [3, 4, 5],
"launch_dates": ["2026-08-05", "2026-09-04"],
"per_page": 25
}'
```
```python Python theme={null}
import os, requests
r = requests.post(
"https://api.pubrio.com/companies/jobs/search",
headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"], "Content-Type": "application/json"},
json={
"domains": ["stripe.com", "adyen.com", "checkout.com"],
"functions": ["engineering", "data_science"],
"seniority_ranks": [3, 4, 5],
"launch_dates": ["2026-08-05", "2026-09-04"],
"per_page": 25,
},
)
body = r.json()
assert body["metadata"]["ignored_fields"] == []
for job in body["data"]["jobs"]:
print(job["companies"]["company_name"], "-", job["title"], job["seniority_rank"])
```
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"locations": ["SG"],
"functions": ["sales", "business_development"],
"seniority_ranks": [4, 5],
"launch_dates": ["2026-08-01", "2026-09-04"],
"per_page": 25
}'
```
Agrupe as linhas por `companies.domain_search_id` — cada empresa distinta é um prospect, e o id vai direto para `companies` no [People Search](/pt/api-reference/endpoint/people/search).
```python Python theme={null}
import os, requests
API = "https://api.pubrio.com/companies/jobs/search"
HEADERS = {"pubrio-api-key": os.environ["PUBRIO_API_KEY"]}
def sync(domains, since):
"""Fetch every posting ingested at or after `since` (ISO timestamp). Returns the new cursor."""
newest = since
page = 1
while True:
body = requests.post(API, headers=HEADERS, json={
"domains": domains, "created_at": since, "page": page, "per_page": 25,
}).json()
rows = body["data"]["jobs"]
if not rows:
break
for job in rows: # newest first
newest = max(newest, job["created_at"])
print(job["job_id"], job["title"]) # upsert into your store here
if page >= body["data"]["pagination"]["total_display_pages"]:
break
page += 1
return newest
cursor = sync(["stripe.com"], "2026-09-01T00:00:00Z")
# persist `cursor` and pass it as `since` on the next run
```
O cursor é o `created_at` completo da linha mais recente que você armazenou, então apenas essa linha é reentregue na próxima execução. Faça upsert por `job_id`. As linhas chegam das mais recentes para as mais antigas, então um dia movimentado nunca empurra o cursor além do limite de páginas do seu plano.
## Relacionados
Todos os parâmetros e campos de resposta.
Contagens por função, senioridade, país e semana para uma empresa.
Níveis de senioridade e o vocabulário completo de funções de cargo.
Receba um webhook em vez de fazer polling.