Skip to main content
POST
/
v2
/
campaigns
Create campaign
curl --request POST \
  --url https://api.snappy.com/public-api/v2/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "My Campaign",
  "accountId": "a12bcd34",
  "customization": {
    "giftProperties": [
      {
        "selectedGiftType": "collection",
        "budget": {
          "max": 100,
          "min": 76
        },
        "expiration": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "guaranteedGift": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "collection": {
          "id": "12345678",
          "featuredProducts": [
            "12345678"
          ]
        },
        "product": {
          "id": "12345678",
          "displayType": "displayAsSurprise"
        }
      }
    ],
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    },
    "recipientExperience": {
      "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"
        }
      }
    }
  }
}
'
{
  "id": "abcd1234",
  "createdAt": "2021-01-01T00:00:00.000Z",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "name": "Campaign Name",
  "accountId": "a12bcd34",
  "companyId": "A1b2C3d4",
  "status": "draft",
  "source": "api_native",
  "account": {
    "id": "a12bcd34",
    "name": "Account Name"
  },
  "type": "oneOffs",
  "giftsExpirationInDays": 30,
  "giftExpirationDate": "<string>",
  "properties": [
    {
      "budget": 100,
      "collection": {
        "id": "abcdef12",
        "name": "Collection Name",
        "defaultCountry": "US"
      }
    }
  ],
  "customization": {
    "giftProperties": [
      {
        "selectedGiftType": "collection",
        "budget": {
          "max": 100,
          "min": 76
        },
        "expiration": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "guaranteedGift": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "collection": {
          "id": "12345678",
          "featuredProducts": [
            "12345678"
          ]
        },
        "product": {
          "id": "12345678",
          "displayType": "displayAsSurprise"
        }
      }
    ],
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    },
    "recipientExperience": {
      "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"
        }
      }
    }
  }
}

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.

Authorizations

​
X-Api-Key
string
header
required

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

Headers

​
Request-Source
enum<string>

Source of the request

Available options:
api_native,
api_zapier,
api_salesforce,
api_ftp,
api_make
Example:

"api_native"

Query Parameters

​
companyId
string

Company ID

Pattern: ^[A-Za-z0-9]{8,}$
Example:

"12345678"

Body

application/json

Request body for creating a campaign.

​
name
string
required

The name of the campaign

Example:

"My Campaign"

​
accountId
string
required

The account ID this campaign belongs to

Example:

"a12bcd34"

​
customization
object
required

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.

Response

Campaign created successfully

Campaign details including configuration and customization.

​
id
string

The id of the campaign.

Example:

"abcd1234"

​
createdAt
string

The date when the campaign was created.

Example:

"2021-01-01T00:00:00.000Z"

​
updatedAt
string

The date when the campaign was last updated.

Example:

"2021-01-01T00:00:00.000Z"

​
name
string

The name of the campaign.

Example:

"Campaign Name"

​
accountId
string

The id of the account.

Example:

"a12bcd34"

​
companyId
string

The id of the company.

Example:

"A1b2C3d4"

​
status
enum<string>

The status of the campaign.

Available options:
live,
sent,
draft,
paused,
pending,
scheduled,
archived,
active
Example:

"draft"

​
source
enum<string>

The source of the campaign.

Available options:
dashboard,
dashboard_ai,
api_native,
api_zapier,
api_make,
api_salesforce,
api_ftp
Example:

"api_native"

​
account
object

The account of the campaign.

​
type
enum<string>

The type of the campaign. valid values are: anniversary, birthday, schedule, marketing, oneOffs, newHire.

Available options:
anniversary,
birthday,
schedule,
marketing,
oneOffs,
newHire
Example:

"oneOffs"

​
giftsExpirationInDays
number
deprecated

The number of days until the gifts will expire. The default value is 30 days.

Example:

30

​
giftExpirationDate
string
deprecated

The date when the gift will expire. Date Format: YYYY-MM-DDThh:mm:ss.sZ.

​
properties
object[]
deprecated

The properties of the campaign.

​
customization
object

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.

Last modified on April 30, 2026