Get gifts

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

{
  "results": [
    {
      "id": "<string>",
      "companyId": "12345678",
      "campaignId": "<string>",
      "status": "<string>",
      "budgetPlan": 123,
      "tyn": "<string>",
      "estimatedCost": {
        "budget": 100,
        "estimatedFee": 2,
        "estimatedTax": 7,
        "estimatedTotalCost": 109
      },
      "expirationDate": "2022-12-06T09:50:38.536Z",
      "createdAt": "<string>",
      "link": "<string>",
      "success": true,
      "deliveryDetails": {
        "carrier": "<string>",
        "trackingNumber": "<string>",
        "trackingLink": "<string>",
        "deliveredAt": "2022-12-06T09:50:38.536Z",
        "outForDelivery": "2022-12-06T09:50:38.536Z",
        "outForDeliveryDate": "2022-12-06T09:50:38.536Z"
      },
      "finalCost": {
        "cost": 100,
        "finalFee": 2,
        "finalTax": 7,
        "totalFinalCost": 109
      },
      "recipient": {
        "firstname": "John",
        "lastname": "Doe",
        "externalId": "1234567890",
        "phone": "+1234567890",
        "email": "example@domain.com",
        "key": "abc123"
      },
      "orders": [
        {
          "id": "<string>",
          "orderedProducts": [
            {
              "selectedProduct": {
                "variantId": "<string>",
                "title": "<string>"
              },
              "deliveryDetails": {
                "carrier": "<string>",
                "trackingNumber": "<string>",
                "trackingLink": "<string>",
                "deliveryDates": {
                  "outForDelivery": "2023-11-07T05:31:56Z",
                  "estimated": "2023-11-07T05:31:56Z",
                  "deliveredAt": "2023-11-07T05:31:56Z"
                }
              }
            }
          ],
          "orderRecipient": {
            "firstName": "John",
            "lastName": "Doe",
            "country": "US"
          }
        }
      ],
      "customization": {
        "giftProperties": {
          "budget": {
            "max": 100,
            "min": 76
          }
        },
        "recipientNotifications": {
          "sendingChannels": [
            "mail",
            "sms"
          ],
          "disableReminders": false
        },
        "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": 123,
  "limit": 123,
  "message": "<string>"
}

Gifts

Get gifts

Use this endpoint to search for and retrieve a list of gifts based on your specified criteria - campaign, status, sending channels, recipient, and more.

Filtering options:

companyId query parameter - Company ID (when not inferable from the calling key)
campaignIds - comma-separated list of Campaign IDs (min 1 item)
keys - comma-separated list of idempotency keys
statuses - comma-separated list of gift statuses (unopened, opened, unwrapped, claimed, expired)
sendingChannels - comma-separated list of sending channels (mail, sms, link, code, slack, teams)
externalRecipientId - filter by the recipient’s external (your-system) ID
experienceId - filter by experience ID
invoiceId - filter by invoice ID
createdBefore / createdAfter - YYYY-MM-DD date bounds (exclusive)
fields - comma-separated field projection. Valid values: id, status, budgetPlan, sendingChannels, tyn, expirationDate, createdAt, link, campaignId, metadata, full
expand - comma-separated objects to include in the response. Valid values: finalCost, deliveryDetails, estimatedCost, recipient, orders, customization
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-100, default 100)

Please note:

The default fields set returns id, link, and status only. Use fields=full for the complete Gift shape, or specify the fields you need.
Use expand to inline related objects like recipient, orders, and finalCost - by default these are not included.
The senderId and senderEmail parameters are deprecated - do not use them in new integrations.

Permissions

Requires: gifts:read:masked or gifts:read:unmasked

GET

gifts

Get gifts

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

{
  "results": [
    {
      "id": "<string>",
      "companyId": "12345678",
      "campaignId": "<string>",
      "status": "<string>",
      "budgetPlan": 123,
      "tyn": "<string>",
      "estimatedCost": {
        "budget": 100,
        "estimatedFee": 2,
        "estimatedTax": 7,
        "estimatedTotalCost": 109
      },
      "expirationDate": "2022-12-06T09:50:38.536Z",
      "createdAt": "<string>",
      "link": "<string>",
      "success": true,
      "deliveryDetails": {
        "carrier": "<string>",
        "trackingNumber": "<string>",
        "trackingLink": "<string>",
        "deliveredAt": "2022-12-06T09:50:38.536Z",
        "outForDelivery": "2022-12-06T09:50:38.536Z",
        "outForDeliveryDate": "2022-12-06T09:50:38.536Z"
      },
      "finalCost": {
        "cost": 100,
        "finalFee": 2,
        "finalTax": 7,
        "totalFinalCost": 109
      },
      "recipient": {
        "firstname": "John",
        "lastname": "Doe",
        "externalId": "1234567890",
        "phone": "+1234567890",
        "email": "example@domain.com",
        "key": "abc123"
      },
      "orders": [
        {
          "id": "<string>",
          "orderedProducts": [
            {
              "selectedProduct": {
                "variantId": "<string>",
                "title": "<string>"
              },
              "deliveryDetails": {
                "carrier": "<string>",
                "trackingNumber": "<string>",
                "trackingLink": "<string>",
                "deliveryDates": {
                  "outForDelivery": "2023-11-07T05:31:56Z",
                  "estimated": "2023-11-07T05:31:56Z",
                  "deliveredAt": "2023-11-07T05:31:56Z"
                }
              }
            }
          ],
          "orderRecipient": {
            "firstName": "John",
            "lastName": "Doe",
            "country": "US"
          }
        }
      ],
      "customization": {
        "giftProperties": {
          "budget": {
            "max": 100,
            "min": 76
          }
        },
        "recipientNotifications": {
          "sendingChannels": [
            "mail",
            "sms"
          ],
          "disableReminders": false
        },
        "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": 123,
  "limit": 123,
  "message": "<string>"
}

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"

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

fields

enum<string>[]

The fields that can be returned for the gift. format: comma-separated without whitespace in between. valid values are: id, status, budgetPlan, sendingChannels, tyn, expirationDate, createdAt, link, campaignId, metadata, full.

Minimum array length: 1

The fields that can be returned for the gift. valid values are: id, status, budgetPlan, sendingChannels, tyn, expirationDate, createdAt, link, campaignId, metadata, full.

Available options:

id,

status,

budgetPlan,

sendingChannels,

tyn,

expirationDate,

createdAt,

link,

full,

experienceId,

campaignId,

metadata

campaignIds

string[]

comma-separated list of campaign ids

Minimum array length: 1

Minimum string length: 8

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

Example:

["abcd1234", "abcd6789"]

keys

string[]

comma-separated list of gift keys

Minimum array length: 1

Example:

["key1", "key2"]

statuses

enum<string>[]

The statuses of gifts that can be returned. comma-separated format without whitespace in between. valid values are: unopened, opened, unwrapped, claimed, expired.

Minimum array length: 1

The statuses of gifts that can be returned. valid values are: unopened, opened, unwrapped, claimed, expired.

Available options:

unopened,

opened,

unwrapped,

claimed,

expired

sendingChannels

enum<string>[]

The sending channels of the gift. default value is 'link'. valid values are: mail, sms, link, code, slack, teams.

Minimum array length: 1

The sending channels of the gift.

Available options:

mail,

sms,

link,

code,

slack,

teams

externalRecipientId

string

External recipient id

Example:

"1234efgh"

experienceId

string

Experience id

Example:

"1234wxyz"

createdBefore

string

Created before date, format: YYYY-MM-DD. results will NOT include the date that was passed.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Example:

"2022-12-06T00:00:00.000Z"

createdAfter

string

Created after date, format: YYYY-MM-DD results will NOT include the date that was passed.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Example:

"2022-12-06T00:00:00.000Z"

senderId

string

deprecated

DEPRECATED, DO NOT USE

Pattern: ^[A-Za-z0-9]+$

Example:

"ab123456"

senderEmail

string

deprecated

DEPRECATED, DO NOT USE

Example:

"sender_email"

invoiceId

string

Invoice id

Example:

"12abcd89"

expand

enum<string>[]

The fields that can be returned for the gift. comma-separated format without whitespace in between. valid values are: finalCost, deliveryDetails, estimatedCost, recipient, customization, orders.

Minimum array length: 1

Fields that can be returned for the gift

Available options:

finalCost,

deliveryDetails,

estimatedCost,

recipient,

orders,

customization

Response

List of gifts with pagination info.

results

object[]

required

The gifts of the company.

Show child attributes

skip

number

limit

number | null

message

string

The message of the response

Last modified on June 17, 2026

Create gifts

Create demo gift