Skip to main content
POST
/
v2
/
recipients
Create recipient
curl --request POST \
  --url https://api.snappy.com/public-api/v2/recipients \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "birthday": "2022-12-06T00:00:00.000Z",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "emailOverride": "john.doe.override@example.com",
  "mobilePhone": "+1234567890",
  "country": "US",
  "accounts": [
    "a12bcd34",
    "a56bcd78"
  ],
  "recipientCustomFields": [
    {
      "fieldName": "petName",
      "displayName": "petName",
      "fieldValue": "Wesley"
    }
  ],
  "type": "employee",
  "employee": {
    "workingSince": "2022-12-06T00:00:00.000Z",
    "department": "R&D"
  }
}
'
{
  "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"
  }
}

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

Create recipient request body.

​
firstName
string
required

the first name of the recipient

Example:

"John"

​
country
string
required

Country code

Pattern: ^[A-Za-z]+$
Example:

"US"

​
accounts
string[]
required

The accounts ids that the recipient is associated with. Can be copied from Snappy's dashboard or queried in upcoming Accounts API

Minimum array length: 1
Example:
["a12bcd34", "a56bcd78"]
​
birthday
string

Date Format: YYYY-MM-DD.

Example:

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

​
lastName
string

the last name of the recipient

Example:

"Doe"

​
email
string

the email of the recipient, should be a valid email

Example:

"john.doe@example.com"

​
emailOverride
string

The sendingEmail of the recipient in the db, used to override the existing email.

Example:

"john.doe.override@example.com"

​
mobilePhone
string

Mobile phone number

Pattern: ^$|^[0-9 \-+().]{3,7}[0-9 \-+().]{3,7}[0-9]{3,7}$
Example:

"+1234567890"

​
recipientCustomFields
object[]

The custom fields of the recipient.

​
type
enum<string>

The type of employee.

Available options:
employee
Example:

"employee"

​
employee
object

The employee info object.

Example:
{
  "workingSince": "2022-01-15T00:00:00.000Z",
  "department": "Engineering"
}
​
externalId
string

An external id used by the customer to track their recipients

Example:

"1234567890"

​
owner
object

The person in charge of the recipient's gifting.

Example:
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com"
}

Response

Recipient created successfully

Created recipient.

​
id
string
required

The id of the recipient.

Example:

"xyz12345"

​
createdAt
string<date-time>
required

Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

​
updatedAt
string<date-time>
required

Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

​
firstName
string
required

the first name of the recipient

Example:

"John"

​
country
string
required

Country code

Pattern: ^[A-Za-z]+$
Example:

"US"

​
accounts
string[]
required

The accounts ids that the recipient is associated with

Minimum array length: 1
Example:
["a12bcd34", "a56bcd78"]
​
type
enum<string>
required

The type of employee.

Available options:
employee
Example:

"employee"

​
updatedBy
string | null
required

The id of the user who last updated the recipient.

Example:

"abc12345"

​
source
object
required

The data source of the recipient.

Example:
{ "type": "apiIntegration" }
​
birthday
string

Date Format: YYYY-MM-DD.

Example:

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

​
lastName
string

the last name of the recipient

Example:

"Doe"

​
email
string

the email of the recipient, should be a valid email

Example:

"john.doe@example.com"

​
emailOverride
string

The sendingEmail of the recipient in the db, used to override the existing email.

Example:

"john.doe.override@example.com"

​
mobilePhone
string

Mobile phone number

Pattern: ^$|^[0-9 \-+().]{3,7}[0-9 \-+().]{3,7}[0-9]{3,7}$
Example:

"+1234567890"

​
externalId
string

An external id used by the customer to track their recipients

Example:

"1234567890"

​
recipientCustomFields
object[]

The custom fields of the recipient.

​
employee
object

The employee info object.

Example:
{
  "workingSince": "2022-01-15T00:00:00.000Z",
  "department": "Engineering"
}
​
owner
object

The person in charge of the recipient's gifting.

Example:
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com"
}
Last modified on April 30, 2026