> ## Documentation Index > Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt > Use this file to discover all available pages before exploring further. # List Leads in Voice Campaign > Returns all leads for the specified campaign, ordered by most recently created first. ## Authentication All requests require an `Authorization` header using Bearer token authentication: `Authorization: Bearer ` ## OpenAPI ````yaml GET /api/v2/voice-campaigns/{campaign_id}/leads/list openapi: 3.1.0 info: title: VoiceAIWrapper API description: >- REST API for managing campaigns, leads, clients, web widgets, and voice providers on VoiceAIWrapper. license: name: MIT version: 1.0.0 servers: - url: https://api.voiceaiwrapper.app security: - bearerAuth: [] paths: /api/v2/voice-campaigns/{campaign_id}/leads/list: get: tags: - Leads (v2) summary: List Leads in Campaign description: >- Returns all leads for the specified campaign, ordered by most recently created first. ## Authentication All requests require an `Authorization` header using Bearer token authentication: `Authorization: Bearer ` operationId: getLeadsInCampaignV2 parameters: - name: campaign_id in: path required: true description: Campaign global ID. Required. schema: type: string example: VnVpc2VDYW1wYWlnbjoxMjM0 - name: limit in: query required: false description: Maximum number of leads to return. Default 50, maximum 200. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: offset in: query required: false description: Number of leads to skip from the start of the result set. Default 0. schema: type: integer minimum: 0 default: 0 responses: '200': description: >- Paginated list of leads and `page_info` (total count, limit, offset, and next/previous flags). content: application/json: schema: $ref: '#/components/schemas/GetCampaignLeadsV2Response' example: leads: - id: Vm9pY2VDYW1wYWlnbkxlYWQ6YWJj phone_number: '+14155552671' first_name: Jane last_name: Doe email: jane@example.com source: API custom_fields: company: Acme call_status: IDLE call_error_reason: null answered: false answer_type: '' attempts_made: 0 do_not_call: false invalid: false invalid_reason: null priority: 0 next_attempt_after: null answered_at: null created_at: '2025-01-15T10:00:00+00:00' updated_at: '2025-01-15T10:00:00+00:00' page_info: total_count: 100 limit: 50 offset: 0 has_next_page: true has_previous_page: false '400': description: >- Bad request. Possible causes: missing or invalid `campaign_id`, invalid campaign global ID format, invalid `limit` (not an integer, less than 1, or greater than 200), or invalid `offset` (not an integer or less than 0). content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: invalidCampaignId: summary: Invalid campaign ID value: message: Invalid campaign ID format invalidLimit: summary: Invalid limit value: message: 'Invalid limit: must be at most 200' invalidOffset: summary: Invalid offset value: message: 'Invalid offset: must be at least 0' '401': description: Authentication failed. Ensure the Bearer token is present and valid. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: Invalid or missing API key '403': description: >- API key disabled, or plan does not include Campaigns API (or white-label API access when using a custom domain). content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: >- API key is disabled or this feature is not available on your plan '404': description: >- Campaign not found, or the campaign does not belong to the tenant for this API key. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: Campaign not found '405': description: Method not allowed. This endpoint only supports GET. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: Method not allowed for this path '429': description: >- Rate limit exceeded (default: 100 requests per minute per API key for this route). content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: Rate limit exceeded. Please try again later. error: RATE_LIMIT_EXCEEDED '500': description: Internal server error. Contact support if this persists. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' example: message: Internal server error error: UnexpectedError components: schemas: GetCampaignLeadsV2Response: type: object required: - leads - page_info properties: leads: type: array items: $ref: '#/components/schemas/VoiceCampaignLeadV2ListItem' page_info: $ref: '#/components/schemas/GetCampaignLeadsV2PageInfo' ErrorMessage: type: object properties: message: type: string VoiceCampaignLeadV2ListItem: type: object description: >- A lead row returned by GET /api/v2/voice-campaigns/{campaign_id}/leads/list properties: id: type: string description: Relay global ID of the campaign lead (`VoiceCampaignLeadType`). phone_number: type: - string - 'null' description: Lead phone number (E.164 when set). first_name: type: - string - 'null' last_name: type: - string - 'null' email: type: - string - 'null' format: email source: type: - string - 'null' description: How the lead was created (e.g. API, MANUAL, IMPORT). custom_fields: type: - object - 'null' additionalProperties: true description: Arbitrary key-value fields for personalisation. call_status: type: string description: Dialer/call state for this lead (e.g. IDLE, in-progress values). call_error_reason: description: >- JSON from the telephony/assistant layer when a call failed. Shape varies by provider. Null when not set. nullable: true answered: type: boolean answer_type: type: string attempts_made: type: integer do_not_call: type: boolean invalid: type: boolean invalid_reason: type: - string - 'null' priority: type: integer next_attempt_after: type: - string - 'null' format: date-time answered_at: type: - string - 'null' format: date-time created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time GetCampaignLeadsV2PageInfo: type: object description: Offset pagination metadata for the list request. required: - total_count - limit - offset - has_next_page - has_previous_page properties: total_count: type: integer description: Total number of leads in the campaign (not just this page). minimum: 0 limit: type: integer description: >- Page size used for this response (same as the `limit` query parameter, or the default). minimum: 1 maximum: 200 offset: type: integer description: >- Number of records skipped from the start (same as the `offset` query parameter, or 0). minimum: 0 has_next_page: type: boolean description: >- True if more leads exist after the current page (use a higher `offset` to fetch them). has_previous_page: type: boolean description: >- True if leads exist before the current page (`offset` greater than 0). securitySchemes: bearerAuth: type: http scheme: bearer ````