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.
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 employee only) |
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 date of the Recipient’s birthday. Can be used to trigger automated birthday gifting flows |
source | object | Object indicating how the Recipient was created. Contains type - one of: apiIntegration, hrisIntegration, manual, ftpIntegration, fileSync |
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’s populated 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 date 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 let you 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. 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 /v2/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-2026"
}
]
}
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-2026"
}
]
}
Field-name reminder: inline recipients (used inside POST /v2/gifts) use firstname / lastname / phone (lowercase). The standalone Recipient resource managed by this API uses firstName / lastName / mobilePhone (camelCase). Same data, different field names depending on which surface you’re using.
Inline recipients apply to gift creation only. POST /v2/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 when 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****
How to Work with Recipients
List Recipients
Search for and retrieve a list of Recipients based on your specified criteria:
Filtering options:
- Account
- Name
- Email
- External ID
Get a Recipient by ID
GET /v2/recipients/{recipientId}
Once created, a Recipient can be referenced by ID across multiple gift sends without re-submitting their details.
PATCH /v2/recipients/{recipientId}
DELETE /v2/recipients/{recipientId}
Deleting a Recipient is permanent and cannot be undone. Existing gifts sent to this Recipient will not be affected, but the Recipient record will no longer be retrievable.
