Update recipient

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/recipients/{recipientId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com"
}
'

{
  "id": "xyz12345",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "updatedAt": "2022-12-06T09:50:38.536Z",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com",
  "country": "US",
  "accounts": [
    "a12bcd34",
    "a56bcd78"
  ],
  "type": "employee",
  "updatedBy": "abc12345",
  "source": {
    "type": "apiIntegration"
  }
}

Recipients

Update recipient

Use this endpoint to update the details of a specific Recipient, including their contact information, employee details, and custom fields.

Required fields:

recipientId - the Recipient identifier, passed as a path parameter

Optional fields: (in request body - all updatable)

firstName, lastName - names
email, emailOverride - email and notification override
mobilePhone - phone
country - ISO 3166-1 alpha-2 country code
birthday - ISO 8601 date
accounts - array of Account IDs (replaces existing list)
type - Recipient type
employee - workingSince, department
recipientCustomFields - array of custom field objects

Optional parameters

companyId query parameter - Company ID (when not inferable from the calling key)
Request-Source header - source of the request

Behavior Notes:

Returns the full updated Recipient on success.
Returns 404 if the Recipient doesn’t exist or isn’t accessible.
Returns 422 for business-rule violations (e.g. invalid Account IDs).
The accounts field is a replace, not merge - supplying it overwrites the existing list. To add or remove Accounts, fetch the current list first and submit the modified array.

Permissions

Requires: recipients:update

PATCH

recipients

{recipientId}

Update recipient

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/recipients/{recipientId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com"
}
'

{
  "id": "xyz12345",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "updatedAt": "2022-12-06T09:50:38.536Z",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com",
  "country": "US",
  "accounts": [
    "a12bcd34",
    "a56bcd78"
  ],
  "type": "employee",
  "updatedBy": "abc12345",
  "source": {
    "type": "apiIntegration"
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients.

Getting Your API Key

Create an API Key: Use the POST /v2/authentication/apiKeys endpoint to generate a new API key
Set Expiration: Choose from 30, 60, 90, or 180 days (default: 90 days)
Optional mTLS: Enable mutual TLS for enhanced security
Name Your Key: Provide a descriptive name for easy identification

Using Your API Key

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_24_CHARACTER_API_KEY

API Key Management

Maximum Keys: Up to 3 active API keys per company
Rotation: Delete old keys before creating new ones when at the limit
Security: Keys are hashed and cannot be retrieved after creation

Enhanced Security (mTLS)

For production environments, enable mutual TLS authentication:

Set enforceMtls: true when creating the API key
Contact support to obtain your client certificates
Use the mTLS endpoint: https://mtls-api.snappy.com/public-api

Headers

Request-Source

enum<string>

Source of the request

Available options:

api_native,

api_zapier,

api_salesforce,

api_ftp,

api_make

Example:

"api_native"

Path Parameters

recipientId

string

required

The id of the recipient

Pattern: ^[A-Za-z0-9]+$

Example:

"xyz12345"

Query Parameters

companyId

string

Company ID

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"12345678"

Body

application/json

Update recipient request body.

birthday

string

Date Format: YYYY-MM-DD.

Example:

"2022-12-06T00:00:00.000Z"

firstName

string

the first name of the recipient

Example:

"John"

lastName

string

the last name of the recipient

Example:

"Doe"

string

the email of the recipient, should be a valid email

Example:

"john.doe@example.com"

emailOverride

string

The sendingEmail of the recipient in the db, used to override the existing email.

Example:

"john.doe.override@example.com"

mobilePhone

string

Mobile phone number

Pattern: ^$|^[0-9 \-+().]{3,7}[0-9 \-+().]{3,7}[0-9]{3,7}$

Example:

"+1234567890"

country

string

Country code

Pattern: ^[A-Za-z]+$

Example:

"US"

accounts

string[]

The accounts ids that the recipient is associated with. Can be copied from Snappy's dashboard or queried in upcoming Accounts API

Minimum array length: 1

Example:

["a12bcd34", "a56bcd78"]

recipientCustomFields

object[]

The custom fields of the recipient.

Show child attributes

type

enum<string>

The type of employee.

Available options:

employee

Example:

"employee"

employee

object

The employee info object.

Show child attributes

Example:

{
  "workingSince": "2022-01-15T00:00:00.000Z",
  "department": "Engineering"
}

Response

Updated recipient.

string

required

The id of the recipient.

Example:

"xyz12345"

createdAt

string<date-time>

required

Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

updatedAt

string<date-time>

required

Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

firstName

string

required

the first name of the recipient

Example:

"John"

country

string

required

Country code

Pattern: ^[A-Za-z]+$

Example:

"US"

accounts

string[]

required

The accounts ids that the recipient is associated with

Minimum array length: 1

Example:

["a12bcd34", "a56bcd78"]

type

enum<string>

required

The type of employee.

Available options:

employee

Example:

"employee"

updatedBy

string | null

required

The id of the user who last updated the recipient.

Example:

"abc12345"

source

object

required

The data source of the recipient.

Show child attributes

Example:

{ "type": "apiIntegration" }

birthday

string

Date Format: YYYY-MM-DD.

Example:

"2022-12-06T00:00:00.000Z"

lastName

string

the last name of the recipient

Example:

"Doe"

string

the email of the recipient, should be a valid email

Example:

"john.doe@example.com"

emailOverride

string

The sendingEmail of the recipient in the db, used to override the existing email.

Example:

"john.doe.override@example.com"

mobilePhone

string

Mobile phone number

Pattern: ^$|^[0-9 \-+().]{3,7}[0-9 \-+().]{3,7}[0-9]{3,7}$

Example:

"+1234567890"

externalId

string

An external id used by the customer to track their recipients

Example:

"1234567890"

recipientCustomFields

object[]

The custom fields of the recipient.

Show child attributes

employee

object

The employee info object.

Show child attributes

Example:

{
  "workingSince": "2022-01-15T00:00:00.000Z",
  "department": "Engineering"
}

owner

object

The person in charge of the recipient's gifting.

Show child attributes

Example:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com"
}

Last modified on June 17, 2026

Get recipient by ID

Delete recipient by ID