Contacts Reference

Endpoints for creating, updating, searching, and managing customer contact records and custom metadata fields.

GET

/api/v1/contacts

Returns a paginated list of contacts with optional search and tag filters.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 50)
search	string	No	Search term for name or phone
tag	string	No	Filter by tag label

Code Example (5 Languages)

curl "https://app.pingstack.in/api/v1/contacts?search=Rahul" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY"

Response Example

JSON

{
  "success": true,
  "data": [
    {
      "id": "c1...",
      "name": "Rahul Sharma",
      "phone_number": "919876543210",
      "email": "rahul@example.com",
      "tags": ["vip"]
    }
  ],
  "request_id": "req_1c2d3e4f"
}

POST

/api/v1/contacts

Creates a new contact or upserts if phone number exists.

Request Body Parameters

Field	Type	Required	Description
phone_number	string	Yes	Phone number with country code
name	string	No	Customer full name
email	string	No	Email address
tags	array	No	Array of tag strings
custom_fields	object	No	Key-value custom attributes

Code Example (5 Languages)

curl -X POST "https://app.pingstack.in/api/v1/contacts" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aarav Gupta",
    "phone_number": "919876543210",
    "tags": ["retail", "vip"]
  }'

Response Example

JSON

{
  "success": true,
  "data": {
    "id": "c1a2b3c4-...",
    "name": "Aarav Gupta",
    "phone_number": "919876543210",
    "tags": ["retail", "vip"],
    "created_at": "2026-09-10T10:00:00.000Z"
  },
  "request_id": "req_2d3e4f5a"
}

POST

/api/v1/contacts/bulk

Batch imports up to 500 contacts per request with partial failure handling.

Code Example (5 Languages)

curl -X POST "https://app.pingstack.in/api/v1/contacts/bulk" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "name": "Aarav", "phone": "919876543210" },
      { "name": "Meera", "phone": "919876543211" }
    ]
  }'

Response Example

JSON

{
  "success": true,
  "data": {
    "total_submitted": 1,
    "processed_count": 1,
    "failed_count": 0,
    "contacts": [{ "id": "c1...", "name": "Aarav", "phone_number": "919876543210" }]
  },
  "request_id": "req_3e4f5a6b"
}

All Reference Endpoints