> ## 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.
# Job Search
> Encuentra publicaciones de empleo abiertas por empresa, cargo, función, seniority, país y fecha de lanzamiento — y lee la clasificación que Pubrio agrega a cada publicación.
[Job Search](/es/api-reference/endpoint/companies/job_search) devuelve publicaciones de empleo abiertas que Pubrio ha capturado, una fila por publicación, cada una vinculada a la empresa que la publicó. Cada fila incluye la publicación original (título, ubicación, URL, fecha de publicación) más tres campos que Pubrio deriva del título: `functions`, `seniority_rank` y `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
}'
```
## Cuándo usarlo
* **Señales de contratación para una cuenta** — pasa la empresa y lee para qué están contratando, dónde y en qué nivel.
* **Prospección por rol** — busca en un país empresas que están abriendo roles senior de ingeniería o ventas, y luego salta a [People Search](/es/api-reference/endpoint/people/search) con el `domain_search_id` de cada fila.
* **Sincronización incremental** — consulta con `created_at` configurado en el momento de ingestión más reciente que tengas almacenado.
Si quieres un conteo acumulado en lugar de filas, usa [Job Insights](/es/api-reference/endpoint/companies/job_insights). Si quieres que te avisen cuando una empresa publica un empleo, crea un [Monitor](/es/developer-guides/examples/tracking-job-postings) con `signal_types: ["jobs"]`.
## Acotar a una empresa
Las búsquedas más rápidas nombran a la empresa. Los tres identificadores se resuelven al mismo registro y pueden combinarse:
| Clave | Valor | Notas |
| --------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| `domains` | `["stripe.com"]` | URLs como `https://www.stripe.com/jobs` se normalizan al dominio |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` | Solo páginas de empresa |
| `companies` | `["5378845d-7726-4817-aba9-ced8c5f41dee"]` | `domain_search_id` de cualquier respuesta anterior |
Se permiten las búsquedas sin empresa — `{"locations": ["SG"], "seniority_ranks": [5]}` funciona — pero cuentan contra todo el índice. `total_entries` es entonces una estimación y `is_timeout` puede ser `true` en filtros muy amplios.
## Filtros
### Texto
| Clave | Tipo | Coincide con |
| -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `titles` | `string[]` | Cargos del empleo. Coincidencia a nivel de palabra, por lo que `["engineer"]` también devuelve `Senior Software Engineer`. Cualquiera de los títulos listados. |
| `search_term` | `string` | Texto libre contra el título de la publicación. |
| `search_terms` | `string[]` | Varios términos de texto libre, cualquiera de los cuales puede coincidir. |
### Clasificación
| Clave | Tipo | Coincide con |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `functions` | `string[]` | Slugs de función derivados del título: `engineering`, `sales`, `marketing`, `finance`, `product_management`, … Cualquiera de los slugs listados. Consulta [Funciones de empleo](/es/api-reference/enums#job-functions). |
| `seniority_ranks` | `integer[]` | `1` junior · `2` senior · `3` manager · `4` director · `5` executive. Consulta [Niveles de seniority](/es/api-reference/enums#seniority-ranks). |
Ambos se comportan de forma distinta ante una entrada incorrecta. Un slug de `functions` desconocido devuelve **cero** filas. Un valor de `seniority_ranks` fuera del rango 1–5 se **ignora** y devuelve todas las filas. Ninguno produce un error.
### Fechas
| Clave | Tipo | Coincide con |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `launch_dates` | `[from, to]` | La fecha de lanzamiento de la publicación — `posting_date` cuando el publicador la proporciona, de lo contrario el día en que Pubrio la vio por primera vez. Límites de día en UTC; se concilia con Job Insights, así que **úsalo por defecto.** |
| `posted_dates` | `[from, to]` | Solo `posting_date`. Los límites de día siguen la zona horaria de tu workspace. |
| `created_at` | fecha o timestamp ISO | Ingerido en o después de este instante (UTC). Pasa el `created_at` exacto de tu fila almacenada más reciente para sondeo incremental. |
Ambas ventanas son inclusivas. `launch_dates` con un solo elemento coincide con ese único día.
### Ubicación
| Clave | Tipo | Coincide con |
| ------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locations` | `string[]` | País de la publicación, ISO alfa-2. |
| `exclude_locations` | `string[]` | País de la publicación a excluir. |
| `location_ids` | `integer[]` | País de la publicación por `location_id` de Pubrio, los mismos números que lleva el endpoint [Locations](/es/api-reference/endpoint/locations/locations) y el `location_id` de cada fila. |
| `company_locations` | `string[]` | País de la **sede de la empresa**, que puede diferir de dónde está el empleo. |
### Paginación y orden
| Clave | Por defecto | Notas |
| -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `per_page` | 25 | Limitado por el `max_search_per_page` de tu plan. |
| `page` | 1 | Limitado por `max_search_page`; el `total_display_pages` de la respuesta indica el tope. |
| `is_ascending_order` | `false` | Las filas se ordenan por `created_at`, las más recientes primero. `true` invierte el orden a las más antiguas primero. |
## Cómo se ve una fila
```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` es `null` y `seniority_rank` es `0` cuando el título no se pudo clasificar. Filtra por ellos de todas formas — las filas no clasificadas simplemente no coinciden.
* `posting_date` es la fecha del publicador; `created_at` es cuándo Pubrio vio la publicación por primera vez y es la clave de orden por defecto.
* `job_id` y `job_search_id` son el mismo valor; pasa cualquiera de los dos a [Job Lookup](/es/api-reference/endpoint/companies/job_lookup).
### Lee `metadata` antes de confiar en un 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 cualquier clave del cuerpo que el endpoint no reconoció. Un error tipográfico como `"seniorty_ranks"` no hace fallar la solicitud — la amplía silenciosamente. Verifica que este array esté vacío en cualquier flujo automatizado.
## Recetas
```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
}'
```
Agrupa las filas por `companies.domain_search_id` — cada empresa distinta es un prospecto, y el id va directo al campo `companies` de [People Search](/es/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):
"""Obtiene cada publicación ingerida en o después de `since` (timestamp ISO). Devuelve el nuevo 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: # más recientes primero
newest = max(newest, job["created_at"])
print(job["job_id"], job["title"]) # inserta o actualiza en tu almacén aquí
if page >= body["data"]["pagination"]["total_display_pages"]:
break
page += 1
return newest
cursor = sync(["stripe.com"], "2026-09-01T00:00:00Z")
# conserva `cursor` y pásalo como `since` en la siguiente ejecución
```
El cursor es el `created_at` completo de la fila más reciente que almacenaste, por lo que solo esa fila se vuelve a entregar en la siguiente ejecución. Inserta o actualiza usando `job_id`. Las filas llegan de más recientes a más antiguas, así que un día con mucha actividad nunca empuja el cursor más allá del tope de páginas de tu plan.
## Relacionado
Todos los parámetros y campos de respuesta.
Conteos por función, seniority, país y semana para una empresa.
Niveles de seniority y el vocabulario completo de funciones de empleo.
Obtén un webhook en lugar de hacer polling.