> ## Documentation Index > Fetch the complete documentation index at: https://docs.leadvector.app/api-reference/llms.txt > Use this file to discover all available pages before exploring further. # Add or update a lead > Adds one lead to the campaign, or updates one: the lead named by `leadId`, else the lead with this email. Variables are set by name. ## OpenAPI ````yaml /openapi.json post /v1/leads/{uuid} openapi: 3.1.0 info: title: LeadVector API version: '1' description: >- Find and verify business emails and mobile numbers, enrich people and companies, and run your email campaigns, mailboxes and inbox. Send your API key in the `x-api-key` header. servers: - url: https://prod.leadvector.app description: Production security: - access-key: [] tags: - name: Authentication description: Check that an API key works. - name: Lookups description: >- Find business emails and mobile numbers, verify emails, and find the person behind an email. - name: Enrichment description: The full profile of a person or a company. - name: Campaigns description: Email campaigns and their sequences. - name: Leads description: A campaign's leads. - name: Email accounts description: The mailboxes campaigns send from, and their warmup. - name: Inbox description: Replies to your campaigns, in one inbox. - name: Webhooks description: Subscribe URLs to events, and read the events sent. - name: Campaign events description: >- A campaign's lifecycle: created, launched, paused, resumed, stopped, completed, deleted. - name: Lead events description: A lead joining a campaign, replying, being labelled, finishing or failing. - name: Email events description: Each step's email to a lead, sent or failed. - name: Inbox events description: Mail the inbox receives, and the replies and forwards sent from it. - name: Email account events description: A mailbox's connection, pause, cooldown, warmup health and deletion. - name: Lookup events description: >- A single lookup’s result, in the app, the extension or the API: an email or a mobile found, an email verified, a person or a company enriched. - name: Bulk job events description: A bulk job (a file of lookups) completing or failing. - name: List events description: A contact saved to one of the team’s lists. - name: Credit events description: The team’s credits running low, or out. - name: Test event description: The event an endpoint gets when you send it a test. paths: /v1/leads/{uuid}: post: tags: - Leads summary: Add or update a lead description: >- Adds one lead to the campaign, or updates one: the lead named by `leadId`, else the lead with this email. Variables are set by name. operationId: ApiV1LeadController_upsertCampaignLead parameters: - name: uuid required: true in: path description: The campaign's UUID. schema: type: string example: 019f2504-58b8-77ec-9c3f-54f5d6df733e requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertCampaignLeadDto' responses: '201': description: Lead created successfully / Lead updated successfully content: application/json: schema: $ref: '#/components/schemas/UpsertedLeadResponseDto' '400': description: A valid email is required, or the body fails validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseDto' '401': description: API_KEY_REQUIRED / INVALID_API_KEY content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseDto' '403': description: ACCOUNT_DEACTIVATED / TEAM_DEACTIVATED content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseDto' '404': description: Campaign not found / Lead not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseDto' '409': description: >- Stopped campaign cannot accept new leads / Completed campaign cannot accept new leads: a new lead, or a deleted one revived, would join a campaign that is over (an update of an active lead is still accepted). Another lead in this campaign already uses this email: the update would give the lead another lead's address. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseDto' '429': description: RATE_LIMIT_EXCEEDED, with a Retry-After header content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponseDto' security: - access-key: [] components: schemas: UpsertCampaignLeadDto: type: object properties: leadId: type: number example: 42 description: >- Id of an existing lead in this campaign to update. The lead keeps its id and history even when the email changes, and omitted names, company and profile fields are carried over from the lead. Without it the lead is matched by email. email: type: string example: john.doe@example.com firstName: type: string example: John lastName: type: string example: Doe companyName: type: string example: Acme Inc. pauseUntil: type: string example: '2026-06-30T00:00:00.000Z' description: Pause lead processing until this date variables: example: - name: jobTitle value: Software Engineer - name: country value: Pakistan type: array items: $ref: '#/components/schemas/LeadVariableDto' required: - email UpsertedLeadResponseDto: type: object properties: message: type: string description: '`Lead created successfully`, or `Lead updated successfully`.' example: Lead created successfully data: $ref: '#/components/schemas/UpsertedLeadDto' required: - message - data ApiErrorResponseDto: type: object properties: statusCode: type: number example: 401 message: description: >- A code in capitals; the list of messages when the body fails validation; `Internal server error` for a 500. oneOf: - type: string - type: array items: type: string example: INVALID_API_KEY error: type: string description: The status's name. example: Unauthorized traceId: type: string description: Quote it when you contact support. example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f timestamp: type: string example: '2026-11-03T09:41:12.000Z' path: type: string example: /v1/find-email required: - statusCode - message - traceId - timestamp - path RateLimitErrorResponseDto: type: object properties: statusCode: type: number example: 401 message: description: The error's code. oneOf: - type: string - type: array items: type: string example: RATE_LIMIT_EXCEEDED error: type: string description: The status's name. example: Unauthorized traceId: type: string description: Quote it when you contact support. example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f timestamp: type: string example: '2026-11-03T09:41:12.000Z' path: type: string example: /v1/find-email limit: type: number description: Calls allowed per window. example: 10 windowSeconds: type: number example: 60 retryAfterSeconds: type: number description: Seconds until the next call is allowed. example: 6 required: - statusCode - message - traceId - timestamp - path - limit - windowSeconds - retryAfterSeconds LeadVariableDto: type: object properties: name: type: string example: jobTitle description: Variable name value: type: string example: Software Engineer description: Variable value required: - name - value UpsertedLeadDto: type: object properties: id: type: number example: 42 leadStatus: type: string enum: - PENDING - SCHEDULED - PROCESSING - COMPLETED - FAILED - REPLIED - BOUNCED - UNSUBSCRIBED example: PENDING currentStep: type: number example: 1 nextScheduledAt: format: date-time type: - string - 'null' customFields: additionalProperties: true description: The variables given for the lead; null when none were. example: jobTitle: Head of Sales type: - object - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - leadStatus - currentStep - nextScheduledAt - customFields - createdAt - updatedAt securitySchemes: access-key: type: apiKey in: header name: x-api-key description: Your API key, from the API keys page of the app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.