> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # Create campaign > Use this endpoint to create a new Campaign under an Account. When created via the API, the Campaign is automatically assigned the Account's default Billing Method. ###### Required fields: - `name` - display name of the Campaign (must be unique within the Company) - `accountId` - the Account this Campaign belongs to - `customization` - Gift Customization configuration (`giftProperties`, `notificationPolicy`, optionally `recipientExperience`) ###### Optional parameters: - `companyId` query parameter - Company identifier, when not inferable from the API key context - `Request-Source` header - source of the request (`api_native`, `api_zapier`, `api_salesforce`, `api_ftp`, `api_make`) ###### Behavior Notes: - Returns `201` with the new Campaign on success. - Campaigns created via the API are always created with `type: oneOffs`. Other Campaign types (`anniversary`, `birthday`, `schedule`, `marketing`, `newHire`) can only be created through the Snappy Dashboard. - Returns `409` when a Campaign with the same name already exists in the Company. - Returns `422` for business-rule violations (e.g. invalid Collection/Product reference, conflicting customization). #### Permissions - Requires: `campaigns:create` ## OpenAPI ````yaml post /v2/campaigns openapi: 3.0.0 info: title: Snappy Public API version: 2.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. In just 3 simple steps you can start sending gifts today: pull the relevant campaign, send gifts to your recipients and track gift statuses. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Authentication description: >- API keys authenticate requests to the Snappy API. Use these endpoints to list active keys for your Company, create new keys, or delete keys you no longer need. - name: Accounts description: >- An **Account** is a sub-entity that lives within a **Company**. Accounts are used to separate and organize your company's campaigns and gift sends for different teams, departments or budget owners. - name: Campaigns description: >- A **Campaign** is the primary organizational object used to configure and send a batch of gifts. It acts as a template for all the settings of a single gifting initiative, including the target **Recipient** list, the selected **Collection** or **product**, the budget, branding, and notification messages. - name: Collections description: >- A **Collection** is a curated catalog of gift items tailored to a specific theme, budget range, and audience (e.g., "Birthday Gifts Under $50"). The gift recipient then chooses their preferred item directly from this collection. Use these endpoints to: - Get available collections based on budget and country requirements - Retrieve budget ranges for specific collections - Access collection details and products Please note: Swag collections can only be retrieved by specifying the accountId in the request. - name: Products & Variants description: >- Use these endpoints to search for and retrieve products and variants (including by collection and budget), and to list product tags for building catalog and filtering experiences in your UI. - name: Gifts description: >- A **Gift** is the core transactional object in the Snappy system. It represents the entire gifting experience for a **Recipient** within a **Campaign**, from initial creation to final delivery. The **Gift** object tracks the status and details through each stage of its lifecycle: 1. **Creation:** The gift is initiated and associated with a recipient and campaign. 2. **Notification:** The recipient is notified about their gift via email or other channels. 3. **Selection:** The recipient selects a specific product from the gift collection (if applicable). 4. **Order Generation:** An order is created based on the selected product and the recipient's shipping address. 5. **Delivery:** The physical product is shipped and its delivery status is tracked to completion. - name: Orders description: >- Endpoints for programmatically claiming gifts (ordering on behalf of recipients), cancelling orders before they ship, and validating or autocompleting shipping addresses as part of your checkout or fulfillment flow. - name: Recipients description: A **Recipient** is the end-user who receives a **Gift**. paths: /v2/campaigns: post: tags: - Campaigns summary: Create campaign description: >- Use this endpoint to create a new Campaign under an Account. When created via the API, the Campaign is automatically assigned the Account's default Billing Method. ###### Required fields: - `name` - display name of the Campaign (must be unique within the Company) - `accountId` - the Account this Campaign belongs to - `customization` - Gift Customization configuration (`giftProperties`, `notificationPolicy`, optionally `recipientExperience`) ###### Optional parameters: - `companyId` query parameter - Company identifier, when not inferable from the API key context - `Request-Source` header - source of the request (`api_native`, `api_zapier`, `api_salesforce`, `api_ftp`, `api_make`) ###### Behavior Notes: - Returns `201` with the new Campaign on success. - Campaigns created via the API are always created with `type: oneOffs`. Other Campaign types (`anniversary`, `birthday`, `schedule`, `marketing`, `newHire`) can only be created through the Snappy Dashboard. - Returns `409` when a Campaign with the same name already exists in the Company. - Returns `422` for business-rule violations (e.g. invalid Collection/Product reference, conflicting customization). #### Permissions - Requires: `campaigns:create` operationId: createCampaign parameters: - schema: type: string pattern: ^[A-Za-z0-9]{8,}$ description: Company ID example: '12345678' required: false description: Company ID name: companyId in: query - schema: $ref: '#/components/schemas/RequestSourceHeader' required: false description: Source of the request name: Request-Source in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostCampaignBody' responses: '201': description: Campaign created successfully content: application/json: schema: $ref: '#/components/schemas/Campaign' '400': description: Bad Request - Invalid input content: application/json: schema: $ref: '#/components/schemas/ApiStringError' '401': description: Unauthorized, invalid, expired or missing token content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 401 errorCode: 401_PBLC_001 message: Unauthorized '403': description: Company or account mismatch content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 403 errorCode: 403_PBLC_001 message: Forbidden '409': description: Conflict - Campaign with this name already exists content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 409 errorCode: 409_PBLC_001 message: Conflict '422': description: Cant create campaign due to business logic validation content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 422 errorCode: 422_PBLC_001 message: Unprocessable entity security: - CompanyLevelAuthentication: [] - BearerAuthentication: [] components: schemas: RequestSourceHeader: type: string enum: - api_native - api_zapier - api_salesforce - api_ftp - api_make description: Source of the request example: api_native PostCampaignBody: type: object properties: name: type: string description: The name of the campaign example: My Campaign accountId: type: string description: The account ID this campaign belongs to example: a12bcd34 customization: $ref: '#/components/schemas/CampaignCustomization' required: - name - accountId - customization additionalProperties: false description: Request body for creating a campaign. Campaign: type: object properties: id: type: string description: The id of the campaign. example: abcd1234 createdAt: type: string description: The date when the campaign was created. example: '2021-01-01T00:00:00.000Z' updatedAt: type: string description: The date when the campaign was last updated. example: '2021-01-01T00:00:00.000Z' name: type: string description: The name of the campaign. example: Campaign Name accountId: type: string description: The id of the account. example: a12bcd34 companyId: type: string description: The id of the company. example: A1b2C3d4 status: $ref: '#/components/schemas/CampaignStatus' source: $ref: '#/components/schemas/CampaignSource' account: $ref: '#/components/schemas/CampaignAccount' type: type: string enum: - anniversary - birthday - schedule - marketing - oneOffs - newHire description: >- The type of the campaign. valid values are: anniversary, birthday, schedule, marketing, oneOffs, newHire. example: oneOffs giftsExpirationInDays: type: number deprecated: true description: |- The number of days until the gifts will expire. The default value is 30 days. example: 30 giftExpirationDate: type: string deprecated: true description: |- The date when the gift will expire. Date Format: YYYY-MM-DDThh:mm:ss.sZ. properties: type: array items: type: object properties: budget: type: number description: The budget of the campaign. example: 100 collection: type: object properties: id: type: string description: The id of the collection. example: abcdef12 name: type: string description: The name of the collection. example: Collection Name defaultCountry: type: string description: >- The default country of the collection. The default country is used to calculate the estimated cost of the gift. example: US required: - id - name - defaultCountry description: The collection of the campaign. required: - budget description: The properties of the campaign. deprecated: true customization: $ref: '#/components/schemas/CampaignCustomization' description: Campaign details including configuration and customization. ApiStringError: type: object properties: status: type: integer description: The HTTP status code. example: 400 errorCode: type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 400_PBLC_001 message: type: string description: The error message. example: Unauthorized errors: type: array items: type: object properties: path: type: string description: The path of the field that caused the error. example: body.recipients.0.email message: type: string description: The error message. example: Invalid email. errorCode: type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 400_PBLC_002 required: - path - message - errorCode description: >- An array of client errors. This field is being returned only for errors the client should fix, usually with status code 400. required: - status - errorCode - message description: >- API error response with string error codes and optional client error details example: status: 400 errorCode: 400_PBLC_001 message: Bad Request CampaignCustomization: type: object properties: giftProperties: type: array items: type: object properties: budget: $ref: '#/components/schemas/Budget' expiration: $ref: '#/components/schemas/Expiration' guaranteedGift: $ref: '#/components/schemas/GuaranteedGift' selectedGiftType: type: string enum: - collection - product description: The type of gift selection collection: $ref: '#/components/schemas/CampaignCollection' product: $ref: '#/components/schemas/Product' required: - selectedGiftType minItems: 1 description: Array of gift property configurations notificationPolicy: $ref: '#/components/schemas/CampaignNotificationPolicy' recipientExperience: allOf: - $ref: '#/components/schemas/RecipientExperience' - type: object properties: visualElements: type: object properties: reveal: type: object properties: type: type: string enum: - noReveal - snowGlobe - snowMan - pinata - boxTap - growingPlant - mountainClimbMask - elegantBoxMask - newHireMask - casinoMachineMask - anniversaryBottleMask - happyBirthdayMask - newbornEggMask - nostalgiaMask - cozyHolidayMask - thanksgivingMask - customImageScratch - brandScratch - customVideo - specialDeliveryMask - newYearMask - appreciationDayMask - magicalMask - thinkingOfYouMask - winterKnittingMask - starMask - winterTrainMask description: Type of reveal experience. example: snowGlobe primaryColor: type: string format: hex pattern: ^#[0-9A-Fa-f]{6}$ description: Primary color of reveal experience. example: '#000000' secondaryColor: type: string format: hex pattern: ^#[0-9A-Fa-f]{6}$ description: Secondary color of reveal experience. example: '#000000' mediaItems: $ref: '#/components/schemas/RevealMediaItems' additionalProperties: false greeting: $ref: '#/components/schemas/Greeting' additionalProperties: false additionalProperties: false description: >- Defines the interactive journey recipients experience when receiving your gift - from the initial unwrapping animation to greeting message presentation and delivery address collection process. example: type: enterAddress visualElements: reveal: type: snowGlobe primaryColor: '#000000' secondaryColor: '#000000' greeting: content: ops: - insert: Happy Birthday! banner: text: Happy Birthday! color: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg postClaim: redirectAfterClaim: https://example.com/redirect required: - giftProperties - notificationPolicy description: >- Campaign customization defines the entire gift recipient experience. It includes budget parameters, collection or product selection, expiration settings, notification methods, and visual presentation elements that create a cohesive branded experience. CampaignStatus: type: string enum: - live - sent - draft - paused - pending - scheduled - archived - active description: The status of the campaign. example: draft CampaignSource: type: string enum: - dashboard - dashboard_ai - api_native - api_zapier - api_make - api_salesforce - api_ftp description: The source of the campaign. example: api_native CampaignAccount: type: object properties: id: type: string description: The id of the account. example: a12bcd34 name: type: string description: The name of the account. example: Account Name required: - id - name description: The account of the campaign. Budget: type: object properties: max: type: number minimum: 1 maximum: 20000 description: Maximum budget allowed for gifts (between 1-20,000) example: 100 min: type: number minimum: 1 maximum: 10000 description: Minimum budget allowed for gifts (between 1-10,000) example: 76 required: - max additionalProperties: false description: Budget constraints for gifts example: max: 100 min: 76 Expiration: type: object properties: type: type: string enum: - unlimited - specificDate - daysFromSend default: unlimited description: Type of expiration example: daysFromSend date: type: string format: date-time description: Required when type is specificDate, otherwise not allowed numberOfDays: type: number minimum: 1 maximum: 365 description: Required when type is daysFromSend, otherwise not allowed additionalProperties: false description: >- Flexible expiration options let you set a specific end date, number of days from sending, or unlimited usage period. This helps manage campaign relevance and encourages timely recipient action while maintaining control over your gifting program timeline. example: type: daysFromSend numberOfDays: 30 GuaranteedGift: type: object properties: type: type: string enum: - specificDate - daysFromSend description: Type of guaranteed gift expiration example: daysFromSend date: type: string format: date-time description: Required when type is specificDate, otherwise not allowed numberOfDays: type: number minimum: 1 maximum: 365 description: Required when type is daysFromSend, otherwise not allowed required: - type additionalProperties: false description: >- Flexible guaranteed gift options mirror campaign expiration settings and allow specific date or days from send configuration. example: type: daysFromSend numberOfDays: 30 CampaignCollection: type: object properties: id: type: string description: The id of the collection. example: '12345678' featuredProducts: type: array items: type: string description: The ids of the featured products. example: - '12345678' additionalProperties: false description: |- Collection configuration for campaign gifts. Required when selectedGiftType is collection, otherwise not allowed. example: id: '12345678' featuredProducts: - '12345678' Product: type: object properties: id: type: string description: The id of the product. example: '12345678' displayType: type: string enum: - displayAsSurprise - displayProduct default: displayProduct example: displayAsSurprise required: - id additionalProperties: false description: |- Product configuration for campaign gifts. Required when selectedGiftType is product, otherwise not allowed. example: id: '12345678' displayType: displayAsSurprise CampaignNotificationPolicy: type: object properties: sendingChannels: type: array items: $ref: '#/components/schemas/SendingChannels' default: - mail description: The sending channels for notifying recipients about their gift. disableReminders: type: boolean description: Whether reminder notifications are disabled description: >- Notification settings control how recipients are informed about their gift - via email, SMS, link sharing or other channels. Also manages reminder behavior to optimize engagement rates. RecipientExperience: type: object properties: type: type: string enum: - enterAddress description: >- The type of recipient experience. Currently, we support 'enterAddress' type. In the future, we plan to support the 'ship to address' feature and will add another type. example: enterAddress visualElements: $ref: '#/components/schemas/VisualElements' postClaim: $ref: '#/components/schemas/PostClaim' additionalProperties: false description: >- Defines the interactive journey recipients experience when receiving your gift - from the initial unwrapping animation to greeting message presentation and delivery address collection process. example: type: enterAddress visualElements: reveal: type: snowGlobe primaryColor: '#000000' secondaryColor: '#000000' greeting: content: ops: - insert: Happy Birthday! banner: text: Happy Birthday! color: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg postClaim: redirectAfterClaim: https://example.com/redirect RevealMediaItems: type: object properties: background: type: array items: $ref: '#/components/schemas/MediaItems' maxItems: 1 logo: type: array items: $ref: '#/components/schemas/MediaItems' maxItems: 1 additionalProperties: false description: Media items of reveal experience. example: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg Greeting: type: object properties: content: type: object properties: ops: type: array items: nullable: true additionalProperties: true required: - ops additionalProperties: nullable: true description: Quill formatted JSON with ops array and any additional properties. example: ops: - attributes: font: pacifico insert: Happy Birthday! customProperty: customValue banner: type: object properties: text: type: string color: type: string pattern: ^#[0-9A-Fa-f]{6}$ mediaItems: $ref: '#/components/schemas/BannerMediaItems' required: - text - color - mediaItems additionalProperties: false description: >- The banner serves as the main visual element of the gift page. Customize background, logo, text, and colors to create a unique branded experience. example: text: Happy Birthday! color: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg required: - content - banner additionalProperties: false description: >- A personalized greeting with customizable fonts, colors, and media elements. Craft an emotional message that accompanies your gift and conveys your sentiment to the recipient. example: content: ops: - attributes: font: pacifico insert: Happy Birthday! banner: text: Happy Birthday! color: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg SendingChannels: type: string enum: - mail - sms - link - code - slack - teams description: The sending channels of the gift. example: mail VisualElements: type: object properties: reveal: $ref: '#/components/schemas/Reveal' greeting: $ref: '#/components/schemas/Greeting' required: - reveal - greeting additionalProperties: false description: Visual elements of recipient experience. example: reveal: type: snowGlobe primaryColor: '#000000' secondaryColor: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg greeting: content: ops: - attributes: font: pacifico insert: Happy Birthday! banner: text: Happy Birthday! color: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg PostClaim: type: object properties: redirectAfterClaim: type: string format: uri description: URL to direct to after the recipient claims the gift. example: https://example.com/redirect required: - redirectAfterClaim additionalProperties: false description: An object defining the customizations in the postClaim step. example: redirectAfterClaim: https://example.com/redirect MediaItems: type: object properties: type: type: string enum: - image - video description: Type of media item. example: image url: type: string format: uri description: URL of the media item. example: https://example.com/image.jpg required: - type - url additionalProperties: false description: Media item object. example: type: image url: https://example.com/image.jpg BannerMediaItems: type: object properties: background: type: array items: $ref: '#/components/schemas/MediaItems' minItems: 0 maxItems: 1 logo: type: array items: $ref: '#/components/schemas/MediaItems' maxItems: 1 required: - background additionalProperties: false description: Media items of banner. example: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg Reveal: type: object properties: type: type: string enum: - noReveal - snowGlobe - snowMan - pinata - boxTap - growingPlant - mountainClimbMask - elegantBoxMask - newHireMask - casinoMachineMask - anniversaryBottleMask - happyBirthdayMask - newbornEggMask - nostalgiaMask - cozyHolidayMask - thanksgivingMask - customImageScratch - brandScratch - customVideo - specialDeliveryMask - newYearMask - appreciationDayMask - magicalMask - thinkingOfYouMask - winterKnittingMask - starMask - winterTrainMask description: Type of reveal experience. example: snowGlobe primaryColor: type: string format: hex pattern: ^#[0-9A-Fa-f]{6}$ description: Primary color of reveal experience. example: '#000000' secondaryColor: type: string format: hex pattern: ^#[0-9A-Fa-f]{6}$ description: Secondary color of reveal experience. example: '#000000' mediaItems: $ref: '#/components/schemas/RevealMediaItems' required: - type - primaryColor - secondaryColor additionalProperties: false description: >- The reveal animation creates an emotional moment of surprise. Choose the animation type, color scheme, and branded elements to personalize the recipient's first impression and enhance gift anticipation. example: type: snowGlobe primaryColor: '#000000' secondaryColor: '#000000' mediaItems: background: - type: image url: https://example.com/image.jpg logo: - type: image url: https://example.com/image.jpg securitySchemes: CompanyLevelAuthentication: type: apiKey in: header name: X-Api-Key description: > ## Company Level Authentication Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ### Getting Your API Key 1. **Create an API Key**: Use the `POST /v2/authentication/apiKeys` endpoint to generate a new API key 2. **Set Expiration**: Choose from 30, 60, 90, or 180 days (default: 90 days) 3. **Optional mTLS**: Enable mutual TLS for enhanced security 4. **Name Your Key**: Provide a descriptive name for easy identification ### Using Your API Key Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_24_CHARACTER_API_KEY ``` ### API Key Management - **Maximum Keys**: Up to 3 active API keys per company - **Rotation**: Delete old keys before creating new ones when at the limit - **Security**: Keys are hashed and cannot be retrieved after creation ### Enhanced Security (mTLS) For production environments, enable mutual TLS authentication: 1. Set `enforceMtls: true` when creating the API key 2. Contact support to obtain your client certificates 3. Use the mTLS endpoint: `https://mtls-api.snappy.com/public-api` BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: >- Bearer authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ````