PingStackDevelopers
DocsCore APIs

Contacts API

Manage workspace contacts, search customer records, handle custom metadata fields, and perform bulk batch imports.

5 min read•API v1

Contacts Overview

Contacts represent individual customer records identified by their normalized phone number. Phone normalization strips spaces, hyphens, and non-numeric characters, ensuring seamless cross-referencing between international and local formats.

Available Endpoints

* `GET /api/v1/contacts` — List contacts with search and pagination (`page`, `pageSize`, `search`, `tag`). * `POST /api/v1/contacts` — Create or upsert a contact (`name`, `phone_number`, `email`, `custom_fields`, `tags`). * `GET /api/v1/contacts/{id}` — Retrieve single contact. * `PATCH /api/v1/contacts/{id}` — Update contact fields. * `DELETE /api/v1/contacts/{id}` — Delete contact. * `POST /api/v1/contacts/bulk` — Bulk upsert up to 500 contacts per batch. * `DELETE /api/v1/contacts/bulk` — Bulk delete contacts.

Bulk Contact Operations

The bulk endpoint processes arrays of contact records and reports partial failures with per-index error details.
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", "tags": ["vip"] },
      { "name": "Meera", "phone": "919876543211", "custom_fields": { "plan": "Enterprise" } }
    ]
  }'
PreviousMessages APINextGroups & Audiences