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

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"

​
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

Ok

Response containing recipients.

​
results
object[]
required

The results of the recipients query.

​
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 April 30, 2026