> ## 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. # Create a campaign > Creates a campaign in `DRAFT`. Pass `uploadId` to import contacts from a CSV uploaded with `POST /campaigns/uploads`. See [Run a campaign end to end](/guides/run-a-campaign). **Required scope:** `campaigns.edit` ## OpenAPI ````yaml /api-reference/openapi.json post /campaigns 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: /campaigns: post: summary: Create a campaign description: >- Creates a campaign in `DRAFT`. Pass `uploadId` to import contacts from a CSV uploaded with `POST /campaigns/uploads`. See [Run a campaign end to end](/guides/run-a-campaign). requestBody: content: application/json: schema: anyOf: - type: object properties: name: type: string maxLength: 100 default: '' description: type: string maxLength: 280 reservedConcurrency: type: integer minimum: 1 maximum: 10 variableMap: type: object additionalProperties: type: string countryCode: type: string pattern: ^\+\d{1,3}$ phoneColumn: type: string altPhoneColumns: type: array items: type: string minLength: 1 maxItems: 5 nameColumn: type: string firstNameColumn: type: string lastNameColumn: type: string removeInvalidRows: type: boolean transliterateCalleeNames: type: boolean timezone: type: string scheduledStartAt: type: string format: date-time scheduledEndAt: type: string format: date-time dailyWindowStart: type: string pattern: ^\d{2}:\d{2}$ dailyWindowEnd: type: string pattern: ^\d{2}:\d{2}$ retryCount: type: integer minimum: 0 maximum: 10 cooldownMinutes: type: integer minimum: 5 maximum: 43200 retryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 43200 maxItems: 10 retryConcurrencyPercent: type: integer nullable: true minimum: 0 maximum: 100 notificationUserIds: type: array items: type: string campaignTypeId: type: string customExtractionKeys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description maxItems: 40 defaultCrmConnectionId: type: string defaultCrmSegmentId: type: string followupEnabled: type: boolean followupMaxAttempts: type: integer minimum: 1 maximum: 10 churnEnabled: type: boolean churnMaxAttempts: type: integer minimum: 1 maximum: 10 churnIntervalHours: type: integer minimum: 1 maximum: 2160 churnDelaysHours: type: array items: type: integer minimum: 1 maximum: 2160 maxItems: 10 goal: type: string nullable: true maxLength: 500 briefText: type: string nullable: true maxLength: 200000 briefFileName: type: string nullable: true maxLength: 255 incompleteRetryEnabled: type: boolean incompleteRetryMaxAttempts: type: integer minimum: 1 maximum: 5 incompleteRetryIntervalMinutes: type: integer minimum: 1 maximum: 1440 incompleteRetryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 1440 maxItems: 5 incompleteCallSeconds: type: integer minimum: 5 maximum: 300 referralMaxDepth: type: integer minimum: 0 maximum: 3 skipRetryOnFirstVoicemail: type: boolean messageRetryEnabled: type: boolean messageRetryMaxAttempts: type: integer minimum: 1 maximum: 10 messageRetryIntervalSeconds: type: integer minimum: 1 maximum: 604800 messageRetryDelaysSeconds: type: array items: type: integer minimum: 1 maximum: 604800 maxItems: 10 messageRetryWindowSeconds: type: integer minimum: 1 maximum: 2592000 messageRetryTieredEnabled: type: boolean messageRetryTransientMaxAttempts: type: integer minimum: 1 maximum: 100 autoReseedEnabled: type: boolean channel: type: string enum: - VOICE - WHATSAPP - VOICE_THEN_WHATSAPP - WHATSAPP_THEN_VOICE - CUSTOM - EMAIL whatsappOutreachTemplateId: type: string nullable: true whatsappTemplateByMetric: anyOf: - type: object properties: key: type: string minLength: 1 maxLength: 120 map: type: object additionalProperties: type: string minLength: 1 maxLength: 64 required: - key - map - type: object properties: {} additionalProperties: false messageDeclinedLeads: type: boolean outreachRules: type: array nullable: true items: type: object properties: trigger: type: string enum: - MESSAGE_REPLY - NO_REPLY_AFTER - CALL_ENDED afterDays: type: integer minimum: 1 maximum: 90 condition: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values conditions: type: array items: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values minItems: 1 maxItems: 5 match: type: string enum: - ALL - ANY default: ALL action: type: string enum: - HAND_OFF - STOP - MARK_INTERESTED default: HAND_OFF required: - trigger maxItems: 20 dailyDialCap: type: integer nullable: true minimum: 1 maximum: 100000 dailyMessageCap: type: integer nullable: true minimum: 1 maximum: 100000 dialDays: type: array items: type: integer minimum: 0 maximum: 6 minItems: 1 maxItems: 7 evaluationMetrics: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ label: type: string minLength: 1 maxLength: 60 allowedValues: type: array items: type: string minLength: 1 maxLength: 40 minItems: 2 maxItems: 24 prompt: type: string minLength: 1 maxLength: 5000 builtin: type: boolean required: - key - label - allowedValues - prompt maxItems: 12 applyAgentDefaults: type: boolean source: type: string enum: - INBOUND phoneNumberId: type: string format: uuid agentId: type: string minLength: 1 activate: type: boolean required: - source - phoneNumberId additionalProperties: false - type: object properties: name: type: string maxLength: 100 default: '' description: type: string maxLength: 280 reservedConcurrency: type: integer minimum: 1 maximum: 10 variableMap: type: object additionalProperties: type: string countryCode: type: string pattern: ^\+\d{1,3}$ phoneColumn: type: string altPhoneColumns: type: array items: type: string minLength: 1 maxItems: 5 nameColumn: type: string firstNameColumn: type: string lastNameColumn: type: string removeInvalidRows: type: boolean transliterateCalleeNames: type: boolean timezone: type: string scheduledStartAt: type: string format: date-time scheduledEndAt: type: string format: date-time dailyWindowStart: type: string pattern: ^\d{2}:\d{2}$ dailyWindowEnd: type: string pattern: ^\d{2}:\d{2}$ retryCount: type: integer minimum: 0 maximum: 10 cooldownMinutes: type: integer minimum: 5 maximum: 43200 retryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 43200 maxItems: 10 retryConcurrencyPercent: type: integer nullable: true minimum: 0 maximum: 100 notificationUserIds: type: array items: type: string campaignTypeId: type: string customExtractionKeys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description maxItems: 40 defaultCrmConnectionId: type: string defaultCrmSegmentId: type: string followupEnabled: type: boolean followupMaxAttempts: type: integer minimum: 1 maximum: 10 churnEnabled: type: boolean churnMaxAttempts: type: integer minimum: 1 maximum: 10 churnIntervalHours: type: integer minimum: 1 maximum: 2160 churnDelaysHours: type: array items: type: integer minimum: 1 maximum: 2160 maxItems: 10 goal: type: string nullable: true maxLength: 500 briefText: type: string nullable: true maxLength: 200000 briefFileName: type: string nullable: true maxLength: 255 incompleteRetryEnabled: type: boolean incompleteRetryMaxAttempts: type: integer minimum: 1 maximum: 5 incompleteRetryIntervalMinutes: type: integer minimum: 1 maximum: 1440 incompleteRetryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 1440 maxItems: 5 incompleteCallSeconds: type: integer minimum: 5 maximum: 300 referralMaxDepth: type: integer minimum: 0 maximum: 3 skipRetryOnFirstVoicemail: type: boolean messageRetryEnabled: type: boolean messageRetryMaxAttempts: type: integer minimum: 1 maximum: 10 messageRetryIntervalSeconds: type: integer minimum: 1 maximum: 604800 messageRetryDelaysSeconds: type: array items: type: integer minimum: 1 maximum: 604800 maxItems: 10 messageRetryWindowSeconds: type: integer minimum: 1 maximum: 2592000 messageRetryTieredEnabled: type: boolean messageRetryTransientMaxAttempts: type: integer minimum: 1 maximum: 100 autoReseedEnabled: type: boolean channel: type: string enum: - VOICE - WHATSAPP - VOICE_THEN_WHATSAPP - WHATSAPP_THEN_VOICE - CUSTOM - EMAIL whatsappOutreachTemplateId: type: string nullable: true whatsappTemplateByMetric: anyOf: - type: object properties: key: type: string minLength: 1 maxLength: 120 map: type: object additionalProperties: type: string minLength: 1 maxLength: 64 required: - key - map - type: object properties: {} additionalProperties: false messageDeclinedLeads: type: boolean outreachRules: type: array nullable: true items: type: object properties: trigger: type: string enum: - MESSAGE_REPLY - NO_REPLY_AFTER - CALL_ENDED afterDays: type: integer minimum: 1 maximum: 90 condition: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values conditions: type: array items: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values minItems: 1 maxItems: 5 match: type: string enum: - ALL - ANY default: ALL action: type: string enum: - HAND_OFF - STOP - MARK_INTERESTED default: HAND_OFF required: - trigger maxItems: 20 dailyDialCap: type: integer nullable: true minimum: 1 maximum: 100000 dailyMessageCap: type: integer nullable: true minimum: 1 maximum: 100000 dialDays: type: array items: type: integer minimum: 0 maximum: 6 minItems: 1 maxItems: 7 evaluationMetrics: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ label: type: string minLength: 1 maxLength: 60 allowedValues: type: array items: type: string minLength: 1 maxLength: 40 minItems: 2 maxItems: 24 prompt: type: string minLength: 1 maxLength: 5000 builtin: type: boolean required: - key - label - allowedValues - prompt maxItems: 12 applyAgentDefaults: type: boolean agentId: type: string minLength: 1 phoneNumberId: type: string format: uuid uploadId: type: string workflowId: type: string format: uuid source: type: string enum: - CSV - CRM_MANUAL - CRM_WEBHOOK - API responses: '201': description: Created content: application/json: schema: type: object properties: campaignId: type: string contactsAdded: type: number contactsSkipped: type: number skippedReasons: type: array items: type: string required: - campaignId - contactsAdded - contactsSkipped - skippedReasons '400': description: >- - `campaign_type_not_found`: campaignTypeId does not exist or is not ACTIVE. - `crm_connection_not_found`: CRM connection not found (400 on campaign create: missing or not ACTIVE; 404 on CRM routes). - `default_crm_connection_required`: CRM_WEBHOOK campaign created without defaultCrmConnectionId. - `inbound_agent_has_many_numbers`: Inbound agent has several numbers and none was specified. - `inbound_agent_has_no_number`: Inbound agent chosen but no number routes to it. - `inbound_campaign_action_not_supported`: Operation is not valid for INBOUND campaigns (uploads, pause/resume/restart, source switch, re-engage, remessage, outreach). - `inbound_did_has_no_agent`: The number has no ACTIVE INBOUND agent assigned. - `inbound_did_unavailable`: Inbound campaign's phone number is missing, not assigned to this workspace, or its carrier is disabled. - `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`. - `journey_campaign_contact_cap`: Too many contacts for a journey campaign. - `journey_campaign_source_unsupported`: Journey (workflow) campaigns only support CSV or API sources. - `metric_key_collision`: A metric key collides with an extraction field name. - `reserved_extraction_key`: A custom extraction key uses a built-in signal name (key field included on the dashboard route). - `reserved_metric_key`: An evaluation metric key uses a built-in signal name. '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_not_allowed`: This action needs a person signed in to the dashboard (sign-ins, payments, email, and similar). - `api_key_not_scoped`: A key issued without scopes was used outside `/v1`. - `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: >- - `agent_not_found`: Agent id missing or not in this workspace (400 on POST /v1/campaigns, inbound-number assignment and suggest routes). - `upload_not_found_or_expired`: The `uploadId` is unknown or expired. On some endpoints currently returned as `internal_error`. - `workflow_not_found`: No workflow with that id (or workflows not enabled). '409': description: >- - `inbound_did_already_in_campaign`: The number already belongs to a non-terminal inbound campaign. - `workflow_not_active`: Workflow is not ACTIVE (not published or archived). '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: >- - `excel_mangled_phone`: Phone column contains scientific-notation numbers (Excel lost the digits). '429': description: '- `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.