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"
  }
}

Recipients

Create recipient

Use this endpoint to add a new Recipient to your Company’s contact list. Once created, the Recipient can be associated with multiple Accounts and referenced by ID across multiple gift sends.

Required fields:

firstName - the Recipient’s first name
country - ISO 3166-1 alpha-2 country code
accounts - array of at least one Account ID to associate this Recipient with

Optional fields:

lastName - the Recipient’s last name
email - the Recipient’s primary email (used as the primary identifier)
emailOverride - alternative email for notifications (e.g. personal email when email is work email)
mobilePhone - mobile phone number
birthday - ISO 8601 date for birthday-trigger flows
externalId - your internal ID for this Recipient (HRIS, CRM)
type - Recipient type. Currently only employee is supported.
employee - work-related details: workingSince (start date), department
owner - the person responsible for this Recipient: firstName, lastName, email
recipientCustomFields - array of custom field objects (fieldName, displayName, fieldValue)

Optional parameters:

companyId query parameter - Company ID (when not inferable from the calling key)
Request-Source header - source of the request

Behavior Notes:

Returns 201 with the created Recipient on success.
Returns 409 if a Recipient with the same identifying data already exists in the Company.
Returns 422 for business-rule violations (e.g. invalid Account IDs).
The source.type on the response will be apiIntegration for recipients created via this endpoint.

Permissions

Requires: recipients:create

POST

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"
  }
}

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"

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"

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.

Show child attributes

type

enum<string>

The type of employee.

Available options:

employee

Example:

"employee"

employee

object

The employee info object.

Show child attributes

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.

Show child attributes

Example:

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

Response

Recipient created successfully

Created recipient.

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.

Show child attributes

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"

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.

Show child attributes

employee

object

The employee info object.

Show child attributes

Example:

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

owner

object

The person in charge of the recipient's gifting.

Show child attributes

Example:

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

Last modified on June 17, 2026

Get recipients

Get recipient by ID