Skip to main content

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.

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

FieldTypeDescription
idstringUnique identifier for the Recipient
firstNamestringRecipient’s first name
lastNamestringRecipient’s last name
emailstringRecipient’s primary email address. Used as the primary identifier
emailOverridestringIf set, gift notifications will be sent to this address instead of email. The original email is retained as the primary identifier
mobilePhonestringRecipient’s mobile phone number
countrystringRecipient’s country, identified by ISO 3166-1 alpha-2 country code (e.g. "US")
externalIdstringYour internal ID for this Recipient. Use this to map Snappy Recipients to records in your own system (e.g. HRIS, CRM)
typestringThe Recipient type (currently supporting only employee)
accountsarrayList of Account IDs this Recipient belongs to. A Recipient can belong to multiple Accounts and receive gifts from all of them
birthdaystringISO 8601 timestamp of the Recipient’s birthday. Can be used to trigger automated birthday gifting flows
sourcestringHow the Recipient was created (e.g. apiIntegration). TBD — full list of possible values coming soon
createdAtstringISO 8601 timestamp of when the Recipient was created
updatedAtstringISO 8601 timestamp of the last update
updatedBystringThe 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.
FieldTypeDescription
employee.workingSincestringISO 8601 timestamp of the Recipient’s employment start date. Can be used to trigger work anniversary gifting flows
employee.departmentstringThe department the Recipient belongs to

​
Owner

The owner object represents the person responsible for this Recipient — typically their manager or HR contact.
FieldTypeDescription
owner.firstNamestringOwner’s first name
owner.lastNamestringOwner’s last name
owner.emailstringOwner’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.
FieldTypeDescription
recipientCustomFields[].fieldNamestringThe internal name of the custom field
recipientCustomFields[].displayNamestringThe display name of the custom field
recipientCustomFields[].fieldValuestringThe 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.
Last modified on April 30, 2026