Get recipients

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

{
  "results": [
    {
      "id": "xyz12345",
      "createdAt": "2022-12-06T09:50:38.536Z",
      "updatedAt": "2022-12-06T09:50:38.536Z",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "country": "US",
      "accounts": [
        "a12bcd34",
        "a56bcd78"
      ],
      "type": "employee",
      "updatedBy": "abc12345",
      "source": {
        "type": "apiIntegration"
      }
    }
  ],
  "skip": 0,
  "limit": 200
}

Recipients

Get recipients

Use this endpoint to retrieve a list of Recipients based on your specified criteria. Use this when building a recipient picker in your UI, syncing recipients to your system, or finding recipients by name, email, or external ID.

Filtering options:

firstNames query parameter - comma-separated list of first names
lastNames query parameter - comma-separated list of last names
emails query parameter - comma-separated list of email addresses (each must be a valid email format)
emailOverrides query parameter - comma-separated list of email override addresses
externalIds query parameter - comma-separated list of your-system IDs
accountIds query parameter - comma-separated list of Account IDs
sources query parameter - comma-separated list of recipient sources (apiIntegration, hrisIntegration, manual, ftpIntegration, fileSync)
fields query parameter - comma-separated field projection. Valid values: id, createdAt, updatedAt, firstName, lastName, email, emailOverride, mobilePhone, country, externalId, accounts, updatedBy, source, owner, type, recipientCustomFields, birthday, full
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)

Pagination:

skip query parameter - number of records to skip (default 0)
limit query parameter - max records per page (1-200, default 200)

Please note:

All array filters use OR semantics - passing multiple firstNames returns recipients matching any of the supplied names.
PII fields are masked unless your API key has the recipients:read:unmasked scope.

Permissions

Requires: recipients:read:masked or recipients:read:unmasked

GET

recipients

Get recipients

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

{
  "results": [
    {
      "id": "xyz12345",
      "createdAt": "2022-12-06T09:50:38.536Z",
      "updatedAt": "2022-12-06T09:50:38.536Z",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "country": "US",
      "accounts": [
        "a12bcd34",
        "a56bcd78"
      ],
      "type": "employee",
      "updatedBy": "abc12345",
      "source": {
        "type": "apiIntegration"
      }
    }
  ],
  "skip": 0,
  "limit": 200
}

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"

firstNames

string[]

The first name of the recipient.

Minimum array length: 1

Example:

["John"]

lastNames

string[]

The last name of the recipient.

Minimum array length: 1

Example:

["Doe"]

externalIds

string[]

The external id of the recipient.

Minimum array length: 1

Example:

["123", "124"]

emails

string[]

Recipient email addresses (must be valid email format).

Minimum array length: 1

Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Example:

["sad@asd.com"]

emailOverrides

string[]

Alternative email addresses to use for sending gifts, overriding the recipient's primary email.

Minimum array length: 1

Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Example:

["sad@sad.com"]

accountIds

string[]

The account id of the recipient.

Minimum array length: 1

Example:

["a12bcd34", "a56bcd78"]

sources

enum<string>[]

The source of the recipient.

Minimum array length: 1

The source of the recipient.

Available options:

apiIntegration,

hrisIntegration,

manual,

ftpIntegration,

fileSync

Example:

["apiIntegration", "ftpIntegration"]

fields

enum<string>[]

Fields to include in the response. Use 'full' to include all fields.

Minimum array length: 1

Fields to include in the response. Use 'full' to include all fields.

Available options:

id,

createdAt,

updatedAt,

firstName,

lastName,

email,

emailOverride,

mobilePhone,

country,

externalId,

accounts,

updatedBy,

source,

owner,

type,

recipientCustomFields,

birthday,

full

Example:

["id", "firstName"]

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:200

Maximum number of records to return per page

Required range: 1 <= x <= 200

Example:

200

Response

Response containing recipients.

results

object[]

required

The results of the recipients query.

Show child attributes

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 | null

Last modified on June 17, 2026

Recipients API (V2): Manage Gift Recipients at Scale

Create recipient