Sign in
API Reference

Recipients

Manage your organization's recipient address book. Create, update, search, and delete recipients.

GET /api/v1/recipients

List recipients

Returns a paginated list of recipients in your organization.

Required scope

recipients.read

Query parameters

Parameter
Type
Required
Description
page
integer
No
Default 1
pageSize
integer
No
Default 20, max 100
searchKeyword
string
No
Search by name or email
GET /api/v1/recipients/{recipientId}

Get recipient

Returns details for a single recipient.

Required scope

recipients.read

Path parameters

recipientId
string
Yes
The recipient ID
POST /api/v1/recipients

Create recipient

Adds a new recipient to your organization's address book. Email must be unique per organization.

Required scope

recipients.write

Request body

JSON
{
  "email": "alice@giftronaut.com",
  "firstName": "Alice",
  "lastName": "Smith",
  "company": "Acme Corp",
  "department": "Marketing"
}

Request body fields

Field
Type
Required
Description
email
string
Yes
Recipient email address. Must be unique within your organization.
firstName
string
No
Recipient first name
lastName
string
No
Recipient last name
company
string
No
Recipient company name
department
string
No
Recipient department

Business rules

  • Email must be unique within your organization.
PUT /api/v1/recipients/{recipientId}

Update recipient

Updates recipient information. If email is changed, uniqueness is re-validated.

Required scope

recipients.write

Path parameters

recipientId
string
Yes
The recipient ID

Request body

JSON
{
  "email": "alice.new@giftronaut.com",
  "firstName": "Alice",
  "lastName": "Smith",
  "company": "Acme Corp",
  "department": "Product"
}

Request body fields

Field
Type
Required
Description
email
string
Yes
New email address. Must remain unique within your organization.
firstName
string
No
Recipient first name
lastName
string
No
Recipient last name
company
string
No
Recipient company name
department
string
No
Recipient department
DELETE /api/v1/recipients/{recipientId}

Delete recipient

Removes a recipient from your address book. Deletion is blocked if the recipient has a pending scheduled order.

Required scope

recipients.write

Path parameters

recipientId
string
Yes
The recipient ID

Error responses

422
RECIPIENT_HAS_PENDING_ORDER — cannot delete a recipient with active scheduled orders.