> ## Documentation Index > Fetch the complete documentation index at: https://docs.pineyard.ai/llms.txt > Use this file to discover all available pages before exploring further. # Push a lead > Push one lead into a standing API campaign. Authenticate with a workspace API key. idempotencyKey is REQUIRED: it is the sole dedup key, so the same phone number can be dialed separately for each distributor/device/alert by sending a distinct, retry-stable key per call. Works for both campaign kinds. A CLASSIC campaign dials the lead on its dial ladder; a JOURNEY campaign (one built on a workflow) instead enrolls the lead into a per-lead run of that workflow, and `lead.fields` become the run's trigger fields — readable in the graph as {{start.fields.}}. Send the field names the workflow's trigger contract lists; any key the graph never reads is echoed back in warnings.undeclaredVariables (the lead is still queued). **Required scope:** `campaigns.edit` Scopes apply to scoped API keys. Keys issued without scopes can call every `/v1` endpoint. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/campaigns/{campaignId}/leads openapi: 3.0.3 info: title: Pineyard API version: 1.0.0 description: >- Programmatic access to agents, campaigns, calls, phone numbers, WhatsApp and results in your Pineyard workspace. servers: - url: https://api.pineyard.ai description: Production security: - bearerAuth: [] paths: /v1/campaigns/{campaignId}/leads: post: summary: Push a lead description: >- Push one lead into a standing API campaign. Authenticate with a workspace API key. idempotencyKey is REQUIRED: it is the sole dedup key, so the same phone number can be dialed separately for each distributor/device/alert by sending a distinct, retry-stable key per call. Works for both campaign kinds. A CLASSIC campaign dials the lead on its dial ladder; a JOURNEY campaign (one built on a workflow) instead enrolls the lead into a per-lead run of that workflow, and `lead.fields` become the run's trigger fields — readable in the graph as {{start.fields.}}. Send the field names the workflow's trigger contract lists; any key the graph never reads is echoed back in warnings.undeclaredVariables (the lead is still queued). requestBody: content: application/json: schema: type: object properties: lead: type: object properties: phone: type: string minLength: 1 name: type: string maxLength: 200 fields: type: object additionalProperties: type: string required: - phone idempotencyKey: type: string maxLength: 200 required: - lead responses: '200': description: >- Idempotent replay — same idempotencyKey already queued; no second dial and no second enrollment content: application/json: schema: type: object properties: leadId: type: string status: type: string enum: - queued deduplicated: type: boolean requestId: type: string format: uuid resultUrl: type: string warnings: type: object properties: undeclaredVariables: type: array items: type: string required: - undeclaredVariables required: - leadId - status - deduplicated - requestId '202': description: Lead queued (new call, or enrolled into a new workflow run) content: application/json: schema: type: object properties: leadId: type: string status: type: string enum: - queued deduplicated: type: boolean requestId: type: string format: uuid resultUrl: type: string warnings: type: object properties: undeclaredVariables: type: array items: type: string required: - undeclaredVariables required: - leadId - status - deduplicated - requestId '400': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. - `invalid_body`: The request body (or query) failed validation. Details are in `issues` (or `detail`). `422` on `POST /v1/campaigns/{campaignId}/leads`. '401': description: >- - `invalid_api_key`: The API key is unknown, revoked or expired, or its workspace was deleted. - `unauthorized`: No `Authorization: Bearer` header, or an empty token. '403': description: >- - `api_key_owner_inactive`: The member the key acts for was removed or suspended. - `forbidden`: The key lacks the permission named in `requiredPermission`, or the resource belongs to another workspace. - `workspace_pending_approval`: The workspace has not been approved yet. - `workspace_suspended`: The workspace is suspended. '404': description: '- `campaign_not_found`: No campaign with that id in this workspace.' '409': description: >- - `campaign_not_accepting`: The campaign is not a running API campaign. Returned as `{"code": "campaign_not_accepting", "reason": …}`; `reason` is `not_api` or the campaign status. '413': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '422': description: >- - `idempotency_key_required`: A billed endpoint was called without an `Idempotency-Key` header (`400`), or a `/v1` lead push without `idempotencyKey` in the body (`422`). - `invalid_body`: The request body (or query) failed validation. Details are in `issues` (or `detail`). `422` on `POST /v1/campaigns/{campaignId}/leads`. - `invalid_phone`: Phone number could not be normalised. '429': description: >- - `journey_campaign_live_cap`: Journey campaign has too many leads pending or in flight. - `rate_limited`: Too many requests. '500': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '502': description: >- - `provider_error`: The calling service rejected the request (`upstreamStatus` 4xx) or was unavailable (5xx). '503': description: '- `database_unavailable`: The service is temporarily unavailable.' components: securitySchemes: bearerAuth: type: http scheme: bearer description: Your API key, e.g. `pk_live_xxxxxxxxxxxxxxxxxxxxxxxx`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.