Short Links

Create branded short links using go.ping.co.zw/{code} to track clicks and simplify URLs in your messages. Short links are perfect for WhatsApp templates, SMS campaigns, and any notification that includes a URL.

The short link model

The short link model contains all the information about a shortened URL, including its destination, click tracking data, and status.

Properties

Name
public_id
Type
string
Description
Unique identifier for the short link (UUID format).
Name
short_code
Type
string
Description
The unique code used in the short URL (e.g., promo2025 in go.ping.co.zw/promo2025).
Name
short_url
Type
string
Description
The full short URL: https://go.ping.co.zw/{short_code}.
Name
destination_url
Type
string
Description
The original long URL that the short link redirects to.
Name
title
Type
string
Description
Optional label to help you identify the link.
Name
click_count
Type
integer
Description
Total number of times the short link has been clicked.
Name
is_active
Type
boolean
Description
Whether the short link is active. Inactive links return a 404.
Name
expires_at
Type
timestamp
Description
Optional expiration date. After this date the link returns a 410 Gone.
Name
date_created
Type
timestamp
Description
Timestamp of when the short link was created.

GET/v1/shortLinks

List short links

Retrieve a paginated list of short links belonging to your business.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key, or use Authorization: Bearer {token} with a JWT.
Name
X-Business-Id
Type
string
Description
Your business ID (required if your account has multiple businesses).

Optional parameters

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

Request

GET

/v1/shortLinks

curl -G https://api.ping.co.zw/v1/shortLinks \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d limit=10 \
  -d skip=0

Response

{
  "result": "success",
  "shortLinks": [
    {
      "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "short_code": "promo2025",
      "short_url": "https://go.ping.co.zw/promo2025",
      "destination_url": "https://example.com/summer-sale?utm_source=whatsapp",
      "title": "Summer Sale Campaign",
      "click_count": 342,
      "is_active": true,
      "expires_at": "2025-12-31T23:59:59",
      "date_created": "2025-01-15T10:30:00"
    }
  ],
  "total": 1
}

POST/v1/shortLinks

Create a short link

Create a new short link. You can provide a custom short code or let the system generate one automatically.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key, or use Authorization: Bearer {token} with a JWT.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
destination_url
Type
string
Description
The URL to redirect to. Must start with http:// or https://.

Optional attributes

Name
title
Type
string
Description
A label to help identify the link (e.g., "Summer Sale Campaign").
Name
short_code
Type
string
Description
Custom short code (3-20 alphanumeric characters). If omitted, a random 6-character code is generated.
Name
expires_at
Type
string
Description
Expiration date in ISO 8601 format (e.g., 2025-12-31T23:59:59Z). After this date the link returns 410 Gone.

Request

POST

/v1/shortLinks

curl -X POST https://api.ping.co.zw/v1/shortLinks \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://example.com/summer-sale?utm_source=whatsapp",
    "title": "Summer Sale Campaign",
    "short_code": "summer25"
  }'

Response

{
  "result": "success",
  "message": "Short link created",
  "shortLink": {
    "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_code": "summer25",
    "short_url": "https://go.ping.co.zw/summer25",
    "destination_url": "https://example.com/summer-sale?utm_source=whatsapp",
    "title": "Summer Sale Campaign"
  }
}

PUT/v1/shortLinks/:public_id

Update a short link

Update an existing short link. You can change the destination URL, title, active status, or expiration date. The short code cannot be changed after creation.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key, or use Authorization: Bearer {token} with a JWT.
Name
Content-Type
Type
string
Description
Must be application/json.

Optional attributes

Name
destination_url
Type
string
Description
New destination URL. Must start with http:// or https://.
Name
title
Type
string
Description
New title for the link.
Name
is_active
Type
boolean
Description
Set to false to deactivate the link (returns 404 when visited). Set to true to reactivate.
Name
expires_at
Type
string
Description
New expiration date in ISO 8601 format, or null to remove expiration.

Request

PUT

/v1/shortLinks/:public_id

curl -X PUT https://api.ping.co.zw/v1/shortLinks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://example.com/new-landing-page",
    "is_active": true
  }'

Response

{
  "result": "success",
  "message": "Short link updated",
  "shortLink": {
    "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_code": "summer25",
    "short_url": "https://go.ping.co.zw/summer25",
    "destination_url": "https://example.com/new-landing-page",
    "title": "Summer Sale Campaign",
    "is_active": true
  }
}

DELETE/v1/shortLinks/:public_id

Delete a short link

Permanently delete a short link. This action cannot be undone. Once deleted, the short code becomes available for reuse.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key, or use Authorization: Bearer {token} with a JWT.

Request

DELETE

/v1/shortLinks/:public_id

curl -X DELETE https://api.ping.co.zw/v1/shortLinks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "message": "Short link deleted"
}

WhatsApp template integration

Short links are designed to work seamlessly with WhatsApp message templates. When creating a template with a URL button, use the short link domain as the base URL and pass the short code as a variable.

How it works

Create a short link for each campaign or destination (via API or Ping dashboard)
Set up your WhatsApp template with a URL button using https://go.ping.co.zw/{{1}}
When sending the template, pass the short code as the button variable
Track clicks — every time a recipient taps the link, the click count increments

Example: Sending a template with a short link

When you send a WhatsApp template message that has a URL button, include the short code in the button component parameters.

The template URL button should be configured as:

URL type: Dynamic
URL: https://go.ping.co.zw/{{1}}

When sending, pass just the short code (e.g., summer25) as the variable — not the full URL.

Request

POST

/v1/notification/api/whatsapp/send

curl -X POST https://api.ping.co.zw/v1/notification/api/whatsapp/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "template_name": "summer_sale",
    "template_data": {
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "John"}
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": 0,
          "parameters": [
            {"type": "text", "text": "summer25"}
          ]
        }
      ]
    }
  }'

The recipient sees a WhatsApp message with a button linking to https://go.ping.co.zw/summer25, which redirects to your destination URL.