Recipients

Recipients are contacts stored in your Ping account that can receive SMS, WhatsApp, and email notifications. Organize recipients into groups for efficient bulk messaging.

The recipient model

The recipient model contains contact information for individuals who can receive notifications through your account.

Properties

Name
id
Type
integer
Description
Unique identifier for the recipient.
Name
public_id
Type
string
Description
Public UUID for the recipient.
Name
first_name
Type
string
Description
Recipient's first name.
Name
last_name
Type
string
Description
Recipient's last name.
Name
email
Type
string
Description
Email address for email notifications.
Name
sms_phone
Type
string
Description
Phone number for SMS notifications in E.164 format.
Name
whatsapp_phone
Type
string
Description
Phone number for WhatsApp messages in E.164 format.
Name
street
Type
string
Description
Street address (optional).
Name
city
Type
string
Description
City (optional).
Name
state
Type
string
Description
State or province (optional).
Name
zip_code
Type
string
Description
Postal code (optional).
Name
country
Type
string
Description
Country code (ISO 3166-1 alpha-2).
Name
tags
Type
array
Description
Array of tags for categorization and filtering.
Name
notes
Type
string
Description
Internal notes about the recipient.
Name
created_at
Type
timestamp
Description
Timestamp of when the recipient was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the recipient was last updated.

POST/v1/add/recipient

Create recipient

Add a new recipient to your account. At least one contact method (email, SMS phone, or WhatsApp phone) is required.

Required headers

Name
Authorization
Type
string
Description
Bearer token for authentication.
Name
User-Type
Type
string
Description
Must be user, adminuser, or agent.
Name
X-Business-Id
Type
integer
Description
Business ID to associate the recipient with.

Required attributes

Name
first_name
Type
string
Description
Recipient's first name.
Name
last_name
Type
string
Description
Recipient's last name.

Optional attributes

Name
email
Type
string
Description
Email address.
Name
sms_phone
Type
string
Description
Phone number for SMS (E.164 format).
Name
whatsapp_phone
Type
string
Description
Phone number for WhatsApp (E.164 format).
Name
street
Type
string
Description
Street address.
Name
city
Type
string
Description
City.
Name
state
Type
string
Description
State or province.
Name
zip_code
Type
string
Description
Postal code.
Name
country
Type
string
Description
Country code (e.g., "ZW", "US").
Name
tags
Type
array
Description
Tags for categorization (e.g., ["vip", "newsletter"]).
Name
notes
Type
string
Description
Internal notes.

Request

POST

/v1/add/recipient

curl -X POST https://api.ping.co.zw/v1/add/recipient \
  -H "Authorization: Bearer {token}" \
  -H "User-Type: user" \
  -H "X-Business-Id: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "sms_phone": "+263771234567",
    "whatsapp_phone": "+263771234567",
    "city": "Harare",
    "country": "ZW",
    "tags": ["customer", "vip"]
  }'

Response

{
  "result": "success",
  "message": "Recipient created successfully",
  "recipient": {
    "id": 42,
    "public_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "sms_phone": "+263771234567",
    "whatsapp_phone": "+263771234567",
    "city": "Harare",
    "country": "ZW",
    "tags": ["customer", "vip"],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

GET/v1/get/recipients

List recipients

Retrieve a paginated list of all recipients in your business account.

Required headers

Name
Authorization
Type
string
Description
Bearer token for authentication.
Name
X-Business-Id
Type
integer
Description
Business ID to fetch recipients from.

Optional parameters

Name
skip
Type
integer
Description
Number of records to skip (default: 0).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 50).

Request

GET

/v1/get/recipients

curl -G https://api.ping.co.zw/v1/get/recipients \
  -H "Authorization: Bearer {token}" \
  -H "X-Business-Id: 1" \
  -d skip=0 \
  -d limit=50

Response

{
  "result": "success",
  "recipients": [
    {
      "id": 42,
      "public_id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "sms_phone": "+263771234567",
      "whatsapp_phone": "+263771234567",
      "tags": ["customer", "vip"],
      "created_at": "15/01/2025"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 50
}

GET/v1/get/recipient/:id

Retrieve recipient

Retrieve a single recipient by their ID.

Required headers

Name
Authorization
Type
string
Description
Bearer token for authentication.

Request

GET

/v1/get/recipient/42

curl https://api.ping.co.zw/v1/get/recipient/42 \
  -H "Authorization: Bearer {token}"

Response

{
  "result": "success",
  "recipient": {
    "id": 42,
    "public_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "sms_phone": "+263771234567",
    "whatsapp_phone": "+263771234567",
    "city": "Harare",
    "country": "ZW",
    "tags": ["customer", "vip"],
    "notes": "",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

PUT/v1/update/recipient/:id

Update recipient

Update an existing recipient's information. Only provided fields will be updated.

Required headers

Name
Authorization
Type
string
Description
Bearer token for authentication.

Optional attributes

All recipient fields can be updated. Only include fields you want to change.

Request

PUT

/v1/update/recipient/42

curl -X PUT https://api.ping.co.zw/v1/update/recipient/42 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "tags": ["customer", "vip", "newsletter"]
  }'

Response

{
  "result": "success",
  "message": "Recipient updated successfully",
  "recipient": {
    "id": 42,
    "public_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "sms_phone": "+263771234567",
    "tags": ["customer", "vip", "newsletter"],
    "updated_at": "2025-01-15T11:45:00Z"
  }
}

DELETE/v1/delete/recipient/:id

Delete recipient

Permanently delete a recipient from your account.

Required headers

Name
Authorization
Type
string
Description
Bearer token for authentication.

Request

DELETE

/v1/delete/recipient/42

curl -X DELETE https://api.ping.co.zw/v1/delete/recipient/42 \
  -H "Authorization: Bearer {token}"

Response

{
  "result": "success",
  "message": "Recipient deleted successfully"
}