Get recipient by ID

curl --request GET \
  --url https://api.snappy.com/public-api/v2/recipients/{recipientId} \
  --header 'X-Api-Key: <api-key>'

import requests

url = "https://api.snappy.com/public-api/v2/recipients/{recipientId}"

headers = {"X-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.snappy.com/public-api/v2/recipients/{recipientId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v2/recipients/{recipientId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v2/recipients/{recipientId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.snappy.com/public-api/v2/recipients/{recipientId}")
  .header("X-Api-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v2/recipients/{recipientId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "xyz12345",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "updatedAt": "2022-12-06T09:50:38.536Z",
  "birthday": "2022-12-06T00:00:00.000Z",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "emailOverride": "john.doe.override@example.com",
  "mobilePhone": "+1234567890",
  "country": "US",
  "externalId": "1234567890",
  "accounts": [
    "a12bcd34",
    "a56bcd78"
  ],
  "type": "employee",
  "recipientCustomFields": [
    {
      "fieldName": "petName",
      "displayName": "petName",
      "fieldValue": "Wesley"
    }
  ],
  "employee": {
    "workingSince": "2022-12-06T00:00:00.000Z",
    "department": "R&D"
  },
  "updatedBy": "abc12345",
  "source": "apiIntegration",
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  }
}

{
  "status": 400,
  "errorCode": "400_PBLC_001",
  "message": "Bad Request"
}

{
  "status": 401,
  "errorCode": "401_PBLC_001",
  "message": "Unauthorized"
}

{
  "status": 404,
  "errorCode": "404_PBLC_001",
  "message": "Not Found"
}

{
  "status": 422,
  "errorCode": "422_PBLC_001",
  "message": "Unprocessable Entity"
}

Recipients

Get recipient by ID

Use this endpoint to retrieve the full details of a specific Recipient.

Required fields:

recipientId - the Recipient identifier, passed as a path parameter

Optional parameters:

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

Please note:

PII fields are masked unless your API key has the recipients:read:unmasked scope.
Returns 404 if no Recipient exists for the supplied recipientId, or if it’s not accessible to the calling API key.
Returns 422 for business-rule violations.

Permissions

Requires: recipients:read:masked or recipients:read:unmasked

GET

recipients

{recipientId}

Get recipient by ID

curl --request GET \
  --url https://api.snappy.com/public-api/v2/recipients/{recipientId} \
  --header 'X-Api-Key: <api-key>'

import requests

url = "https://api.snappy.com/public-api/v2/recipients/{recipientId}"

headers = {"X-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.snappy.com/public-api/v2/recipients/{recipientId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v2/recipients/{recipientId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v2/recipients/{recipientId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.snappy.com/public-api/v2/recipients/{recipientId}")
  .header("X-Api-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v2/recipients/{recipientId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "xyz12345",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "updatedAt": "2022-12-06T09:50:38.536Z",
  "birthday": "2022-12-06T00:00:00.000Z",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "emailOverride": "john.doe.override@example.com",
  "mobilePhone": "+1234567890",
  "country": "US",
  "externalId": "1234567890",
  "accounts": [
    "a12bcd34",
    "a56bcd78"
  ],
  "type": "employee",
  "recipientCustomFields": [
    {
      "fieldName": "petName",
      "displayName": "petName",
      "fieldValue": "Wesley"
    }
  ],
  "employee": {
    "workingSince": "2022-12-06T00:00:00.000Z",
    "department": "R&D"
  },
  "updatedBy": "abc12345",
  "source": "apiIntegration",
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  }
}

{
  "status": 400,
  "errorCode": "400_PBLC_001",
  "message": "Bad Request"
}

{
  "status": 401,
  "errorCode": "401_PBLC_001",
  "message": "Unauthorized"
}

{
  "status": 404,
  "errorCode": "404_PBLC_001",
  "message": "Not Found"
}

{
  "status": 422,
  "errorCode": "422_PBLC_001",
  "message": "Unprocessable Entity"
}

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"

Response

Recipient details.

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

Create recipient

Update recipient

Authentication

Marketplace

Gifting

Administration

Get recipient by ID

Required fields:

Optional parameters:

Please note:

Permissions

Authorizations

Company Level Authentication

Getting Your API Key

Using Your API Key

API Key Management

Enhanced Security (mTLS)

Headers

Path Parameters

Query Parameters

Response