> ## Documentation Index > Fetch the complete documentation index at: https://docs.roofkit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Listar leads > Lista leads activos para sincronización incremental con CRM. Una página contiene como máximo limit leads (hasta 100) y lee como máximo 1,000 leads, o 250 cuando se define un filtro conversion_type o communication_channel. Una página puede contener menos leads que limit, o ninguno, mientras has_more sea true. Vuelva a solicitar con next_cursor hasta que has_more sea false. No use el tamaño de la página para decidir que la lista terminó. Se acepta un limit mayor que 100, y la respuesta contiene la primera página de 100. **Scopes requeridos:** `leads.read` ## OpenAPI ````yaml /es/api-reference/openapi.yaml get /api/v1/leads openapi: 3.1.0 info: title: RoofKit Partner API version: 1.0.0 summary: API REST JSON para integraciones externas de socios de RoofKit. contact: name: RoofKit Engineering description: >- RoofKit Partner API v1 autentica solicitudes con API keys del workspace. Las API keys vinculan cada solicitud exactamente a un workspace; las rutas de Partner API no aceptan roofer_id, workspace_id ni identificadores de tenant. Los endpoints autenticados están limitados a 60 solicitudes por minuto por API key, método y plantilla de ruta; los intentos de autenticación inválidos se limitan por separado a 20 solicitudes por minuto por cliente y endpoint. Los parámetros y campos de fecha/hora aceptan ISO 8601 con Z o un desfase ±HH:MM, por ejemplo 2026-09-07T04:00:00Z o 2026-09-07T00:00:00-04:00. Ambos indican el mismo instante y devuelven el mismo resultado. Codifica + como %2B en una query string. Las respuestas usan UTC. Una fecha/hora sin desfase, por ejemplo 2026-09-07T04:00:00, está obsoleta. Hasta la fecha de retiro, 2027-01-10T00:00:00Z, se interpreta como UTC, y la respuesta incluye un header `Deprecation` (RFC 9745) y un header `Sunset` (RFC 8594). A partir de la fecha de retiro, se requiere Z o un desfase ±HH:MM. Desde entonces, una fecha/hora sin desfase devuelve 400 con el código `VALIDATION_ERROR`, y la respuesta no incluye ningún header `Deprecation` ni `Sunset`. Cada API key tiene solo los scopes que un propietario o administrador del workspace eligió al crear la key, y sus scopes nunca cambian. Cada operación indica los scopes que requiere en `x-required-scopes`. Una key nueva en Configuración empieza con el nivel predefinido Solo lectura: `leads.read`, `analytics.read`, `reports.read` y `data_objects.read`. Una key de Solo lectura puede llamar a todas las operaciones de lectura excepto las exportaciones, las lecturas de Sales Visualizer y los Data Objects en papelera, y no puede llamar a ninguna operación de escritura. Una llamada que necesita un scope que la key no tiene devuelve 403 `FORBIDDEN`, y `error.details.required_scope` indica un scope faltante. servers: - url: https://api.roofkit.ai description: Origen canónico de RoofKit Partner API security: - ApiKeyBearer: [] tags: - name: Foundation description: Endpoints base de autenticación y contrato. - name: Leads description: Endpoints de sincronización de leads para CRM de socios. - name: Attribution description: >- Endpoints de atribución de marketing, analíticas de campañas e ingesta de eventos para socios. - name: Pipeline description: Metadatos del pipeline de leads legibles para socios. - name: Reports description: >- Endpoints para importar, listar, obtener, exportar y descargar reportes de socios. - name: Visualizer description: >- Endpoints de Partner para crear Sales Visualizer, generar visualizaciones, crear enlaces alojados de subida de fotos, leer imágenes, consultar el historial de sesión y crear enlaces compartidos. - name: Estimates description: >- Creación y lectura de Budget Estimates de Partner para el workspace vinculado a la key. - name: Objects description: >- Endpoints de Partner para descubrimiento, esquema, registros, relaciones, vistas y administración de Data Objects. paths: /api/v1/leads: get: tags: - Leads summary: Listar leads description: >- Lista leads activos para sincronización incremental con CRM. Una página contiene como máximo limit leads (hasta 100) y lee como máximo 1,000 leads, o 250 cuando se define un filtro conversion_type o communication_channel. Una página puede contener menos leads que limit, o ninguno, mientras has_more sea true. Vuelva a solicitar con next_cursor hasta que has_more sea false. No use el tamaño de la página para decidir que la lista terminó. Se acepta un limit mayor que 100, y la respuesta contiene la primera página de 100. operationId: List leads parameters: - $ref: '#/components/parameters/Source' - $ref: '#/components/parameters/Medium' - $ref: '#/components/parameters/Campaign' - $ref: '#/components/parameters/ConversionType' - $ref: '#/components/parameters/CommunicationChannel' - $ref: '#/components/parameters/LeadType' - $ref: '#/components/parameters/UpdatedFrom' - $ref: '#/components/parameters/UpdatedTo' - $ref: '#/components/parameters/StatusStageId' - $ref: '#/components/parameters/Search' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/LeadLimit' responses: '200': description: Página de leads activos. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/LeadListResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: Source: name: source in: query schema: type: string maxLength: 500 Medium: name: medium in: query schema: type: string maxLength: 500 Campaign: name: campaign in: query schema: type: string maxLength: 500 ConversionType: name: conversion_type in: query description: Filtra leads por un tipo de conversión aprobado. schema: type: string enum: - public_quiz - onsite_form - partner_api - jobnimbus_import - sms_inbound - phone_call CommunicationChannel: name: communication_channel in: query description: >- Filtra leads que tienen al menos un evento de comunicación aprobado en el canal. schema: type: string enum: - call - sms LeadType: name: lead_type in: query description: >- Filtra leads por tipo de lead. Envíe la clave o la etiqueta actual de un tipo de lead del workspace. Un valor desconocido devuelve VALIDATION_ERROR. schema: type: string maxLength: 100 UpdatedFrom: name: from in: query description: >- Límite inferior inclusivo de updated_at para sincronización incremental. Fecha/hora ISO 8601 con Z o un desfase ±HH:MM. Codifica + como %2B. schema: type: string format: date-time UpdatedTo: name: to in: query description: >- Límite superior inclusivo de updated_at para sincronización incremental. Fecha/hora ISO 8601 con Z o un desfase ±HH:MM. Codifica + como %2B. schema: type: string format: date-time StatusStageId: name: status_stage_id in: query schema: type: string maxLength: 150 Search: name: search in: query schema: type: string maxLength: 200 Cursor: name: cursor in: query description: >- Cursor opaco devuelto por respuestas de listado/exportación. Envíalo de vuelta sin cambios; los cursores malformados devuelven 400. schema: type: string maxLength: 500 LeadLimit: name: limit in: query description: >- Tamaño de página de una lista de leads, de 1 a 100. Un valor mayor no devuelve 400; el servidor usa 100. La exportación ignora este valor y devuelve hasta 500 leads por respuesta. Una página puede contener menos leads que este valor, o ninguno, mientras has_more sea true. Siga solicitando con el cursor devuelto hasta que has_more sea false. schema: type: integer minimum: 1 default: 50 headers: RateLimitLimit: description: Cantidad máxima de solicitudes permitidas en la ventana actual. schema: type: string RateLimitRemaining: description: Solicitudes restantes en la ventana actual. schema: type: string RateLimitReset: description: Timestamp ISO cuando se reinicia la ventana actual de rate limit. schema: type: string format: date-time Deprecation: description: >- Presente solo cuando la solicitud envió una fecha/hora sin desfase respecto a UTC. Esa forma está obsoleta y se interpretó como UTC. El valor es la fecha de obsolescencia de RFC 9745 como `@` seguido de los segundos Unix. schema: type: string example: '@1791763200' Sunset: description: >- Presente solo con Deprecation. La HTTP-date de RFC 8594 a partir de la cual una fecha/hora sin desfase respecto a UTC devuelve 400. schema: type: string example: Sun, 10 Jan 2027 00:00:00 GMT RetryAfter: description: Segundos hasta que el llamador debería reintentar. schema: type: string schemas: LeadListResponse: type: object additionalProperties: false required: - leads - pagination properties: leads: type: array items: $ref: '#/components/schemas/Lead' pagination: $ref: '#/components/schemas/CursorPagination' Lead: type: object additionalProperties: false required: - id - contact_name - contact_email - contact_phone - property_address - status - status_stage_id - attribution - communication_summary - created_at - updated_at properties: id: type: string external_id: type: - string - 'null' external_source: type: - string - 'null' contact_name: type: - string - 'null' contact_email: type: - string - 'null' format: email contact_phone: description: Dígitos telefónicos almacenados para el lead. type: - string - 'null' property_address: description: Texto de dirección de la propiedad del lead. type: - string - 'null' status: description: >- Grupo de compatibilidad del estado de Contacts (not_set, pending, appointment_scheduled, sold o lost). Un workspace que importa su CRM guarda la etapa del negocio en Opportunities, y sus leads pueden quedar en not_set. type: string status_stage_id: description: Id del estado de Contacts. type: - string - 'null' status_label: description: Etiqueta del estado de Contacts. type: - string - 'null' status_sort_order: type: - integer - 'null' is_conversion_stage: type: boolean stage_timestamps: type: - object - 'null' additionalProperties: type: - string - 'null' funnel_gap_summary: type: - object - 'null' additionalProperties: true attribution: $ref: '#/components/schemas/Attribution' lead_type: description: >- Clave del tipo de lead. Indica cómo llegó el contacto. Null cuando no está definida. type: - string - 'null' lead_type_label: description: >- Etiqueta actual de lead_type en el workspace. Null cuando lead_type es null. type: - string - 'null' landing_url: description: Primera página en la que el contacto convirtió, sin la query string. type: - string - 'null' first_form_name: description: Nombre del primer formulario que envió el contacto. type: - string - 'null' communication_summary: $ref: '#/components/schemas/LeadCommunicationSummary' form_data: $ref: '#/components/schemas/JsonRecord' custom_fields: $ref: '#/components/schemas/JsonRecord' selected_material_id: type: - string - 'null' selected_color_id: type: - string - 'null' selected_shape_id: type: - string - 'null' notes: type: - string - 'null' quote_value: type: - number - 'null' sales_value: type: - number - 'null' follow_up_date: type: - string - 'null' format: date-time converted_at: type: - string - 'null' format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time CursorPagination: type: object additionalProperties: false required: - limit - next_cursor - has_more properties: limit: type: integer minimum: 1 maximum: 10000 next_cursor: type: - string - 'null' has_more: type: boolean total: type: integer minimum: 0 description: >- Cantidad exacta de filas que coinciden con la solicitud. Algunas lecturas la incluyen y otras no, así que trátala como opcional. ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message - request_id properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string request_id: type: string details: type: object additionalProperties: true Attribution: type: object additionalProperties: false properties: source: type: - string - 'null' medium: type: - string - 'null' campaign: type: - string - 'null' content: type: - string - 'null' conversion_url: type: - string - 'null' format: uri entry: description: >- Entrada al sitio web de este punto de contacto. Se omite cuando no está definida. No reemplaza source. type: string enum: - button - embed - direct LeadCommunicationSummary: type: object additionalProperties: false required: - last_call_at - last_sms_at - call_count - answered_call_count - missed_call_count - sms_inbound_count - sms_outbound_count - last_tracking_number - last_communication_source - last_communication_campaign properties: last_call_at: type: - string - 'null' format: date-time last_sms_at: type: - string - 'null' format: date-time call_count: type: integer answered_call_count: type: integer missed_call_count: type: integer sms_inbound_count: type: integer sms_outbound_count: type: integer last_tracking_number: oneOf: - $ref: '#/components/schemas/TrackingNumberSummary' - type: 'null' last_communication_source: type: - string - 'null' last_communication_campaign: type: - string - 'null' JsonRecord: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: oneOf: - type: string - type: number - type: boolean - type: 'null' ErrorCode: type: string enum: - UNAUTHORIZED - FORBIDDEN - RATE_LIMITED - VALIDATION_ERROR - NOT_FOUND - CONFLICT - INSUFFICIENT_CREDITS - INTERNAL_ERROR TrackingNumberSummary: type: object additionalProperties: false required: - label - phone_last4 - national_format properties: label: type: - string - 'null' phone_last4: type: - string - 'null' national_format: type: - string - 'null' responses: ValidationError: description: El payload, query o header requerido de la solicitud no es válido. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: API key ausente, malformada, revocada, eliminada o desconocida. headers: WWW-Authenticate: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- La API key no tiene un scope requerido, o el workspace no está activo. Un fallo de scope indica un scope faltante en `details.required_scope`. Cuando la búsqueda de la key rechaza la llamada, `details.missing_scopes` lista cada scope requerido que la key no tiene. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_scope: summary: Una key de Solo lectura llama a una operación de escritura value: error: code: FORBIDDEN message: 'API key does not include the required scope: leads.write.' request_id: req_123 details: required_scope: leads.write missing_scopes: - leads.write RateLimited: description: >- Rate limit excedido para esta key y endpoint o para el bucket de autenticación inválida. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Error interno de autenticación o del servidor. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: RoofKit API key description: 'Usa `Authorization: Bearer rk_live_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.