Skip to main content
GET
/
v2
/
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>",
        "status": "orderReceived",
        "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>",
          "status": "active",
          "orderedProducts": [
            {
              "selectedProduct": {
                "variantId": "<string>",
                "orderStatus": "processing",
                "title": "<string>",
                "type": "physicalGift"
              },
              "deliveryDetails": {
                "status": "orderReceived",
                "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>"
}

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"

​
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

Ok

List of gifts with pagination info.

​
results
object[]
required

The gifts of the company.

​
skip
number
​
limit
number | null
​
message
string

The message of the response

Last modified on April 30, 2026