> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create lead in a lead list > Create a lead and assign it to the specified list. Provide `idempotency_key` to make retries safe, duplicate POSTs return the original lead. This operation can change workspace data or trigger an external side effect; review the request before sending it and do not retry blindly after a timeout. ## OpenAPI ````yaml /openapi.json post /api/v1/public/lead-lists/{list_id}/leads openapi: 3.1.0 info: description: >- Customer-facing API for managing outreach, leads, conversations, voice agents, knowledge bases, analytics, and webhooks. title: Sendora Public API version: 1.0.0 servers: - description: Production url: https://api.sendora.ai security: [] tags: - description: Build, launch, pause and stop campaigns, and enroll leads. name: Campaigns - description: Create, update, tag, enrich and import leads. name: Leads - description: Group leads into reusable lists. name: Lead lists - description: Find new prospects and research existing leads. name: Prospecting - description: Read conversations and send messages to leads. name: Inbox - description: Manage workspace-wide suppressions. name: Do not contact - description: Manage the content your agents answer from. name: Knowledge bases - description: Create, configure, test and publish voice agents. name: Voice agents - description: Give agents actions such as booking, lookups and transfers. name: Agent tools - description: Embed a voice agent on your website. name: Voice widgets - description: Start voice calls and read call results. name: Calls - description: Browse and preview the voices an agent can use. name: Voices - description: List numbers, bring your own, and route calls. name: Phone numbers - description: List the channel accounts connected to the workspace. name: Connected accounts - description: Register endpoints and review deliveries. name: Webhooks - description: Drive the workspace assistant programmatically. name: Copilot - description: Read workspace and campaign performance. name: Analytics - description: Track asynchronous operations. name: Jobs - description: Manage client workspaces, plans and branding. name: Agency paths: /api/v1/public/lead-lists/{list_id}/leads: post: tags: - Lead lists summary: Create lead in a lead list description: >- Create a lead and assign it to the specified list. Provide `idempotency_key` to make retries safe, duplicate POSTs return the original lead. This operation can change workspace data or trigger an external side effect; review the request before sending it and do not retry blindly after a timeout. operationId: public_create_lead_in_list_api_v1_public_lead_lists__list_id__leads_post parameters: - description: >- The lead list's id: the `id` from List lead lists. It is also the last part of that page's address in the app. in: path name: list_id required: true schema: title: List Id type: string - in: header name: X-API-Key required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - in: header name: Authorization required: false schema: anyOf: - type: string - type: 'null' title: Authorization requestBody: content: application/json: schema: $ref: '#/components/schemas/LeadCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/LeadOut' description: Successful Response '401': description: The X-API-Key header is missing, invalid, expired, or revoked. '402': description: >- The workspace is suspended for billing, or the request would exceed a plan or usage limit. '403': description: >- The key is valid but lacks the required scope, or the workspace has no active plan, lacks the entitlement, or has this feature turned off or view-only. '404': description: >- The resource does not exist or is not owned by the authenticated workspace. '410': description: The workspace behind this key has been deleted. '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '500': description: >- An unexpected Sendora error occurred. Retry only if the operation is safe to repeat. '503': description: >- An entitlement or billing check is temporarily unavailable. Retry after the Retry-After interval. security: - ApiKeyAuth: [] x-codeSamples: - label: cURL lang: bash source: >- curl -X POST 'https://api.sendora.ai/api/v1/public/lead-lists/YOUR_ID/leads' -H "X-API-Key: $SENDORA_API_KEY" -H "Content-Type: application/json" \ -d '{"company":"example","custom_fields":{},"email":"example"}' - label: Python lang: python source: >- import requests url = 'https://api.sendora.ai/api/v1/public/lead-lists/YOUR_ID/leads' headers = {'X-API-Key': '$SENDORA_API_KEY'} response = requests.post(url, headers=headers, json={'company': 'example', 'custom_fields': {}, 'email': 'example'}) response.raise_for_status() print(response.json()) - label: JavaScript lang: javascript source: >- const response = await fetch("https://api.sendora.ai/api/v1/public/lead-lists/YOUR_ID/leads", { method: "POST", headers: { 'X-API-Key': process.env.SENDORA_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({"company": "example", "custom_fields": {}, "email": "example"}), }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); - label: Go lang: go source: >- req, err := http.NewRequest("POST", "https://api.sendora.ai/api/v1/public/lead-lists/YOUR_ID/leads", bytes.NewBufferString(`{"company": "example", "custom_fields": {}, "email": "example"}`)) if err != nil { log.Fatal(err) } req.Header.Set("X-API-Key", os.Getenv("SENDORA_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() components: schemas: LeadCreate: properties: company: anyOf: - maxLength: 300 type: string - type: 'null' description: Company returned by the Sendora API. title: Company custom_fields: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Up to 50 custom scalar fields; keys are limited to 64 characters and string values to 2,000 characters. title: Custom Fields email: anyOf: - maxLength: 320 type: string - type: 'null' description: Email returned by the Sendora API. title: Email first_name: anyOf: - maxLength: 200 type: string - type: 'null' description: First name returned by the Sendora API. title: First Name idempotency_key: anyOf: - maxLength: 128 type: string - type: 'null' description: Idempotency key returned by the Sendora API. title: Idempotency Key last_name: anyOf: - maxLength: 200 type: string - type: 'null' description: Last name returned by the Sendora API. title: Last Name lead_list_id: anyOf: - maxLength: 128 type: string - type: 'null' description: 'A lead list''s id: the `id` from List lead lists.' title: Lead List Id linkedin_url: anyOf: - maxLength: 500 type: string - type: 'null' description: Linkedin url returned by the Sendora API. title: Linkedin Url notes: anyOf: - maxLength: 10000 type: string - type: 'null' description: Notes returned by the Sendora API. title: Notes phone_number: anyOf: - maxLength: 40 type: string - type: 'null' description: Phone number returned by the Sendora API. title: Phone Number pipeline_stage: anyOf: - $ref: '#/components/schemas/PipelineStage-Input' - type: 'null' description: Pipeline stage returned by the Sendora API. title: anyOf: - maxLength: 300 type: string - type: 'null' description: Title returned by the Sendora API. title: Title required: [] title: LeadCreate type: object LeadOut: properties: automation_paused: default: false description: Automation paused returned by the Sendora API. title: Automation Paused type: boolean avatar_url: anyOf: - type: string - type: 'null' description: Avatar url returned by the Sendora API. title: Avatar Url city: anyOf: - type: string - type: 'null' description: City returned by the Sendora API. title: City company: anyOf: - type: string - type: 'null' description: Company returned by the Sendora API. title: Company company_domain: anyOf: - type: string - type: 'null' description: Company domain returned by the Sendora API. title: Company Domain country: anyOf: - type: string - type: 'null' description: Country returned by the Sendora API. title: Country created_at: description: Created at returned by the Sendora API. format: date-time title: Created At type: string current_campaign_id: anyOf: - type: string - type: 'null' description: >- The campaign this lead is currently enrolled in: an `id` from List campaigns. title: Current Campaign Id custom_fields: anyOf: - additionalProperties: true type: object - type: 'null' description: Custom fields returned by the Sendora API. title: Custom Fields email: anyOf: - type: string - type: 'null' description: Email returned by the Sendora API. title: Email email_verification_score: anyOf: - type: integer - type: 'null' description: Email verification score returned by the Sendora API. title: Email Verification Score email_verification_status: anyOf: - type: string - type: 'null' description: Email verification status returned by the Sendora API. title: Email Verification Status email_verified_at: anyOf: - format: date-time type: string - type: 'null' description: Email verified at returned by the Sendora API. title: Email Verified At enrich_signals: anyOf: - additionalProperties: true type: object - type: 'null' description: Enrich signals returned by the Sendora API. title: Enrich Signals first_name: anyOf: - type: string - type: 'null' description: First name returned by the Sendora API. title: First Name id: description: The lead's id. Pass it to any endpoint that takes `lead_id`. title: Id type: string industry: anyOf: - type: string - type: 'null' description: Industry returned by the Sendora API. title: Industry last_activity_at: anyOf: - format: date-time type: string - type: 'null' description: Last activity at returned by the Sendora API. title: Last Activity At last_name: anyOf: - type: string - type: 'null' description: Last name returned by the Sendora API. title: Last Name lead_list_id: anyOf: - type: string - type: 'null' description: 'A lead list''s id: the `id` from List lead lists.' title: Lead List Id linkedin_url: anyOf: - type: string - type: 'null' description: Linkedin url returned by the Sendora API. title: Linkedin Url notes: anyOf: - type: string - type: 'null' description: Notes returned by the Sendora API. title: Notes phone_number: anyOf: - type: string - type: 'null' description: Phone number returned by the Sendora API. title: Phone Number pipeline_stage: anyOf: - $ref: '#/components/schemas/api__v1__leads__schemas__PipelineStage' - type: 'null' description: Pipeline stage returned by the Sendora API. source: anyOf: - type: string - type: 'null' description: Source returned by the Sendora API. title: Source status: $ref: '#/components/schemas/LeadStatus' description: Status returned by the Sendora API. title: anyOf: - type: string - type: 'null' description: Title returned by the Sendora API. title: Title traffic_light_status: anyOf: - $ref: '#/components/schemas/TrafficLightStatus' - type: 'null' description: Traffic light status returned by the Sendora API. website: anyOf: - type: string - type: 'null' description: Website returned by the Sendora API. title: Website required: - id - status - created_at title: LeadOut type: object HTTPValidationError: properties: detail: description: Detail returned by the Sendora API. items: $ref: '#/components/schemas/ValidationError' title: Detail type: array required: [] title: HTTPValidationError type: object PipelineStage-Input: enum: - new - contacted - engaged - meeting_booked - meeting_scheduled - proposal_sent - closed_won - closed_lost title: PipelineStage type: string api__v1__leads__schemas__PipelineStage: enum: - new - contacted - engaged - meeting_booked - meeting_scheduled - proposal_sent - closed_won - closed_lost title: PipelineStage type: string LeadStatus: enum: - active - unsubscribed - dnc - bounced title: LeadStatus type: string TrafficLightStatus: enum: - GREEN - YELLOW - RED title: TrafficLightStatus type: string ValidationError: properties: loc: description: Loc returned by the Sendora API. items: anyOf: - type: string - type: integer title: Location type: array msg: description: Msg returned by the Sendora API. title: Message type: string type: description: Type returned by the Sendora API. title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: ApiKeyAuth: description: Customer API key created in the Sendora dashboard. in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.