Get campaigns

curl --request GET \
  --url https://api.snappy.com/public-api/v2/campaigns \
  --header 'X-Api-Key: <api-key>'

{
  "results": [
    {
      "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": [
          {
            "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"
            }
          }
        }
      }
    }
  ],
  "skip": 0,
  "limit": 10
}

Campaigns

Get campaigns

Use this endpoint to retrieve a paginated list of Campaigns with flexible filtering options. Use this when building a Campaign picker in your UI, syncing Campaigns to your system, or auditing existing Campaign configurations.

Filtering options

companyId query parameter - Company ID (when not inferable from the calling key)
accountId query parameter - filter to Campaigns belonging to a specific Account
types query parameter - comma-separated Campaign types (anniversary, birthday, schedule, marketing, oneOffs, newHire)
sources query parameter - comma-separated Campaign sources (dashboard, dashboard_ai, api_native, api_zapier, api_make, api_salesforce, api_ftp)
statuses query parameter - comma-separated Campaign statuses (e.g. draft,active,paused)
fields query parameter - comma-separated field projection. Valid values: id, name, createdAt, updatedAt, companyId, accountId, account, properties, giftsExpirationInDays, giftExpirationDate, type, source, status, customization, full
Request-Source header - source of the request

Pagination

skip query parameter - number of records to skip (default 0)
limit query parameter - max records per page (1-1000, default 100)

Please note

The response wraps Campaigns in a results array with skip and limit echoed back.

Permissions

Requires: campaigns:read

GET

campaigns

Get campaigns

curl --request GET \
  --url https://api.snappy.com/public-api/v2/campaigns \
  --header 'X-Api-Key: <api-key>'

{
  "results": [
    {
      "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": [
          {
            "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"
            }
          }
        }
      }
    }
  ],
  "skip": 0,
  "limit": 10
}

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

Create an API Key: Use the POST /v2/authentication/apiKeys endpoint to generate a new API key
Set Expiration: Choose from 30, 60, 90, or 180 days (default: 90 days)
Optional mTLS: Enable mutual TLS for enhanced security
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:

Set enforceMtls: true when creating the API key
Contact support to obtain your client certificates
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"

accountId

string

Account ID

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

Example:

"a12bcd34"

skip

number | null

default:0

Number of records to skip for pagination (use with limit for paging through results)

Required range: x >= 0

Example:

0

limit

number

default:100

Limit returned campaigns

Required range: 1 <= x <= 1000

Example:

100

types

enum<string>[]

The types of campaigns that can be returned. comma-separated format without whitespace in between. valid values are: anniversary, birthday, schedule, marketing, oneOffs, newHire.

Minimum array length: 1

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

Available options:

anniversary,

birthday,

schedule,

marketing,

oneOffs,

newHire

sources

enum<string>[]

Filter by campaign sources

Minimum array length: 1

The source of the campaign.

Available options:

dashboard,

dashboard_ai,

api_native,

api_zapier,

api_make,

api_salesforce,

api_ftp

statuses

enum<string>[]

Filter by campaign statuses

Minimum array length: 1

The status of the campaign.

Available options:

live,

sent,

draft,

paused,

pending,

scheduled,

archived,

active

fields

enum<string>[]

The fields that can be returned for the campaign. comma-separated format without whitespace in between. valid values are: id, name, createdAt, updatedAt, companyId, accountId, account, properties, giftsExpirationInDays, giftExpirationDate, type, source, status, customization, full.

Minimum array length: 1

The fields that can be returned for the campaign. valid values are: id, name, createdAt, updatedAt, companyId, accountId, account, properties, giftsExpirationInDays, giftExpirationDate, type, source, status, customization, full.

Available options:

id,

name,

createdAt,

updatedAt,

companyId,

accountId,

account,

properties,

giftsExpirationInDays,

giftExpirationDate,

type,

status,

source,

customization,

full

Response

List of campaigns with pagination info.

results

object[]

required

The campaigns of the company.

Show child attributes

skip

number | null

default:0

Number of records to skip for pagination (use with limit for paging through results)

Required range: x >= 0

Example:

0

limit

number

default:100

Maximum number of records to return per page

Required range: 1 <= x <= 100

Example:

10

Last modified on June 17, 2026

Campaigns API (V2): Plan, Schedule, and Report on Gifting Campaigns

Create campaign