> ## 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.
# Recipients API (V2): Manage Gift Recipients at Scale
> Create, retrieve, update, and delete recipients programmatically. Build recipient lists for campaigns and automated triggers.
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](/pages/snappy-core-concepts-and-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 `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.
```json theme={null} theme={null}
{
"campaignId": "cmp_12345",
"recipients": [
{
"recipientId": "rec_12345",
"key": "jane-doe-anniversary-2026"
}
]
}
```
**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:
```json theme={null} theme={null}
{
"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****`
See [Authentication & Security](/pages/authentication-and-security#data-privacy-pii-masking) for details on configuring data access permissions.
***
## How to Work with Recipients
**List Recipients**
Search for and retrieve a list of Recipients based on your specified criteria:
```text theme={null} theme={null}
GET /v2/recipients
```
Filtering options:
* Account
* Name
* Email
* External ID
**Get a Recipient by ID**
```text theme={null} theme={null}
GET /v2/recipients/{recipientId}
```
**Create Recipient**
Add a new Recipient to your Company's contact list:
```text theme={null} theme={null}
POST /v2/recipients
```
Once created, a Recipient can be referenced by ID across multiple gift sends without re-submitting their details.
**Update Recipient**
```text theme={null} theme={null}
PATCH /v2/recipients/{recipientId}
```
**Delete Recipient by ID**
```text theme={null} theme={null}
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.