> ## Documentation Index > Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Búsqueda de personas > Encuentra personas por cargo, nivel de seniority, ubicación o empleador. También puedes enriquecer el perfil de una persona conocida o encontrar su correo electrónico profesional. Elige una acción y proporciona sus campos obligatorios a continuación. Cada acción devuelve `output` normalizado. La salida nativa del proveedor no se repite allí; permanece en el Run y se puede leer con [Get Run](https://glasser.ai/docs/es/api-reference/runs/get.md). `search` devuelve `total_matches` y `output.items[]`, una fila por persona. `enrich` y `find_email` devuelven una persona con los mismos campos en el nivel superior. Un valor que el proveedor seleccionado no informa es `null`; Glasser no lo completa. Lee `result_status` por separado de `status`: `success`, `no_result`, `error` o `pending`. Una respuesta vacía pero válida es `no_result` y conserva la estructura de la acción: cada campo es `null`, o `items` es `[]`. `find_email` sin un correo electrónico es `no_result`. `charge_usd` totaliza el `runs` de esta respuesta y es nulo hasta que todos los Runs se resuelvan. Con `provider: auto`, el fallback puede crear varios Runs, cada uno enumerado en `runs[]` con su propio cargo. Consulta [Selección de proveedores y cargos](https://glasser.ai/docs/es/api-reference/solutions/overview.md#how-provider-selection-works). ## Salida por acción Cada campo está presente en cada fila; un valor que el proveedor no informa es `null`. Los campos siguen las [convenciones de los campos](https://glasser.ai/docs/es/api-reference/solutions/overview.md#field-conventions). | `action` | `output` | | - | - | | `search` | `total_matches`, `items[]`: una persona por fila | | `enrich` | una persona | | `find_email` | una persona | Una persona tiene estos campos: name, first\_name, last\_name, job\_title, seniority, department, headline, linkedin\_url, city, region, country, country\_code, email, email\_status, email\_catch\_all, email\_source, phone, company\_name, company\_domain, company\_linkedin\_url, apollo\_match\_confidence, pdl\_likelihood, hunter\_email\_score, zoominfo\_accuracy\_score. * Los nombres, cargos y etiquetas son los que informa el proveedor. Los nombres de PDL están en minúsculas. `name` es `null` cuando el proveedor proporciona solo el nombre y el apellido; Glasser no los concatena. La búsqueda de Apollo oculta el apellido, por lo que `last_name` es `null`. * `seniority` y `department` son etiquetas del vocabulario propio del proveedor que responde (por ejemplo, Apollo `founder`, PDL `cxo`, LeadMagic `C-Team`). No son los valores `seniorities` de la solicitud y no son comparables entre proveedores. * `email` es la dirección que el proveedor proporciona como correo electrónico laboral. PDL solo la completa a partir de `work_email`; sus otras direcciones permanecen en el Run. Las filas de búsqueda de Apollo, ZoomInfo y LeadMagic no tienen correo electrónico. * `email_status` es la etiqueta de verificación propia del proveedor (`verified`, `VERIFIED`, `valid`). Los proveedores verifican de distintas maneras, así que no compares las etiquetas. Léelas junto con `email_catch_all` (el dominio acepta todas las direcciones, por lo que una comprobación del buzón no puede confirmar esta) y `email_source` (Hunter: `found` en la web, o `generated` a partir del patrón de direcciones del dominio). Hunter cobra por una dirección generada. * `total_matches` cuenta las coincidencias en todo el conjunto de datos del proveedor, no solo en esta página. Es `null` para LeadMagic, que proporciona únicamente el recuento de la página. * Las puntuaciones del modelo propio de un proveedor llevan su nombre y son `null` para los demás: `apollo_match_confidence` (alta, media, baja, ninguna), `pdl_likelihood` (1–10), `hunter_email_score` (0–100), `zoominfo_accuracy_score` (0–100). ```json { "action": "find_email", "provider": "hunter", "status": "COMPLETED", "result_status": "success", "output": { "name": null, "first_name": "Avery", "last_name": "Example", "job_title": null, "email": "example@stripe.com", "email_status": "valid", "email_catch_all": true, "email_source": "generated", "company_name": "Stripe", "company_domain": "stripe.com", "hunter_email_score": 80, "…": "other fields null" }, "charge_usd": "0.0245", "runs": [{ "provider": "hunter", "status": "COMPLETED", "charge_usd": "0.0245" }], "result_url": "/v1/solutions/gtm/people_search/result?token=…" } ``` ## Filtros * PDL hace coincidir `job_titles` exactamente como se proporciona, por lo que "CTO" no coincide con "Co-founder & CTO". Hace coincidir `locations` como subcadena, por lo que "london" también coincide con "new london, connecticut". * ZoomInfo no tiene un nivel `founder`, `owner`, `partner`, `head`, `entry` o `intern`, así que, con `auto`, esas solicitudes omiten ZoomInfo. El nivel `senior` de ZoomInfo es todo su nivel "Non Manager", que también incluye colaboradores individuales junior. * La búsqueda de Hunter enumera únicamente las direcciones personales en `company_domain`, no buzones de función como info\@. El enriquecimiento de Prospeo solo devuelve personas para las que tiene un correo electrónico laboral verificado. find\_email mediante Apollo también acepta `linkedin_url` por sí solo; una coincidencia de Apollo sin un correo electrónico real no cuenta como coincidencia y no se cobra. ## OpenAPI ````yaml /openapi.es.json post /v1/solutions/gtm/people_search openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: >- Una API Key, sin contrato, con pago por llamada, para APIs de pago adquiridas al por mayor. Cada respuesta incluye x-request-id; cada cuerpo de error incluye el mismo sobre. servers: - url: https://api.glasser.ai security: [] tags: - name: Solutions - name: Endpoints - name: Runs - name: Balance paths: /v1/solutions/gtm/people_search: post: tags: - Solutions summary: Búsqueda de personas description: >- Encuentre personas por cargo, nivel de seniority, ubicación o empleador. También puede enriquecer el perfil de una persona conocida, encontrar su correo electrónico laboral, verificar de forma independiente un buzón, consultar perfiles de empleados y sus cargos reales en una empresa, o encontrar un número móvil a partir de un perfil de LinkedIn, un correo electrónico o el nombre y empleador cuando sea compatible. Elija una acción y proporcione a continuación los campos obligatorios. Cada acción devuelve resultados normalizados con el id, el proveedor de datos y el estado del ciclo de vida del último Run: search y list_employees proporcionan total_matches y output.items[] con personas; enrich, find_email y find_phone proporcionan una persona con los mismos campos en el nivel superior; verify_email proporciona un veredicto del buzón con el estado y las marcas nativos del proveedor de datos. Los veredictos invalid, catch-all, disposable y unknown son resultados de verificación válidos, no búsquedas sin coincidencias. El resultado nativo del proveedor de datos no se repite en output; permanece en el Run y puede leerse con GET /v1/runs/:id. Un valor que el proveedor de datos seleccionado no informe es null. Lea result_status por separado de status: success, no_result, error o pending. charge_usd es el cargo total de los Runs de esta respuesta y es null hasta que todos los Runs indicados se hayan completado; runs[] incluye el cargo de cada Run. provider=auto selecciona el primer proveedor de datos elegible y prueba el siguiente solo ante PROVIDER_ERROR, TIMED_OUT o un 503 durante la admisión; un proveedor de datos indicado por nombre nunca hace fallback. Reutilice la misma Idempotency-Key y los mismos parámetros de ejecución para un reintento intencionado. operationId: gtm-people-search parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- Genere un valor único para cada ejecución prevista (se recomienda un UUID). Reintente con la misma clave y los mismos parámetros de ejecución para recuperar el Run original sin un segundo cargo. Cambiar los parámetros de ejecución con la misma clave devuelve 409; cambiar task_id o metadata no actualiza el Run original. required: true requestBody: content: application/json: schema: type: object properties: action: anyOf: - type: string enum: - search - list_employees - enrich - find_email - verify_email - find_phone description: >- Predeterminado: search. - search: proporcione al menos uno de job_titles, seniorities, locations, company_domain o keywords. Las filas de Apollo y ZoomInfo no incluyen correo electrónico ni teléfono; las filas de PDL son registros completos; Hunter enumera las direcciones personales de company_domain. - list_employees: proporcione company_domain. Lea hasta 100 perfiles de empleados y sus cargos reales desde LeadMagic; es una muestra, no un listado completo de la empresa. No se aplican filtros de cargo ni ubicación. - enrich: proporcione linkedin_url, email o full_name más company_domain. Prospeo solo devuelve personas para las que tiene un correo electrónico laboral verificado. - find_email: proporcione full_name y company_domain. Apollo también acepta únicamente linkedin_url; una coincidencia de Apollo sin un correo electrónico real no cuenta como coincidencia y no se cobra. - verify_email: proporcione email. Los veredictos invalid, catch-all, disposable y unknown son respuestas correctas, no resultados inexistentes. Use completed_at del Run final como hora de comprobación. - find_phone: LeadMagic requiere linkedin_url; Prospeo también acepta email, o full_name más company_domain. Encuentra un número móvil; no envía mensajes ni realiza llamadas. Los filtros nunca se descartan silenciosamente. Con auto, se omiten los proveedores de datos que no puedan aplicarlos; un proveedor de datos indicado por nombre que no pueda aplicarlos devuelve 400. - type: 'null' provider: anyOf: - type: string enum: - auto - apollo - pdl - leadmagic - zoominfo - hunter - prospeo description: >- Predeterminado auto: selecciona el primer proveedor de datos elegible según el orden de preferencia de Glasser. Un proveedor de datos indicado por nombre debe admitir la solicitud y estar permitido por su Key; no hace fallback a otro proveedor de datos. Los valores disponibles se indican a continuación. - type: 'null' job_titles: anyOf: - type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 20 description: >- Cargos que deben coincidir. PDL compara cada cargo exactamente como se proporciona, por lo que 'CTO' no coincide con 'Co-founder & CTO'. - type: 'null' seniorities: anyOf: - type: array items: type: string enum: - owner - founder - c_suite - partner - vp - head - director - manager - senior - entry - intern minItems: 1 maxItems: 11 description: >- Niveles de seniority, uno o más de owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Un proveedor de datos sin un nivel coincidente devuelve 400 cuando se indica por nombre y se omite con auto. ZoomInfo no tiene los niveles founder, owner, partner, head, entry ni intern; su nivel senior abarca todo el nivel Non Manager, que también incluye a colaboradores individuales junior. - type: 'null' locations: anyOf: - type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 20 description: >- Ubicaciones como texto libre. PDL compara cada una como una subcadena del nombre de la ubicación de la persona, por lo que 'london' también coincide con 'new london, connecticut'. - type: 'null' company_domain: anyOf: - type: string minLength: 3 maxLength: 253 description: >- Un dominio web como stripe.com. Se acepta una URL completa y se reduce a su host. - type: 'null' keywords: anyOf: - type: string minLength: 1 maxLength: 300 - type: 'null' full_name: anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' email: anyOf: - type: string maxLength: 320 pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$ description: Una dirección de correo electrónico. - type: 'null' linkedin_url: anyOf: - type: string maxLength: 2048 pattern: linkedin\.com\/in\/[^/?#\s]+ description: >- La URL del perfil de LinkedIn de la persona, `linkedin.com/in/`. No es una página de empresa. - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: >- Filas que se devolverán. Mantenga este valor bajo: la regla de cargo del Endpoint enrutado puede leerlo. Cada capacidad lo limita aún más. - type: 'null' task_id: anyOf: - type: string description: >- Agrupe Runs relacionados, incluido el fallback automático, bajo un mismo Task. Reutilice una cadena estable y filtre la lista de Runs por task para recuperarlos. - type: 'null' metadata: anyOf: - anyOf: - type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ - {} description: >- Campos de seguimiento opcionales, devueltos en el Run y disponibles como filtros. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de su End user, nunca su dirección de correo electrónico ni su nombre. Las entradas no válidas se descartan por completo, sin truncarlas. La solicitud continúa y el Run devuelve los campos almacenados. - type: 'null' additionalProperties: false required: true responses: '200': description: Success content: application/json: schema: anyOf: - $ref: '#/components/schemas/PeopleSearchResult' '202': description: Success content: application/json: schema: anyOf: - $ref: '#/components/schemas/PeopleSearchResult' '400': description: ValidationFailed | IdempotencyKeyRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationFailedEncoded' - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded' - $ref: '#/components/schemas/ValidationFailedEncoded' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedEncoded' '402': description: InsufficientBalance content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: EndpointNotPermitted | Forbidden content: application/json: schema: anyOf: - $ref: '#/components/schemas/EndpointNotPermittedEncoded' - $ref: '#/components/schemas/ForbiddenEncoded' '409': description: IdempotencyConflict content: application/json: schema: $ref: '#/components/schemas/IdempotencyConflictEncoded' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimitedEncoded' '503': description: ServiceUnavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableEncoded' security: - bearer: [] components: schemas: PeopleSearchResult: type: object properties: id: type: string run_url: type: string description: Abre este Run en la consola. Requiere pertenencia a un Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED o RUNNING: aún está en curso. COMPLETED: hay una respuesta del proveedor de datos, incluidas las respuestas que no son 2xx. FAILED: consulta `failure`. STOPPED: detenido antes del envío. Lee charge_usd por separado del estado. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: >- Motivo por el que falló el Run. No es null solo cuando el estado es FAILED. input: type: object output: anyOf: - anyOf: - type: object properties: total_matches: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Personas que coinciden con los filtros en todo el conjunto de datos del proveedor de datos, no solo en esta página. Es null cuando el proveedor de datos solo proporciona el recuento de la página (LeadMagic). items: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' description: >- Nombre completo exactamente como lo proporciona el proveedor de datos (PDL lo escribe en minúsculas). Es null cuando el proveedor de datos solo proporciona el nombre y el apellido; nunca se combinan. first_name: anyOf: - type: string - type: 'null' description: >- Nombre tal como lo proporciona el proveedor de datos. last_name: anyOf: - type: string - type: 'null' description: >- Apellido tal como lo proporciona el proveedor de datos. Es null cuando el proveedor de datos lo oculta (búsqueda de Apollo). job_title: anyOf: - type: string - type: 'null' description: >- Puesto actual tal como lo proporciona el proveedor de datos. seniority: anyOf: - type: string - type: 'null' description: >- Etiqueta de seniority según el vocabulario propio del proveedor de datos que responde (Apollo founder, PDL cxo, LeadMagic C-Team, Hunter executive). No corresponde al vocabulario de seniorities de la solicitud ni es comparable entre proveedores de datos; consulta provider. Cuando el proveedor de datos incluye varios valores, se muestra el primero. department: anyOf: - type: string - type: 'null' description: >- Departamento o función laboral según el vocabulario propio del proveedor de datos que responde. Cuando el proveedor de datos incluye varios valores, se muestra el primero. headline: anyOf: - type: string - type: 'null' description: >- Titular del perfil (la línea del puesto de LinkedIn). linkedin_url: anyOf: - type: string - type: 'null' description: >- URL del perfil de LinkedIn. Se añade https:// cuando el proveedor de datos omite el esquema. city: anyOf: - type: string - type: 'null' description: Ciudad de la ubicación de la persona. region: anyOf: - type: string - type: 'null' description: Estado o región de la ubicación de la persona. country: anyOf: - type: string - type: 'null' description: >- País de la ubicación de la persona como nombre para mostrar en inglés (nunca como código). country_code: anyOf: - type: string - type: 'null' description: >- País de la ubicación de la persona como código ISO 3166-1 alpha-2. email: anyOf: - type: string - type: 'null' description: >- Correo electrónico laboral tal como lo proporciona el proveedor de datos. PDL: solo work_email; las demás direcciones se conservan en el Run. email_status: anyOf: - type: string - type: 'null' description: >- Etiqueta de verificación del correo electrónico propia del proveedor de datos que responde (Apollo verified, Prospeo VERIFIED, Hunter y LeadMagic valid). Los proveedores de datos verifican de forma diferente, por lo que las etiquetas no son comparables; léela junto con email_catch_all y email_source. email_catch_all: anyOf: - type: boolean - type: 'null' description: >- True cuando el proveedor de datos indica que el dominio del correo electrónico acepta todas las direcciones, por lo que una comprobación del buzón no puede confirmar esta dirección (Hunter accept_all, Apollo email_domain_catchall). email_source: anyOf: - type: string - type: 'null' description: >- Cómo obtuvo Hunter el correo electrónico: found (visto en la web) o generated (creado a partir del patrón de direcciones del dominio). Es null para otros proveedores de datos. phone: anyOf: - type: string - type: 'null' description: >- Número de teléfono tal como lo proporciona el proveedor de datos. Se omiten los números enmascarados. company_name: anyOf: - type: string - type: 'null' description: >- Empleador actual tal como lo proporciona el proveedor de datos. company_domain: anyOf: - type: string - type: 'null' description: >- Dominio del empleador actual (hostname sin www. ni puerto). company_linkedin_url: anyOf: - type: string - type: 'null' description: >- URL de la página de empresa del empleador actual en LinkedIn. apollo_match_confidence: anyOf: - type: string - type: 'null' description: >- Nivel de confianza de Apollo en que el registro coincide con los datos de entrada: high, medium, low o none. Es null para otros proveedores de datos. pdl_likelihood: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Puntuación de 1 a 10 de People Data Labs sobre el grado de coincidencia del registro con los datos de entrada. Es null para otros proveedores de datos. hunter_email_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Confianza de Hunter de 0 a 100 en el correo electrónico (puntuación de email-finder, confianza de la búsqueda de dominio). Es null para otros proveedores de datos. zoominfo_accuracy_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Puntuación de precisión del contacto de ZoomInfo, de 0 a 100. Es null para otros proveedores de datos. required: - name - first_name - last_name - job_title - seniority - department - headline - linkedin_url - city - region - country - country_code - email - email_status - email_catch_all - email_source - phone - company_name - company_domain - company_linkedin_url - apollo_match_confidence - pdl_likelihood - hunter_email_score - zoominfo_accuracy_score additionalProperties: false required: - total_matches - items additionalProperties: false - type: object properties: email: anyOf: - type: string - type: 'null' description: >- Dirección de correo electrónico devuelta por el proveedor de datos. email_status: anyOf: - type: string - type: 'null' description: >- Veredicto propio del proveedor de datos sobre la entregabilidad. Las direcciones con estado unknown y catch-all no se consideran direcciones verificadas como entregables. email_catch_all: anyOf: - type: boolean - type: 'null' description: >- Indica si el proveedor de datos informa de un dominio catch-all. email_disposable: anyOf: - type: boolean - type: 'null' description: >- Indica si el proveedor de datos informa de una dirección desechable. email_webmail: anyOf: - type: boolean - type: 'null' description: >- Indica si el proveedor de datos informa de una dirección de correo web gratuita. hunter_email_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Puntuación de confianza propia de Hunter, de 0 a 100; es null para otros proveedores de datos. required: - email - email_status - email_catch_all - email_disposable - email_webmail - hunter_email_score additionalProperties: false - type: object properties: name: anyOf: - type: string - type: 'null' description: >- Nombre completo exactamente como lo proporciona el proveedor de datos (PDL lo escribe en minúsculas). Es null cuando el proveedor de datos solo proporciona el nombre y el apellido; nunca se combinan. first_name: anyOf: - type: string - type: 'null' description: Nombre tal como lo proporciona el proveedor de datos. last_name: anyOf: - type: string - type: 'null' description: >- Apellido tal como lo proporciona el proveedor de datos. Es null cuando el proveedor de datos lo oculta (búsqueda de Apollo). job_title: anyOf: - type: string - type: 'null' description: >- Puesto actual tal como lo proporciona el proveedor de datos. seniority: anyOf: - type: string - type: 'null' description: >- Etiqueta de seniority según el vocabulario propio del proveedor de datos que responde (Apollo founder, PDL cxo, LeadMagic C-Team, Hunter executive). No corresponde al vocabulario de seniorities de la solicitud ni es comparable entre proveedores de datos; consulta provider. Cuando el proveedor de datos incluye varios valores, se muestra el primero. department: anyOf: - type: string - type: 'null' description: >- Departamento o función laboral según el vocabulario propio del proveedor de datos que responde. Cuando el proveedor de datos incluye varios valores, se muestra el primero. headline: anyOf: - type: string - type: 'null' description: Titular del perfil (la línea del puesto de LinkedIn). linkedin_url: anyOf: - type: string - type: 'null' description: >- URL del perfil de LinkedIn. Se añade https:// cuando el proveedor de datos omite el esquema. city: anyOf: - type: string - type: 'null' description: Ciudad de la ubicación de la persona. region: anyOf: - type: string - type: 'null' description: Estado o región de la ubicación de la persona. country: anyOf: - type: string - type: 'null' description: >- País de la ubicación de la persona como nombre para mostrar en inglés (nunca como código). country_code: anyOf: - type: string - type: 'null' description: >- País de la ubicación de la persona como código ISO 3166-1 alpha-2. email: anyOf: - type: string - type: 'null' description: >- Correo electrónico laboral tal como lo proporciona el proveedor de datos. PDL: solo work_email; las demás direcciones se conservan en el Run. email_status: anyOf: - type: string - type: 'null' description: >- Etiqueta de verificación del correo electrónico propia del proveedor de datos que responde (Apollo verified, Prospeo VERIFIED, Hunter y LeadMagic valid). Los proveedores de datos verifican de forma diferente, por lo que las etiquetas no son comparables; léela junto con email_catch_all y email_source. email_catch_all: anyOf: - type: boolean - type: 'null' description: >- True cuando el proveedor de datos indica que el dominio del correo electrónico acepta todas las direcciones, por lo que una comprobación del buzón no puede confirmar esta dirección (Hunter accept_all, Apollo email_domain_catchall). email_source: anyOf: - type: string - type: 'null' description: >- Cómo obtuvo Hunter el correo electrónico: found (visto en la web) o generated (creado a partir del patrón de direcciones del dominio). Es null para otros proveedores de datos. phone: anyOf: - type: string - type: 'null' description: >- Número de teléfono tal como lo proporciona el proveedor de datos. Se omiten los números enmascarados. company_name: anyOf: - type: string - type: 'null' description: >- Empleador actual tal como lo proporciona el proveedor de datos. company_domain: anyOf: - type: string - type: 'null' description: >- Dominio del empleador actual (hostname sin www. ni puerto). company_linkedin_url: anyOf: - type: string - type: 'null' description: >- URL de la página de empresa del empleador actual en LinkedIn. apollo_match_confidence: anyOf: - type: string - type: 'null' description: >- Nivel de confianza de Apollo en que el registro coincide con los datos de entrada: high, medium, low o none. Es null para otros proveedores de datos. pdl_likelihood: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Puntuación de 1 a 10 de People Data Labs sobre el grado de coincidencia del registro con los datos de entrada. Es null para otros proveedores de datos. hunter_email_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Confianza de 0 a 100 de Hunter en el correo electrónico (puntuación de email-finder, confianza de domain-search). Es null para otros proveedores de datos. zoominfo_accuracy_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Puntuación de precisión del contacto de ZoomInfo de 0 a 100. Es null para otros proveedores de datos. required: - name - first_name - last_name - job_title - seniority - department - headline - linkedin_url - city - region - country - country_code - email - email_status - email_catch_all - email_source - phone - company_name - company_domain - company_linkedin_url - apollo_match_confidence - pdl_likelihood - hunter_email_score - zoominfo_accuracy_score additionalProperties: false - type: 'null' description: >- Campos normalizados por acción; enrich y find_email devuelven una persona con los mismos campos que una fila de búsqueda. El resultado nativo del proveedor de datos no se repite aquí; permanece en el Run (GET /v1/runs/:id). Los valores que un proveedor de datos no informa son null; una respuesta vacía conserva la estructura de la acción con todos los campos en null, o items: [], con result_status no_result. Los nombres, cargos y etiquetas se muestran tal como los informa el proveedor de datos. Una puntuación del modelo propio de un proveedor de datos lleva el nombre de ese proveedor (pdl_likelihood) y es null para los demás. - search: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score - list_employees: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score - enrich: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score - find_email: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score - find_phone: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score - verify_email: email, email_status, email_catch_all, email_disposable, email_webmail, hunter_email_score provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté COMPLETED. error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: >- No es null únicamente cuando el estado es COMPLETED. - Para respuestas 2xx, output contiene JSON nativo del proveedor de datos (de cualquier estructura), o null si el cuerpo está vacío. - Para respuestas que no son 2xx, error contiene el cuerpo de error del proveedor de datos y output es null. Los campos sensibles se eliminan de ambos cuerpos. charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, con una única representación canónica). Suma con aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo total de los Runs en esta respuesta de Solution. Es null hasta que se liquiden todos los Runs incluidos. Cada Run conserva su propio cargo; los errores también pueden generar cargos. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Base del cargo de un único Run, o null para un total de varios Runs. Consulta runs[].charge_basis para cada cargo. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del envío. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado. created_at: type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, al Price o a la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. action: type: string enum: - search - list_employees - enrich - find_email - verify_email - find_phone result_status: type: string enum: - success - no_result - error - pending description: >- Estado de entrega empresarial, independiente del ciclo de vida final del Run indicado en status. no_result es una respuesta vacía pero válida; error indica que no se pudo entregar el resultado del proveedor de datos. error: anyOf: - type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false - type: 'null' runs: type: array items: type: object properties: id: type: string run_url: type: string description: >- Abre este Run en la consola. Requiere pertenecer a un Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED o RUNNING: sigue en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no son 2xx. FAILED: consulta `failure`. STOPPED: detenido antes del envío. Consulta charge_usd por separado de status. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: >- Motivo por el que falló el Run. No es null únicamente cuando el estado es FAILED. input: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false output: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté COMPLETED. required: - http_status additionalProperties: false - type: 'null' charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, con una única representación canónica). Suma con aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo final como cadena decimal exacta en USD. Es null mientras está QUEUED o RUNNING. Un Run FAILED puede tener un cargo distinto de cero según el Price del endpoint. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Cláusula de Price utilizada para calcular el cargo. Es null antes de la liquidación o cuando no se realizó ningún intento con el proveedor de datos. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del envío. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado. created_at: type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, al Price o a la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata additionalProperties: false result_url: type: string description: >- Ruta URL autenticada y de solo lectura para consultar este resultado normalizado y el cargo total. Úsala con el origen de la API. No crea Runs ni reanuda el fallback. GET /v1/runs/:id sigue devolviendo el Run individual nativo. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata - action - result_status - error - runs - result_url additionalProperties: false ValidationFailedEncoded: type: object properties: error: type: object properties: code: type: string enum: - validation_failed message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyKeyRequiredEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_key_required message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false UnauthorizedEncoded: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false InsufficientBalanceEncoded: type: object properties: error: type: object properties: code: type: string enum: - insufficient_balance message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false EndpointNotPermittedEncoded: type: object properties: error: type: object properties: code: type: string enum: - endpoint_not_permitted message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ForbiddenEncoded: type: object properties: error: type: object properties: code: type: string enum: - forbidden message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyConflictEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_conflict message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false RateLimitedEncoded: type: object properties: error: type: object properties: code: type: string enum: - rate_limited message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ServiceUnavailableEncoded: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false securitySchemes: bearer: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.