> ## 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: 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.

<Tip>
  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.
</Tip>

## 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.

```json theme={null}
{
  "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:

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

<Note>
  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.
</Note>

#### **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****`
  <Tip>
    See [Authentication & Security](/pages/authentication-and-security#data-privacy-pii-masking) for details on configuring data access permissions.
  </Tip>

***

## How to Work with Recipients

**Retrieving Recipients**

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

```text theme={null}
GET /recipients
```

Filtering options:

* Account
* Name
* Email
* External ID

***

**Retrieving Recipient by ID**

Retrieve the details of **a specific Recipient**:

```text theme={null}
GET /recipients/{recipientId}
```

***

**Create Recipient**

Add a new Recipient to your Company's contact list:

```text theme={null}
POST /recipients
```

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

***

**Update Recipient**

Update the details of a specific Recipient:

```text theme={null}
PATCH /recipients/{recipientId}
```

***

**Delete Recipient by ID**

Permanently delete a specific Recipient from your Company's contact list:

```text theme={null}
DELETE /recipients/{recipientId}
```

<Warning>
  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.
</Warning>