Create gifts

curl --request POST \
  --url https://api.snappy.com/public-api/v2/gifts \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "campaignId": "12345678",
  "recipients": [
    {
      "firstname": "John",
      "lastname": "Doe",
      "externalId": "1234567890",
      "phone": "+1234567890",
      "email": "example@domain.com",
      "key": "abc123"
    }
  ],
  "sendingMethod": "mail",
  "customization": {
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000",
          "mediaItems": {
            "logo": [
              {
                "type": "image",
                "url": "https://example.com/media-item-1.jpg"
              }
            ]
          }
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "attributes": {
                  "font": "pacifico",
                  "size": "32px",
                  "color": "#000000"
                },
                "insert": "Happy Birthday!"
              }
            ]
          },
          "banner": {
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/media-item-1.jpg"
                }
              ]
            },
            "text": "🎁 Enjoy your gift!",
            "color": "#36d4ff"
          }
        },
        "postClaim": {
          "redirectAfterClaim": "https://example.com/redirect"
        }
      }
    },
    "giftProperties": {
      "selectedGiftType": "product",
      "product": {
        "id": "productId",
        "displayType": "displayAsSurprise"
      },
      "budget": {
        "max": 100,
        "min": 76
      },
      "expiration": {
        "type": "daysFromSend",
        "numberOfDays": 30
      }
    },
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    }
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
'

{
  "message": "2 gifts out of 3 have been sent successfully",
  "metadata": {
    "campaignName": "Employee Appreciation Q1 2025",
    "totalRecipients": 3,
    "batchId": "batch_20250609_001"
  },
  "results": [
    {
      "success": true,
      "link": "https://snappy.com/experience/K9mP3xL7dN",
      "id": "G7nR4bD9mK",
      "experienceId": "exp_2024_john_001"
    },
    {
      "success": true,
      "link": "https://snappy.com/experience/X2pQ8vB5jL",
      "id": "H8sT6cF2nP",
      "experienceId": "exp_2024_jane_002"
    },
    {
      "success": false,
      "message": "Gift creation failed",
      "errorCode": 40000
    }
  ]
}

Gifts

Create gifts

Use this endpoint to create one or more gifts within a Campaign and initiate the Triggered Gifting flow. Snappy will notify recipients based on the Campaign’s Notification Policy.

Required fields:

campaignId - the Campaign ID to send under
recipients - array of recipients, each requiring at minimum a firstname and an identifier to send to (email or phone). Include a unique key per recipient for duplicate detection.

Optional fields:

customization - Gift Customization overrides (giftProperties, notificationPolicy, recipientExperience). Overrides apply only to gifts created in this call.
metadata - optional key-value pairs (max 50 pairs, keys up to 40 chars, values up to 500 chars)
companyId query parameter - Company ID (when not inferable from the calling key)
Request-Source header - source of the request (api_native, api_zapier, api_salesforce, api_ftp, api_make)

Behavior Notes:

Supports batch creation - multiple recipients in a single request. Each recipient generates its own Gift with its own link and key.
A successful request returns the Gift objects with an initial status of unopened and a unique claim link for each recipient.
Webhook events fired through the lifecycle: gift-status-changed (unopened → unwrapped → opened → claimed / expired), and gift-notification-initial-sent.
The top-level sendingMethod field is deprecated - use customization.notificationPolicy.sendingChannels instead.

Permissions

Requires: gifts:create

POST

gifts

Create gifts

curl --request POST \
  --url https://api.snappy.com/public-api/v2/gifts \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "campaignId": "12345678",
  "recipients": [
    {
      "firstname": "John",
      "lastname": "Doe",
      "externalId": "1234567890",
      "phone": "+1234567890",
      "email": "example@domain.com",
      "key": "abc123"
    }
  ],
  "sendingMethod": "mail",
  "customization": {
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000",
          "mediaItems": {
            "logo": [
              {
                "type": "image",
                "url": "https://example.com/media-item-1.jpg"
              }
            ]
          }
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "attributes": {
                  "font": "pacifico",
                  "size": "32px",
                  "color": "#000000"
                },
                "insert": "Happy Birthday!"
              }
            ]
          },
          "banner": {
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/media-item-1.jpg"
                }
              ]
            },
            "text": "🎁 Enjoy your gift!",
            "color": "#36d4ff"
          }
        },
        "postClaim": {
          "redirectAfterClaim": "https://example.com/redirect"
        }
      }
    },
    "giftProperties": {
      "selectedGiftType": "product",
      "product": {
        "id": "productId",
        "displayType": "displayAsSurprise"
      },
      "budget": {
        "max": 100,
        "min": 76
      },
      "expiration": {
        "type": "daysFromSend",
        "numberOfDays": 30
      }
    },
    "notificationPolicy": {
      "sendingChannels": [
        "mail"
      ],
      "disableReminders": true
    }
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
'

{
  "message": "2 gifts out of 3 have been sent successfully",
  "metadata": {
    "campaignName": "Employee Appreciation Q1 2025",
    "totalRecipients": 3,
    "batchId": "batch_20250609_001"
  },
  "results": [
    {
      "success": true,
      "link": "https://snappy.com/experience/K9mP3xL7dN",
      "id": "G7nR4bD9mK",
      "experienceId": "exp_2024_john_001"
    },
    {
      "success": true,
      "link": "https://snappy.com/experience/X2pQ8vB5jL",
      "id": "H8sT6cF2nP",
      "experienceId": "exp_2024_jane_002"
    },
    {
      "success": false,
      "message": "Gift creation failed",
      "errorCode": 40000
    }
  ]
}

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"

Body

application/json

The gift object.

campaignId

string

required

Campaign ID

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

Example:

"12345678"

recipients

object[]

required

The recipients of the gift.

Show child attributes

sendingMethod

enum<string>

deprecated

Deprecated. Use "customization.notificationPolicy.sendingChannels" instead.

Available options:

mail,

sms,

mailAndSms,

link

Example:

"mail"

customization

object

Customization configuration of the gift.

Show child attributes

metadata

object

Optional metadata object with key-value pairs. Keys must be alphanumeric (including underscores) and up to 40 characters. Values must be alphanumeric and up to 500 characters. Maximum 50 key-value pairs allowed.

Show child attributes

Example:

{ "key1": "value1", "key2": "value2" }

Response

The response of the gift creation

message

string

required

The message of the response

metadata

object

required

Show child attributes

Example:

{ "key1": "value1", "key2": "value2" }

results

object[]

required

Show child attributes

Last modified on June 17, 2026

Gifts API (V2): Create, Track, and Expire Gifts

Get gifts