> ## 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. # List leads > Lists active leads for incremental CRM sync. One page holds at most limit leads (up to 100) and reads at most 1,000 leads, or 250 when a conversion_type or communication_channel filter is set. A page can hold fewer leads than limit, or none, while has_more is true. Request again with next_cursor until has_more is false. Do not use the page size to decide that the list is finished. A limit above 100 is accepted, and the response holds the first page of 100. **Required scopes:** `leads.read` ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/v1/leads openapi: 3.1.0 info: title: RoofKit Partner API version: 1.0.0 summary: REST JSON API for external RoofKit partner integrations. contact: name: RoofKit Engineering description: > RoofKit Partner API v1 authenticates requests with workspace API keys. API keys bind each request to exactly one workspace; Partner API paths do not accept roofer_id, workspace_id, or tenant identifiers. Authenticated endpoints are limited to 60 requests per minute per API key, method, and route template; invalid authentication attempts are limited separately at 20 requests per minute per client and endpoint. Date-time parameters and fields accept ISO 8601 with Z or a ±HH:MM offset, for example 2026-09-07T04:00:00Z or 2026-09-07T00:00:00-04:00. Both name the same instant and return the same result. Encode + as %2B in a query string. Responses return UTC. A date-time without an offset, for example 2026-09-07T04:00:00, is deprecated. Until the sunset on 2027-01-10T00:00:00Z it is read as UTC, and the response carries a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594). From the sunset, Z or a ±HH:MM offset is required. A date-time without an offset then returns 400 with the `VALIDATION_ERROR` code, and the response carries no `Deprecation` or `Sunset` header. Each API key holds only the scopes that a workspace owner or admin chose when the key was created, and its scopes never change. Each operation lists the scopes it requires in `x-required-scopes`. A new key in Settings starts on the Read-only preset: `leads.read`, `analytics.read`, `reports.read`, and `data_objects.read`. A Read-only key can call every read operation except exports, Sales Visualizer reads, and trashed Data Objects, and it cannot call any write operation. A call that needs a scope the key does not hold returns 403 `FORBIDDEN`, and `error.details.required_scope` names a missing scope. servers: - url: https://api.roofkit.ai description: Canonical RoofKit Partner API origin security: - ApiKeyBearer: [] tags: - name: Foundation description: Authentication and contract foundation endpoints. - name: Leads description: Partner CRM lead sync endpoints. - name: Attribution description: >- Partner marketing attribution, campaign analytics, and event ingestion endpoints. - name: Pipeline description: Partner-readable lead pipeline metadata. - name: Reports description: Partner report import, listing, fetch, export, and download endpoints. - name: Visualizer description: >- Partner Sales Visualizer creation, generation, hosted photo upload links, image reads, session history, and share-link endpoints. - name: Estimates description: Partner Budget Estimate creation and reads for the key-bound workspace. - name: Objects description: >- Partner Data Objects discovery, schema, records, relations, views, and admin endpoints. paths: /api/v1/leads: get: tags: - Leads summary: List leads description: >- Lists active leads for incremental CRM sync. One page holds at most limit leads (up to 100) and reads at most 1,000 leads, or 250 when a conversion_type or communication_channel filter is set. A page can hold fewer leads than limit, or none, while has_more is true. Request again with next_cursor until has_more is false. Do not use the page size to decide that the list is finished. A limit above 100 is accepted, and the response holds the first page of 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: Active leads page. 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: Filters leads by an approved conversion type. schema: type: string enum: - public_quiz - onsite_form - partner_api - jobnimbus_import - sms_inbound - phone_call CommunicationChannel: name: communication_channel in: query description: >- Filters leads that have at least one approved communication event in the channel. schema: type: string enum: - call - sms LeadType: name: lead_type in: query description: >- Filters leads by Lead type. Send the key or the current label of a workspace lead type. An unknown value returns VALIDATION_ERROR. schema: type: string maxLength: 100 UpdatedFrom: name: from in: query description: >- Inclusive updated_at lower bound for incremental sync. ISO 8601 date-time with Z or a ±HH:MM offset. Encode + as %2B. schema: type: string format: date-time UpdatedTo: name: to in: query description: >- Inclusive updated_at upper bound for incremental sync. ISO 8601 date-time with Z or a ±HH:MM offset. Encode + as %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: >- Opaque cursor returned by list/export responses. Send it back unchanged; malformed cursors return 400. schema: type: string maxLength: 500 LeadLimit: name: limit in: query description: >- Page size of a lead list, from 1 to 100. A higher value does not return 400; the server uses 100. The export ignores this value and returns up to 500 leads per response. A page can contain fewer leads than this value, or none, while has_more is true. Keep requesting with the returned cursor until has_more is false. schema: type: integer minimum: 1 default: 50 headers: RateLimitLimit: description: Maximum requests allowed in the current window. schema: type: string RateLimitRemaining: description: Requests remaining in the current window. schema: type: string RateLimitReset: description: ISO timestamp when the current rate-limit window resets. schema: type: string format: date-time Deprecation: description: > Present only when the request sent a date-time without a UTC offset. That form is deprecated and was read as UTC. The value is the RFC 9745 deprecation date as `@` and Unix seconds. schema: type: string example: '@1791763200' Sunset: description: > Present only with Deprecation. The RFC 8594 HTTP-date from which a date-time without a UTC offset returns 400. schema: type: string example: Sun, 10 Jan 2027 00:00:00 GMT RetryAfter: description: Seconds until the caller should retry. 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: Stored phone digits for the lead. type: - string - 'null' property_address: description: Property address text for the lead. type: - string - 'null' status: description: >- Compatibility bucket of the Contacts status (not_set, pending, appointment_scheduled, sold, or lost). A workspace that imports its CRM keeps the deal Stage on Opportunities, and its leads can stay on not_set. type: string status_stage_id: description: Id of the Contacts status. type: - string - 'null' status_label: description: Label of the Contacts status. 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: Lead type key. It tells how the contact came in. Null when unset. type: - string - 'null' lead_type_label: description: Current workspace label of lead_type. Null when lead_type is null. type: - string - 'null' landing_url: description: First page that the contact converted on, without the query string. type: - string - 'null' first_form_name: description: Name of the first form that the contact sent. 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: >- Exact number of rows that match the request. Some reads include it and others do not, so treat it as optional. 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: >- Website entry for this touch. Omitted when unset. Does not replace 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: Request payload, query, or required header is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing, malformed, revoked, deleted, or unknown API key. headers: WWW-Authenticate: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks a required scope, or the workspace is not active. A scope failure names a missing scope in `details.required_scope`. When the key lookup refuses the call, `details.missing_scopes` lists every required scope that the key does not hold. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_scope: summary: A Read-only key calls a write operation 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 exceeded for this key and endpoint or invalid-auth bucket. 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: Internal authentication or server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: RoofKit API key description: 'Use `Authorization: Bearer rk_live_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.