API para clientes: búsqueda, enriquecimiento y exportación

Autenticación y límites

Cree una clave en la configuración de claves de API. Su secreto se muestra una sola vez. Use leads:read para ubicaciones, estado, resultados y exportaciones; leads:write para la creación de tareas y acciones. Un flujo de trabajo que haga ambas cosas necesita ambos ámbitos. Las claves antiguas no adquieren ámbitos automáticamente.

Envíe Authorization: Bearer sk_YOUR_KEY. Guarde el secreto en un almacén de credenciales, nunca en un flujo de trabajo público ni en una URL. El aislamiento de cuentas sigue aplicándose. La API de producción D1 permite hasta 60 solicitudes por minuto por cuenta y requiere al menos 200 ms entre solicitudes. Hasta tres tareas activas de búsqueda/campaña/enriquecimiento comparten el presupuesto de concurrencia de la cuenta.

Cada creación de tarea necesita una Idempotency-Key que contenga 8–100 letras, dígitos, guiones bajos o guiones. Reintente una solicitud sin cambios con la misma clave. Use una clave nueva para una tarea nueva. El éxito devuelve HTTP 202, no los datos completados.

Descubrir una ubicación compatible

curl "https://ownerclue.com/api/v1/leads/locations?country=US&type=City&q=Phoenix"   -H "Authorization: Bearer $OWNERCLUE_API_KEY"

Use un código devuelto; no invente un locationCode. Los códigos de país registrados incluyen US, CA, GB (Reino Unido), AU, IE, NZ, SG, DE, FR, ES, IT, NL, MX, BR, PT, AT, CH, BE, ZA y AE (20 países). Cada país debe estar habilitado y disponible para la cuenta. GET /api/v1/leads/countries devuelve el arreglo de códigos disponibles; añada ?metadata=true para obtener nombres de países, idiomas y tipos de ubicación compatibles. El espacio de trabajo muestra las mismas opciones disponibles. El inglés (en) es compatible en estos países; Canadá también admite fr. Los idiomas de búsqueda local son de para Alemania y Austria, fr para Francia, es para España y México, it para Italia, nl para los Países Bajos y pt para Brasil y Portugal. Suiza admite de/fr/it/en y Bélgica admite nl/fr/de/en. Sudáfrica y los EAU actualmente admiten búsquedas en inglés; las consultas en árabe y otros idiomas locales aún no están habilitadas. La búsqueda por palabras clave en el idioma local está disponible independientemente de la coincidencia exacta de categorías, que requiere validación específica por país e idioma. La disponibilidad de un país no establece la calidad de los contactos.

Las ubicaciones se pueden acotar por tipo, level=region o level=city y parentCode. level=city busca los descendientes de una región seleccionada, incluidas las ciudades bajo condados o distritos intermedios. También incluye áreas locales compatibles, como los boroughs del Reino Unido y los barrios de Singapur. Para Singapur, type=Country devuelve un código de país directamente consultable; la selección de región es opcional.

El directorio devuelve un array dentro de data, no un sobre de trabajos paginado. Use limit=1–100 (predeterminado 50) y offset=0, luego aumente offset según la longitud devuelta; deténgase cuando una página contenga menos filas que limit. Ejemplo: /api/v1/leads/locations?country=GB&level=city&limit=50&offset=50. Reemplace el origen de los ejemplos por el origen público de la app que utilice.

Crear una búsqueda y luego consultar su estado

{
  "keyword": "plumber",
  "locationCode": 123456,
  "languageCode": "en",
  "depth": 20
}

Envíe este cuerpo mediante POST a /api/v1/leads/searches con ambas cabeceras. El código de ubicación anterior es un marcador de posición. Una respuesta correcta tiene code: 0 y data.id. Consulte GET /api/v1/leads/searches/{id} hasta que data.status sea completed. queued/running requieren otra consulta; failed requiere inspeccionar el error. No exporte una tarea incompleta.

Rutas

Método y ruta bajo /api/v1/leads	Propósito
GET /countries	Códigos de país disponibles; metadata=true incluye nombres, idiomas y tipos de ubicación
GET /locations	Directorio de ubicaciones compatibles; country, q, type, level, parentCode, limit, offset
GET /searches, /campaigns, /enrichments	Listar trabajos propios
POST /searches	keyword, locationCode, languageCode, depth; exactCategory opcional
POST /campaigns/preview	Previsualizar los códigos de ubicación seleccionados y el máximo estimado de leads
POST /campaigns	keyword, locations (códigos), languageCode, depth, maxLeads
POST /enrichments	rows: [{domain, name?}] o cadena csv; como máximo 1,000 filas
GET /searches/{id}, /campaigns/{id}, /enrichments/{id}	Estado y detalles de la tarea
GET /…/{id}/results?limit=100&cursor=…	Resultados y nextCursor
GET /…/{id}/export?format=full	CSV tras la finalización
POST /campaigns/{id}/pause, /resume, /stop	Control de la campaña
POST /enrichments/{id}/resume	Reanudar un enriquecimiento pausado

La profundidad de búsqueda es 1–700. La profundidad de campaña acepta 20, 50, 100, 300, 500 o 700; seleccione 1–100 códigos de ubicación y previsualice las ubicaciones de búsqueda expandidas antes de la creación. Las regiones se expanden en nodos de búsqueda locales compatibles; la raíz de país de Singapur sigue siendo una única ubicación consultable. La guía multicuidad explica la cancelación y la deduplicación.

Paginación y filtros

Las listas de trabajos y los resultados colocan los elementos y nextCursor dentro de data. Mantenga limit constante entre páginas, pase el cursor devuelto sin cambios y deténgase cuando nextCursor sea null. Los resultados pueden cambiar durante el procesamiento porque la paginación actualmente usa offsets; lea los datos finales tras la finalización. Las ubicaciones son una excepción con un array simple.

Los resultados de Maps y las exportaciones comparten los filtros q, email=true, owner=true, websiteStatus, signal, phoneType e includeExcluded=true. Las señales compatibles son no_website, website_unreachable, booking_not_found y reviews_below_20. Los formatos de exportación son basic, full, gohighlevel, instantly y 1cw. Los resultados de enriquecimiento devuelven el resultado de cada fila en lugar de los filtros de leads de Maps.

Errores y política de reintentos

Estado HTTP	Acción
202	Guarde data.id y consulte el estado
400	Corrija la entrada, la clave de idempotencia, la ubicación, el saldo de créditos o la condición de concurrencia; inspeccione el mensaje
401	Proporcione la cabecera Bearer
403	Compruebe la validez de la clave, los ámbitos, la propiedad y la disponibilidad de la exportación
404	Compruebe el ID de la tarea y la cuenta
429	Espere antes de reintentar
503	Capacidad no disponible; reintente solo cuando cambie su disponibilidad

Las respuestas JSON usan {code, message, data}; las exportaciones CSV devuelven text/csv. Registre tanto el estado HTTP como el código. Actualmente no hay webhook de finalización de tareas disponible; use la guía de consulta de n8n. Las reglas de facturación se aplican tanto a las tareas de API como a las del espacio de trabajo.

Valoraciones, reseñas y listas

La interfaz, los resultados API y los CSV admiten minRating/maxRating (0–5) y minReviews/maxReviews (enteros no negativos). Límites inclusivos; los vacíos no cuentan como cero. Ejemplo: ?minRating=3.5&maxRating=4.5&minReviews=10&maxReviews=50. Se rechazan rangos inválidos o invertidos. El CSV completo añade business_id y enlaces de reserva/pedido con fuentes. Comparar listas.