Recipients API: Manage Gift Recipients at Scale

A Recipient is the end-user who receives a Gift. Recipients are saved at the Company level, meaning the same Recipient can be added to multiple Accounts and receive gifts from all of them.

Want to understand how Recipients fit into the bigger picture? Check out the Core Concepts & Data Models page.

The Recipient Object

Core Fields

Field	Type	Description
`id`	string	Unique identifier for the Recipient
`firstName`	string	Recipient’s first name
`lastName`	string	Recipient’s last name
`email`	string	Recipient’s primary email address. Used as the primary identifier
`emailOverride`	string	If set, gift notifications will be sent to this address instead of `email`. The original `email` is retained as the primary identifier
`mobilePhone`	string	Recipient’s mobile phone number
`country`	string	Recipient’s country, identified by ISO 3166-1 alpha-2 country code (e.g. `"US"`)
`externalId`	string	Your internal ID for this Recipient. Use this to map Snappy Recipients to records in your own system (e.g. HRIS, CRM)
`type`	string	The Recipient type (currently supporting only `employee`)
`accounts`	array	List of Account IDs this Recipient belongs to. A Recipient can belong to multiple Accounts and receive gifts from all of them
`birthday`	string	ISO 8601 timestamp of the Recipient’s birthday. Can be used to trigger automated birthday gifting flows
`source`	string	How the Recipient was created (e.g. `apiIntegration`). TBD - full list of possible values coming soon
`createdAt`	string	ISO 8601 timestamp of when the Recipient was created
`updatedAt`	string	ISO 8601 timestamp of the last update
`updatedBy`	string	The ID of the user who last updated this Recipient

Employee Details

The employee object contains work-related information about the Recipient. It is populated either when the Recipient is synced from an HRIS integration or manually provided when creating or updating a Recipient via the API.

Field	Type	Description
`employee.workingSince`	string	ISO 8601 timestamp of the Recipient’s employment start date. Can be used to trigger work anniversary gifting flows
`employee.department`	string	The department the Recipient belongs to

Owner

The owner object represents the person responsible for this Recipient - typically their manager or HR contact.

Field	Type	Description
`owner.firstName`	string	Owner’s first name
`owner.lastName`	string	Owner’s last name
`owner.email`	string	Owner’s email address

Custom Fields

The recipientCustomFields array contains additional custom attributes defined during your HRIS integration setup. These fields allow you to store supplemental data about a Recipient beyond the standard fields.

Field	Type	Description
`recipientCustomFields[].fieldName`	string	The internal name of the custom field
`recipientCustomFields[].displayName`	string	The display name of the custom field
`recipientCustomFields[].fieldValue`	string	The value of the custom field for this Recipient

Key Concepts & Business Rules

Recipients are scoped to a Company

Recipients are stored at the Company level, not the Account level. This means a single Recipient record can be associated with multiple Accounts and receive gifts from any of them without needing to be created multiple times.

Managed list vs. inline

Snappy supports two ways to provide recipient details when sending a gift via POST /gifts. The choice is made per-request - there’s no global setting. Managed Recipients Create and maintain a persistent contact list via the API. Once created, a Recipient can be referenced by their recipientId across multiple gift sends without re-submitting their details. Recommended for recurring use cases such as employee anniversaries or loyalty rewards.

{
  "campaignId": "cmp_12345",
  "recipients": [
    {
      "recipientId": "rec_12345",
      "key": "jane-doe-anniversary-2025"
    }
  ]
}

Inline Recipients Pass recipient details directly in the request body without creating a persistent Recipient record. Recommended for one-off sends where you don’t need to maintain the contact in Snappy. Omitting recipientId is what tells the API to treat the entry as inline:

{
  "campaignId": "cmp_12345",
  "recipients": [
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "email": "jane.doe@example.com",
      "phone": "+15551234567",
      "externalId": "emp_98765",
      "key": "jane-doe-anniversary-2025"
    }
  ]
}

Inline recipients apply to gift creation only. POST /gifts/{giftId}/claim does not create or accept inline recipients - it uses an orderRecipient object that captures the order’s shipping details for that specific claim.

Email override

If a Recipient has an emailOverride set, all gift notifications will be sent to that address. The original email field is retained as the primary identifier and is unaffected. This is useful for cases where a Recipient’s work email should be used for identification but notifications should go to a personal address.

PII Masking

The Recipient object contains significant personal data. If your API key does not have the recipients:read:unmasked scope, sensitive fields will be partially redacted in all responses:

Name: J*** D***
Email: j*******@e*****.com
Phone: (***) ***-1234
IDs: 3****
See Authentication & Security for details on configuring data access permissions.

How to Work with Recipients

Retrieving Recipients Search for and retrieve a list of Recipients based on your specified criteria:

GET /recipients

Filtering options:

Account
Name
Email
External ID

Retrieving Recipient by ID Retrieve the details of a specific Recipient:

GET /recipients/{recipientId}

Create Recipient Add a new Recipient to your Company’s contact list:

POST /recipients

Once created, a Recipient can be referenced by ID across multiple gift sends without re-submitting their details.

Update Recipient Update the details of a specific Recipient:

PATCH /recipients/{recipientId}

Delete Recipient by ID Permanently delete a specific Recipient from your Company’s contact list:

DELETE /recipients/{recipientId}

Deleting a Recipient is a permanent action and cannot be undone. Existing gifts sent to this Recipient will not be affected, but the Recipient record will no longer be retrievable.

Welcome

Start building

Our API Standards

Migrating to V3

Webhooks & Events

Recipients API: Manage Gift Recipients at Scale

The Recipient Object

Core Fields

Employee Details

Owner

Custom Fields

Key Concepts & Business Rules

Recipients are scoped to a Company

Managed list vs. inline

Email override

PII Masking

How to Work with Recipients

​The Recipient Object

​Core Fields

​Employee Details

​Owner

​Custom Fields

​Key Concepts & Business Rules

​Recipients are scoped to a Company

​Managed list vs. inline

​Email override

​PII Masking

​How to Work with Recipients

The Recipient Object

Core Fields

Employee Details

Owner

Custom Fields

Key Concepts & Business Rules

Recipients are scoped to a Company

Managed list vs. inline

Email override

PII Masking

How to Work with Recipients