Docs/Contacts
🔑 API Key required

Contacts API

Full contact management scoped to a firm. Each contact supports multiple phones, emails, addresses, and free-form tags. Includes bulk operations and seamless background CSV importing.

When to use this module

  • Add or edit contacts → CRUD endpoints (POST /contact/create, PUT /contact/update)
  • Organize contacts with labels → tagging endpoints (PUT /contact/add-or-remove-tags)
  • Import contacts from spreadsheet → CSV import (POST /contact/import/upload)
  • Send WhatsApp messages → contacts provide recipient data (phone numbers)

All Endpoints

MethodRouteAuthDescription
POST/api/V1/Contact/create🔑 API KeyCreate a new contact
GET/api/V1/Contact/get/{id}🔑 API KeyGet contact by ID
POST/api/V1/Contact/getall🔑 API KeyPaginated contact list (filter, sort, tag filter)
PUT/api/V1/Contact/update🔑 API KeyUpdate contact + nested children (phones, emails, addresses)
DELETE/api/V1/Contact/delete🔑 API KeySoft-delete a single contact
DELETE/api/V1/Contact/bulkdelete🔑 API KeyBulk soft-delete by list of IDs
GET/api/V1/Contact/search🔑 API KeySearch contacts (mode: whatsapp filters by phone)
PUT/api/V1/Contact/add-or-remove-tags🔑 API KeyAdd/remove tags on one contact
PUT/api/V1/Contact/bulk-add-or-remove-tags🔑 API KeyBulk tag operations across multiple contacts
GET/api/V1/Contact/tags/search🔑 API KeySearch existing tag names in the firm
POST/api/V1/Contact/import/upload🔑 API KeyQueue CSV import job (returns 202 Accepted)
POST

/api/V1/Contact/create

Add a new contact to your firm's database. This endpoint is powerful because you can include all of their phone numbers, email addresses, and postal addresses in just one single request.

Request Body

JSON
{
  "firstName": "John",
  "lastName": "Smith",
  "gender": "Male",
  "isActive": true,
  "profilePic": "https://url.to.pic/john.png",
  "phones": [
    { "phone": "9876543210", "phoneCC": "+91", "type": 1, "isPrimary": true }
  ],
  "emails": [
    { "email": "john@company.com", "type": 1, "isPrimary": true }
  ],
  "addresses": [
    {
      "type": 1,
      "line1": "123 Main St",
      "line2": "Suite 400",
      "landmark": "Near Central Park",
      "city": "Mumbai",
      "state": "Maharashtra",
      "country": "India",
      "pinCode": "400001"
    }
  ],
  "tags": ["VIP", "Lead"]
}

Request Parameters

FieldTypeRequiredDescription
firstNamestring(50)requiredContact's first name
lastNamestring(50)requiredContact's last name
genderstringoptionalMale / Female / Other
isActivebooloptionalDefaults to true
profilePicstringoptionalAzure Blob URL of profile picture
phonesarrayoptionalList of phone entries; only one can be isPrimary
emailsarrayoptionalList of email entries; only one can be isPrimary
addressesarrayoptionalList of postal addresses
tagsstring[]optionalList of free-form tags
POST

/api/V1/Contact/getall

Retrieve your contacts in a neat, organized list. You can easily filter by tags, search by name, and sort the results exactly how you need them.

Request Body

JSON
{
  "page": 1,
  "pageSize": 20,
  "searchTerm": "",
  "sortBy": "firstName",
  "sortDesc": false,
  "tags": []
}

Request Parameters

FieldTypeDescription
pageint1-based page number
pageSizeintNumber of records per page (max 100)
searchTermstringFree-text search across name, email, phone
sortBystringField to sort by (e.g. firstName, lastName)
sortDescboolDescending sort when true
tagsstring[]Filter to contacts having ALL listed tags
DELETE

/api/V1/Contact/bulkdelete

Safely removes multiple contacts at once. The contacts are hidden from your active list and search results, but their historical data is kept safe in the background.

Request Body

JSON
{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7cb2a123-1234-5678-abcd-ef9876543210"
  ]
}
Please note that deleting contacts cannot be undone through the API. While they disappear from your active lists, we securely retain their records to preserve your historical activity and reporting.
PUT

/api/V1/Contact/add-or-remove-tags

Organize your contacts by adding or removing custom tags. You can create new tags on the fly—just type whatever label helps you categorize them best! Use /bulk-add-or-remove-tags to update multiple contacts at once.

Request Body

JSON
{
  "contactId": "guid-here",
  "tagsToAdd": ["VIP", "Lead"],
  "tagsToRemove": ["Prospect"]
}

Tag Search

Easily search through all the tags you've created. This is perfect for building autocomplete drop-downs in your own application.

Tags are case-insensitive and deduplicated per contact. A contact cannot have the same tag twice regardless of casing.
POST

/api/V1/Contact/import/upload

Quickly import a large list of contacts using a CSV file. You'll first upload your file through the File Upload section to get a unique file ID. Then, use this endpoint to start the import process in the background.

CSV Import Flow

Step 1 - Upload your CSV file Use the file upload tool to securely send us your CSV document. → We'll give you a unique File ID in return. Step 2 - Start the Import Provide your unique File ID to this endpoint to begin importing. → Our system immediately queues your contacts for processing. Step 3 - Success Confirmation You'll receive an instant confirmation that the import has started. → "Import queued successfully"

Response (HTTP 202)

JSON
{
  "isSuccess": true,
  "data": null,
  "message": "Import queued successfully"
}
Previous App Marketplace Next WhatsApp Messages