Contacts API

Manage your contact database programmatically. Create, update, import, and organize contacts with tags and custom fields.

List Contacts

Get all contacts with optional filtering and pagination.

GET /api/contacts

Query Parameters:

Example Request:

GET /api/contacts?search=john&page=1&pageSize=20&tags=[1,2]

Response:

{
  "contacts": [
    {
      "id": 1,
      "phoneNumber": "+1234567890",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "tags": [
        { "id": 1, "name": "VIP", "color": "#3b82f6" }
      ],
      "customFields": {
        "company": "Acme Corp",
        "position": "Manager"
      },
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

cURL Example:

curl -X GET "https://waflow.edesy.in/api/contacts?search=john&page=1&pageSize=20" \
  -H "Content-Type: application/json" \
  -b cookies.txt

Create Contact

Create a new contact in your workspace.

POST /api/contacts

Request Body:

{
  "phoneNumber": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "customFields": {
    "company": "Acme Corp"
  }
}

Response:

{
  "id": 1,
  "phoneNumber": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "tags": [],
  "customFields": {
    "company": "Acme Corp"
  },
  "createdAt": "2025-01-01T00:00:00.000Z"
}

JavaScript Example:

const response = await fetch('https://waflow.edesy.in/api/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    phoneNumber: '+1234567890',
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    customFields: {
      company: 'Acme Corp'
    }
  })
});

const data = await response.json();
console.log(data);

Update Contact

Update an existing contact's information.

PUT /api/contacts/{id}

Path Parameters:

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]"
}

Response:

{
  "id": 1,
  "phoneNumber": "+1234567890",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "tags": [],
  "customFields": {},
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

Bulk Import Contacts

Import multiple contacts at once with validation and duplicate handling.

POST /api/contacts/import

Request Body:

{
  "contacts": [
    {
      "phoneNumber": "+1234567890",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "tags": ["VIP", "Customer"]
    },
    {
      "phoneNumber": "+1987654321",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]"
    }
  ],
  "options": {
    "skipDuplicates": true,
    "updateExisting": false
  }
}

Options:

Response:

{
  "success": true,
  "imported": 1,
  "skipped": 0,
  "failed": 0,
  "details": {
    "successful": ["[email protected]"],
    "duplicates": [],
    "failed": []
  }
}

cURL Example:

curl -X POST "https://waflow.edesy.in/api/contacts/import" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "contacts": [
      {
        "phoneNumber": "+1234567890",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "tags": ["VIP"]
      }
    ],
    "options": {
      "skipDuplicates": true,
      "updateExisting": false
    }
  }'

Phone Number Format

Phone numbers should be in E.164 format:

• Include country code with + prefix
• No spaces, dashes, or parentheses
• Examples: +1234567890, +919876543210

Valid formats:

• +1234567890 (US)
• +919876543210 (India)
• +447911123456 (UK)

Invalid formats:

• 1234567890 (missing +)
• +1 234 567 890 (contains spaces)
• (123) 456-7890 (local format)

Rate Limits