Skip to main content
POST
/
v2
/
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
    }
  ]
}

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

The gift object.

​
campaignId
string
required

Campaign ID

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

"12345678"

​
recipients
object[]
required

The recipients of the gift.

​
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.

​
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.

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

Response

Ok

The response of the gift creation

​
message
string
required

The message of the response

​
metadata
object
required

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.

Example:
{ "key1": "value1", "key2": "value2" }
​
results
object[]
required
Last modified on April 30, 2026