Update campaign by ID

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/campaigns/{campaignId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "New campaign name",
  "status": "active",
  "customization": {
    "giftProperties": [
      {
        "budget": {
          "max": 100,
          "min": 76
        },
        "expiration": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "guaranteedGift": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "collection": {
          "id": "12345678",
          "featuredProducts": [
            "12345678"
          ]
        }
      }
    ],
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "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": {
        "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": [
      {
        "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"
        }
      }
    }
  }
}

Campaigns

Update campaign by ID

Use this endpoint to update the settings of an existing Campaign, including its Gift Customization configuration. Changes apply only to gifts created after the update - previously created gifts are not affected.

Required fields:

campaignId - the Campaign identifier, passed as a path parameter

Optional fields: (in request body)

name - new display name of the Campaign (must be unique within the Company)
status - Campaign lifecycle status. Allowed values via API: active, paused, archived
customization - updated Gift Customization configuration. The entire customization object must be provided when updating.

Optional parameters:

companyId query parameter - Company ID (when not inferable from the calling key)
Request-Source header - source of the request

Behavior Notes:

Only active, paused, and archived status transitions are allowed via the API. Other status changes (draft → pending → scheduled etc.) are managed by Snappy automatically or via the Dashboard.
Returns 404 if the Campaign doesn’t exist.
Returns 409 when renaming the Campaign to a name that already exists in the Company.
Returns 422 when the requested update conflicts with business rules (e.g. updating a sent or archived Campaign).

Permissions

Requires: campaigns:update

PATCH

campaigns

{campaignId}

Update campaign by ID

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/campaigns/{campaignId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "New campaign name",
  "status": "active",
  "customization": {
    "giftProperties": [
      {
        "budget": {
          "max": 100,
          "min": 76
        },
        "expiration": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "guaranteedGift": {
          "type": "daysFromSend",
          "numberOfDays": 30
        },
        "collection": {
          "id": "12345678",
          "featuredProducts": [
            "12345678"
          ]
        }
      }
    ],
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "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": {
        "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": [
      {
        "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"
        }
      }
    }
  }
}

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"

Path Parameters

campaignId

string

required

Campaign ID

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

Example:

"abcd1234"

Query Parameters

companyId

string

Company ID

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

Example:

"12345678"

Body

application/json

Request body for updating a campaign.

name

string

The name of the campaign.

Example:

"New campaign name"

status

enum<string>

The status of the campaign.

Available options:

active,

paused,

archived

Example:

"active"

customization

object

Configuration options for customizing the campaign. The entire customization object must be provided when updating.

Show child attributes

Response

Campaign updated

Campaign details including configuration and customization.

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

Last modified on June 17, 2026

Get campaign by ID

Get estimated cost for campaign