Saltar al contenido principal
POST
Búsqueda de personas
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. 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.

​
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. 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).

​
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.

Encabezados

​
idempotency-key
string
requerido

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.

Minimum string length: 1

Cuerpo

application/json
​
action
enum<string> | null

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.

Opciones disponibles:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
provider
enum<string> | null

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.

Opciones disponibles:
auto,
apollo,
pdl,
leadmagic,
zoominfo,
hunter,
prospeo
​
job_titles
string[] | null

Cargos que deben coincidir. PDL compara cada cargo exactamente como se proporciona, por lo que 'CTO' no coincide con 'Co-founder & CTO'.

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
seniorities
enum<string>[] | null

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.

Required array length: 1 - 11 elements
Opciones disponibles:
owner,
founder,
c_suite,
partner,
vp,
head,
director,
manager,
senior,
entry,
intern
​
locations
string[] | null

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'.

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
company_domain
string | null

Un dominio web como stripe.com. Se acepta una URL completa y se reduce a su host.

Required string length: 3 - 253
​
keywords
string | null
Required string length: 1 - 300
​
full_name
string | null
Required string length: 1 - 200
​
email
string | null

Una dirección de correo electrónico.

Maximum string length: 320
Pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
​
linkedin_url
string | null

La URL del perfil de LinkedIn de la persona, linkedin.com/in/<slug>. No es una página de empresa.

Maximum string length: 2048
Pattern: linkedin\.com\/in\/[^/?#\s]+
​
limit
integer | null

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.

Rango requerido: 1 <= x <= 100
​
task_id
string | null

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.

​
metadata

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.

Respuesta

Success

​
id
string
requerido
​
run_url
string
requerido

Abre este Run en la consola. Requiere pertenencia a un Workspace.

​
provider
string
requerido
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
requerido
Pattern: ^\/.+$
​
endpoint_version
integer
requerido
​
status
enum<string>
requerido

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.

Opciones disponibles:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
requerido

Motivo por el que falló el Run. No es null solo cuando el estado es FAILED.

​
input
object
requerido
​
output
object
requerido

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
object | null
requerido

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
string | null
requerido

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.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
requerido

Base del cargo de un único Run, o null para un total de varios Runs. Consulta runs[].charge_basis para cada cargo.

​
stoppable
boolean
requerido

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
string<date-time> | null
requerido

Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado.

​
created_at
string<date-time>
requerido

Marca de tiempo UTC en formato ISO-8601

​
started_at
string<date-time> | null
requerido

Marca de tiempo UTC en formato ISO-8601

​
completed_at
string<date-time> | null
requerido

Marca de tiempo UTC en formato ISO-8601

​
task_id
string | null
requerido
​
metadata
object
requerido

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
enum<string>
requerido
Opciones disponibles:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
result_status
enum<string>
requerido

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.

Opciones disponibles:
success,
no_result,
error,
pending
​
error
object | null
requerido
​
runs
object[]
requerido
​
result_url
string
requerido

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.