> ## Documentation Index > Fetch the complete documentation index at: https://docs.paubox.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription > Subscribes an existing subscriber to an existing subscription list. Creating a subscription fires any drip campaign configured with a `subscription_created` trigger on that list. A subscriber may only be subscribed to a given list once; a duplicate request fails validation. **Note on `subscriber_id`:** this field takes the subscriber's internal numeric ID, not the UUID returned by the subscriber endpoints. To add a subscriber to a list by UUID, use [`POST /subscribers`](/marketing/subscribers/create) with a `subscription_list_id`, or [`POST /subscriptions/subscribe`](/marketing/subscriptions/subscribe) to re-subscribe an existing subscription. **Example curl command:** ```bash curl -X POST \ https://api.paubox.com/v1/marketing/subscriptions \ -H 'authorization: Token token=YOUR_API_KEY' \ -H 'content-type: application/json' \ -d '{ "subscription": { "subscription_list_id": "123e4567-e89b-12d3-a456-426614174000", "subscriber_id": 4821 } }' ``` ## OpenAPI ````yaml openapi2 POST /subscriptions openapi: 3.0.3 info: title: Paubox Marketing API description: > Public documentation Paubox Marketing API. All Paubox Marketing customers have access to the Paubox Marketing API to automate various tasks. ## Authentication Use the authorization header in requests with the format: `authorization: Token token=` Replace `` with your API key. Find your API key in the address bar from the email builder (note: each API Key is displayed only once upon creation). ## Base URL `https://api.paubox.com/v1/marketing` contact: name: Paubox Support url: https://www.paubox.com version: 1.0.0 servers: - url: https://api.paubox.com/v1/marketing description: Production server security: - TokenAuth: [] tags: - name: subscribers description: Subscriber management operations - name: analytics description: Campaign analytics and reporting operations - name: campaign_mailings description: Campaign mailing management and sending operations - name: drip_campaigns description: Drip campaign management and automation operations - name: subscription_lists description: Subscription list management operations - name: subscriptions description: Subscriber opt-in and opt-out operations - name: tracking_links description: Tracking link analytics and data operations paths: /subscriptions: post: tags: - subscriptions summary: Create a subscription description: > Subscribes an existing subscriber to an existing subscription list. Creating a subscription fires any drip campaign configured with a `subscription_created` trigger on that list. A subscriber may only be subscribed to a given list once; a duplicate request fails validation. **Note on `subscriber_id`:** this field takes the subscriber's internal numeric ID, not the UUID returned by the subscriber endpoints. To add a subscriber to a list by UUID, use [`POST /subscribers`](/marketing/subscribers/create) with a `subscription_list_id`, or [`POST /subscriptions/subscribe`](/marketing/subscriptions/subscribe) to re-subscribe an existing subscription. **Example curl command:** ```bash curl -X POST \ https://api.paubox.com/v1/marketing/subscriptions \ -H 'authorization: Token token=YOUR_API_KEY' \ -H 'content-type: application/json' \ -d '{ "subscription": { "subscription_list_id": "123e4567-e89b-12d3-a456-426614174000", "subscriber_id": 4821 } }' ``` operationId: createSubscription requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' example: subscription: subscription_list_id: 123e4567-e89b-12d3-a456-426614174000 subscriber_id: 4821 required: true responses: '200': description: >- Subscription created. If validation fails the response is still `200` but the body contains an `errors` array instead of `data`. content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionResponse' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateSubscriptionRequest: type: object properties: subscription: $ref: '#/components/schemas/CreateSubscriptionRequest_subscription' CreateSubscriptionResponse: type: object description: >- Returned with HTTP 200 in both the success and the validation-failure case. Check for the presence of `errors`. properties: data: $ref: '#/components/schemas/Subscription' errors: type: array description: Validation messages, present only when the create failed items: type: string CreateSubscriptionRequest_subscription: required: - subscriber_id - subscription_list_id type: object properties: subscription_list_id: type: string description: UUID of the subscription list to subscribe to subscriber_id: type: integer description: >- Internal numeric identifier of the subscriber. This is not the subscriber UUID returned by the subscriber endpoints. Subscription: type: object properties: id: type: integer description: Internal numeric identifier for the subscription uuid: type: string description: >- Public identifier for the subscription. Use this value as `subscription_id` in path parameters. subscription_list_id: type: string nullable: true description: >- UUID of the subscription list. Null when the subscription belongs to a dynamic list. dynamic_list_id: type: integer nullable: true description: >- Identifier of the dynamic list. Null when the subscription belongs to a subscription list. subscriber_id: type: integer description: Internal numeric identifier of the subscriber unsubscribed_at: type: string format: date-time nullable: true description: >- When the subscriber opted out of this list. Null while the subscription is active. delete_at: type: string format: date-time nullable: true description: When the subscription is scheduled for deletion created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: string description: Error message code: type: string description: Error code details: type: object description: Additional error details responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: TokenAuth: type: apiKey description: >- Token-based authentication. Use format: "Token token=" where is your API key name: authorization in: header ````