> ## 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 lead sources > Lists first-touch attribution source groups for the key-bound workspace. **Required scopes:** `analytics.read` ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/v1/lead-sources 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/lead-sources: get: tags: - Attribution summary: List lead sources description: Lists first-touch attribution source groups for the key-bound workspace. operationId: List lead sources parameters: - $ref: '#/components/parameters/AttributionFrom' - $ref: '#/components/parameters/AttributionTo' - $ref: '#/components/parameters/AttributionTimezone' responses: '200': description: Lead source attribution rows. 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/LeadSourcesResponse' '400': $ref: '#/components/responses/AttributionValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: AttributionFrom: name: from in: query description: >- Inclusive lower bound. ISO 8601 date-time with Z or a ±HH:MM offset. Encode + as %2B. Defaults to 30 days before `to` or now. schema: type: string format: date-time AttributionTo: name: to in: query description: >- Exclusive upper bound. ISO 8601 date-time with Z or a ±HH:MM offset. Encode + as %2B. Defaults to the current server time. schema: type: string format: date-time AttributionTimezone: name: timezone in: query description: IANA timezone used for analytics bounds and spend proration. schema: type: string default: UTC maxLength: 100 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: LeadSourcesResponse: type: object additionalProperties: false required: - lead_sources - summary - range properties: lead_sources: type: array items: $ref: '#/components/schemas/AttributionRow' summary: $ref: '#/components/schemas/AttributionMetrics' range: $ref: '#/components/schemas/AttributionRange' restricted: $ref: '#/components/schemas/AttributionFinancialRestriction' AttributionRow: type: object additionalProperties: false required: - id - key - label - source - medium - campaign - metrics properties: id: type: string key: type: string label: type: string source: type: - string - 'null' medium: type: - string - 'null' campaign: type: - string - 'null' metrics: $ref: '#/components/schemas/AttributionMetrics' AttributionMetrics: type: object additionalProperties: false required: - lead_count - conversion_count - conversion_rate - avg_lead_to_sold_seconds - funnel_gap_count - funnel_gap_rate - stage_counts - stages - trend - trends - automated_spend_cents - other_costs_cents - total_spend_cents - prorated_spend_cents - cpl_cents - cpa_cents - revenue_cents - roas - currency - form_count - call_count - answered_call_count - missed_call_count - avg_call_duration_seconds - call_duration_seconds_total - sms_inbound_count - sms_outbound_count - sms_inbound_thread_count - sms_responded_thread_count - sms_response_rate properties: lead_count: type: integer conversion_count: type: integer conversion_rate: type: number avg_lead_to_sold_seconds: type: - number - 'null' funnel_gap_count: type: integer funnel_gap_rate: type: number funnel_gap_stage_counts: type: object additionalProperties: type: integer stage_counts: description: >- Leads in each Contacts status, by status id. A workspace that imports its CRM keeps the deal Stage on Opportunities, so read opportunities for that funnel. type: object additionalProperties: type: integer stages: type: array items: type: object additionalProperties: true trend: type: object additionalProperties: true trends: type: object additionalProperties: true automated_spend_cents: type: - integer - 'null' other_costs_cents: type: - integer - 'null' total_spend_cents: type: - integer - 'null' prorated_spend_cents: type: - integer - 'null' cpl_cents: type: - integer - 'null' cpa_cents: type: - integer - 'null' revenue_cents: description: >- Sales value approved in the range, in cents, by the first-touch source of the Contact linked to each Opportunity. Only the lead source endpoints fill it. It is null on the campaign endpoints and without financial access. type: - integer - 'null' roas: description: >- revenue_cents divided by prorated_spend_cents, rounded to two decimals. It is null without spend, on the campaign endpoints, and without financial access. type: - number - 'null' opportunities: $ref: '#/components/schemas/AttributionOpportunityMetrics' currency: type: - string - 'null' form_count: type: integer call_count: type: integer answered_call_count: type: integer missed_call_count: type: integer avg_call_duration_seconds: type: - number - 'null' call_duration_seconds_total: type: integer sms_inbound_count: type: integer sms_outbound_count: type: integer sms_inbound_thread_count: type: integer sms_responded_thread_count: type: integer sms_response_rate: type: number AttributionRange: type: object additionalProperties: false required: - from - to - timezone properties: from: type: string format: date-time to: type: string format: date-time timezone: type: string AttributionFinancialRestriction: type: string enum: - financial description: >- Present when the member behind the API key has no financial access. Spend, cost per lead, cost per acquisition, revenue, and ROAS are then null. 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 AttributionOpportunityMetrics: type: object additionalProperties: false description: >- Opportunity figures of the Overview Sources table, by the first-touch source of the Contact linked to each Opportunity. Only the lead source endpoints return them. The figures count whole calendar days in timezone. A figure is null when RoofKit could not read it completely for the range. required: - created_count - appointment_count - won_count properties: created_count: description: Opportunities created in the range. type: - integer - 'null' appointment_count: description: Opportunities that entered the Appointment Stage in the range. type: - integer - 'null' won_count: description: Opportunities that entered the Won Stage in the range. type: - integer - 'null' ErrorCode: type: string enum: - UNAUTHORIZED - FORBIDDEN - RATE_LIMITED - VALIDATION_ERROR - NOT_FOUND - CONFLICT - INSUFFICIENT_CREDITS - INTERNAL_ERROR responses: AttributionValidationError: description: >- The query is invalid, or the range has too many leads for one request. A range above the lookup limit returns `details.reason` set to `range_too_large`, with `lead_count` and `suggested_max_days`. `suggested_max_days` is the largest number of whole days that fits when `to` stays the same, or null when one day is already above the limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: range_too_large: summary: Range has too many leads for one request value: error: code: VALIDATION_ERROR message: >- The date range contains too many leads for one request. With the same to, request 45 days or fewer. request_id: req_123 details: reason: range_too_large lead_count: 2800 suggested_max_days: 45 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.