> ## Documentation Index > Fetch the complete documentation index at: https://docs.journeybee.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Leads > Retrieve a list of leads for a company with advanced filtering, sorting, and pagination support ## Authentication ```bash cURL theme={null} curl -X GET "https://app.journeybee.io/api/v1/leads?userId={userId}" \ -H "Authorization: Bearer your-api-key-uuid" \ -H "Content-Type: application/json" ``` ```javascript JavaScript theme={null} const response = await fetch('https://app.journeybee.io/api/v1/leads?userId={userId}', { method: 'GET', headers: { 'Authorization': 'Bearer your-api-key-uuid', 'Content-Type': 'application/json' } }); ``` ## Query Parameters The ID of the user making the request (for authorization) Pagination cursor (ISO timestamp) for fetching the next set of results Search leads by company name, email, phone, first name, last name, assigned users, or partner companies Filter by lead source/type. Options: `received`, `sent`, `reseller`, `campaigns` Filter by assignment status. Use `1` to show only assigned leads Filter by assignment status. Use `1` to show only unassigned leads Comma-separated list of lead statuses to filter by. Options: `new`, `contacted`, `qualified`, `converted`, `lost` Comma-separated list of tag IDs to filter by Comma-separated list of user IDs to filter by assigned users JSON string of custom field filters with format: `[{"id": 123, "value": {"text": "search"}}]` JSON string of sort options with format: `[{"type": "status", "asc": true}]`. Types: `status` ## Response Schema Array of lead objects Total number of leads matching the query Lead ID Lead UUID Lead creation timestamp Lead last update timestamp Lead source: `manual`, `campaign`, `partnership`, `integration`, `form` Lead company name Lead contact email Lead contact phone number Lead contact first name Lead contact last name Lead status: `new`, `contacted`, `qualified`, `converted`, `lost` Partner relationship type: `referral`, `reseller`, `null` Company ID that owns this lead ID of user who created this lead Campaign ID if lead came from a campaign Campaign name if lead came from a campaign Array of assigned tags Tag ID Tag label Tag background color Tag text color Array of assigned users User ID User email User first name User last name User color Profile image asset ID Profile image asset UUID Array of partnership information (for sent/received leads) Partnership lead ID Partnership creation timestamp Partnership ID Sending company ID Sending company name Sending company logo asset ID Sending company logo asset UUID Receiving company ID Receiving company name Receiving company logo asset ID Receiving company logo asset UUID Partnership type: `referral`, `reseller` Direction from perspective: `sent`, `received` Partner fallback data for inactive partners Array of campaign partner information (for campaign leads) Partner company ID Partner company name Partner company logo asset ID Partner company logo asset UUID Array of associated deals Deal ID Deal name Deal value Currency code for deal value Deal stage ID Deal stage label Deal stage series (order) Deal stage phase ## Example Request ```bash cURL theme={null} curl -X GET "https://app.journeybee.io/api/v1/leads?userId=456&view=received&search=tech&status=new,contacted" \ -H "Authorization: Bearer jb_api_1234567890abcdef" \ -H "Content-Type: application/json" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ userId: '456', view: 'received', search: 'tech', status: 'new,contacted' }); const response = await fetch( `https://app.journeybee.io/api/v1/leads?${params}`, { method: 'GET', headers: { 'Authorization': 'Bearer jb_api_1234567890abcdef', 'Content-Type': 'application/json' } } ); const leads = await response.json(); ``` ## Example Response ```json Example Response theme={null} [ { "total": 1, "id": 789, "uuid": "lead-uuid-789", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T12:45:00Z", "source": "partnership", "company_name": "TechCorp Solutions", "email": "contact@techcorp.com", "phone_number": "+1-555-123-4567", "first_name": "John", "last_name": "Smith", "status": "new", "partner_type": "referral", "company_id": 123, "created_by_user_id": 456, "campaign_id": null, "campaign_title": null, "tags": [ { "id": 10, "label": "High Priority", "background_color": "#EF4444", "text_color": "#FFFFFF" } ], "assigned_users": [ { "id": 456, "email": "jane@company.com", "first_name": "Jane", "last_name": "Doe", "color": "#3B82F6", "profile_image_id": 789, "profile_image_uuid": "profile-uuid-456" } ], "partnership_leads": [ { "id": 123, "created_at": "2024-01-15T10:30:00Z", "partnership_id": 456, "sent_by_company_id": 234, "sent_by_company_name": "Partner Corp", "sent_by_company_logo_id": 567, "sent_by_company_logo_uuid": "logo-uuid-567", "received_by_company_id": 123, "received_by_company_name": "Your Company", "received_by_company_logo_id": 890, "received_by_company_logo_uuid": "logo-uuid-890", "partner_type": "referral", "direction": "received", "fallback_data": null } ], "campaign_partners": [], "lead_deals": [ { "id": 345, "label": "TechCorp Deal", "deal_value": 50000, "currency_code": "USD", "stage_id": 2, "stage_label": "Proposal", "stage_series": 2, "stage_phase": "negotiation" } ] } ] ``` ## Error Responses ```json 401 Unauthorized theme={null} { "error": "Invalid API key or insufficient permissions" } ``` ```json 403 Forbidden theme={null} { "error": "Read access required for this operation" } ``` ```json 404 Not Found theme={null} { "error": "Company not found or user not authorized" } ``` ## Notes * Requires API key with `read_access` permission * User ID must match the authenticated user * Results are paginated using cursor-based pagination (timestamp-based)