> ## Documentation Index > Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt > Use this file to discover all available pages before exploring further. # List Discover leads > List the Discover leads (brand inquiries) submitted to your agency, ordered newest-first. Each lead includes: - the brand's contact details and submitted lead-form `answers`, - the lead-form field definitions (`leadForm.fields`) so you can map each answer back to its question, - the submitting brand's `company` profile (joined live from the brand's workspace where available, otherwise the values captured at submit time), - lightweight `engagement` counters (messages, calls). Results are scoped to the authenticated company — you can only read leads that belong to your agency. Duplicate interaction records for the same brand + listing are collapsed into a single lead. ## OpenAPI ````yaml /openapi/platform-apikey.yaml get /discover/leads openapi: 3.0.4 info: title: Sideshift Public API version: 1.0.0 description: > REST API for Sideshift platform. Authenticate using your API key in the `x-api-key` header. This document covers the **public, API-key-authenticated** surface. The restricted endpoints (Jobs, Applicants, payout execution/Quick Pay) are gated to an explicit partner allowlist and are documented in the **Full Access** spec (`sideshift-api-private.yaml`); a non-allowlisted key calling them receives `403`. API-key *management* (creating/rotating keys, digest automations) is performed in the dashboard with a Firebase session and is not part of this API-key contract. ## Requirements - **Active Subscription Required**: API access requires an active Sideshift subscription. Requests from a company without one return `402 { "error": "Active subscription required" }`. - API key from Settings → Integrations ## Rate Limits - Default: **100 requests per minute** per API key. - Allowlisted partner accounts: **400 requests per minute**. - Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers; exceeding the limit returns `429`. ## Errors - Errors are returned as `{ "error": "" }` with the appropriate HTTP status (`400` invalid request, `401` invalid/missing key, `402` no active subscription, `403` restricted endpoint / cross-company, `404` not found, `429` rate limited). Some endpoints add a `code` (e.g. `LEAD_NOT_FOUND`). ## Timestamps - All timestamps are Unix timestamps in milliseconds - Example: `1634567890000` ## Pagination - Most list endpoints support `page` (default: 1) and `limit` (default: 25, max: 100) parameters and return `{ data, page, total }`. Some additionally return `limit` and/or `totalPages`. - Agency (parent) accounts can pass `scope=agency` on analytics/posts endpoints to aggregate across the parent agency and every subaccount. ## Base URL - Production: `https://app.sideshift.app/api/v1` servers: - url: https://app.sideshift.app/api/v1 description: Production server security: - apiKeyAuth: [] tags: - name: Programs description: Campaign and program management - name: Posts description: Social media posts and content - name: Analytics description: Performance metrics and KPIs - name: Payouts description: Payout management including pending payouts and execution - name: Contracts description: Creator contracts and agreements - name: Creators description: Creator profiles and statistics - name: Invoices description: Create, list, and send invoices to customers - name: Discover description: Read Discover leads (brand inquiries) submitted to your agency paths: /discover/leads: get: tags: - Discover summary: List Discover leads description: > List the Discover leads (brand inquiries) submitted to your agency, ordered newest-first. Each lead includes: - the brand's contact details and submitted lead-form `answers`, - the lead-form field definitions (`leadForm.fields`) so you can map each answer back to its question, - the submitting brand's `company` profile (joined live from the brand's workspace where available, otherwise the values captured at submit time), - lightweight `engagement` counters (messages, calls). Results are scoped to the authenticated company — you can only read leads that belong to your agency. Duplicate interaction records for the same brand + listing are collapsed into a single lead. parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 25 - in: query name: status schema: type: string enum: - new - contacted - call_booked - proposal_sent - won - lost - unqualified - nurture - all description: Filter by lead status. responses: '200': description: Discover leads retrieved content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/DiscoverLead' page: type: integer limit: type: integer total: type: integer '400': description: Invalid query parameter '401': description: Invalid or missing API key '402': description: Active subscription required '429': description: Rate limit exceeded components: schemas: DiscoverLead: type: object properties: id: type: string status: type: string enum: - new - contacted - call_booked - proposal_sent - won - lost - unqualified - nurture submittedAt: type: string format: date-time nullable: true statusUpdatedAt: type: string format: date-time nullable: true listing: type: object properties: id: type: string title: type: string formTitle: type: string nullable: true contact: type: object description: Primary contact details the brand provided. properties: name: type: string email: type: string phone: type: string company: $ref: '#/components/schemas/DiscoverLeadCompany' agency: type: object description: The agency that owns this lead (your authenticated company). properties: id: type: string name: type: string nullable: true avatarUrl: type: string nullable: true answers: type: array items: $ref: '#/components/schemas/DiscoverLeadAnswer' leadForm: type: object description: Lead-form field definitions for this listing. properties: fields: type: array items: $ref: '#/components/schemas/DiscoverLeadFormField' engagement: type: object properties: messageCount: type: integer callCount: type: integer lastMessageAt: type: string format: date-time nullable: true lastCallAt: type: string format: date-time nullable: true lastEngagedAt: type: string format: date-time nullable: true DiscoverLeadCompany: type: object description: The submitting brand's company profile (joined live where available). properties: id: type: string nullable: true name: type: string nullable: true website: type: string nullable: true appstoreUrl: type: string nullable: true avatarUrl: type: string nullable: true type: type: string nullable: true description: Account type of the submitting company (e.g. `Employer`). DiscoverLeadAnswer: type: object description: A single answer the brand submitted on the lead form. properties: fieldId: type: string description: >- Identifier of the lead-form field (or `name`/`email`/`phone` for contact fields). label: type: string type: type: string description: >- Field type, e.g. `contact`, `short_text`, `single_select`, `file_upload`. required: type: boolean value: nullable: true description: >- Raw submitted value (string, array of strings, boolean, or array of file objects). displayValue: type: string description: Human-readable rendering of the answer. DiscoverLeadFormField: type: object description: Definition of a lead-form field, useful for interpreting answers. properties: id: type: string label: type: string type: type: string required: type: boolean description: type: string options: type: array items: type: object properties: id: type: string label: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication. Get yours from Settings → Integrations ````