Contacts API

Base URL:

https://api.dmly.io/rest

The Contacts API allows you to create, search, update, delete, and manage tags for contacts programmatically inside your DMLY workspace.

All endpoints require authentication using the x-api-key header.

VIDEO GUIDE:

🔐 Authentication

Every request must include:

x-api-key: YOUR_API_KEY

You can generate your API key from:

DMLY → Integrations → REST API → Edit Setup

📌 Contact Endpoints Overview

1⃣ Search Contacts

Endpoint

GET /v1/contacts

Description

Search contacts using filters, pagination, tags, or free-text search.

Query Parameters

Example Request

curl -X GET "https://api.dmly.io/rest/v1/contacts?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Response

200 OK → Returns array of contacts

2⃣ Create New Contact

Endpoint

POST /v1/contacts

Description

Create a new contact in DMLY.

Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Example Request

curl -X POST "https://api.dmly.io/rest/v1/contacts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phoneNumber": "+15551234567",
    "workspace": {
      "id": "workspace_id_here"
    }
  }'

Response

200 OK → Returns created contact object

3⃣ Get Contact by ID

Endpoint

GET /v1/contacts/{contactId}

Path Parameters

Example

curl -X GET "https://api.dmly.io/rest/v1/contacts/12345" \
  -H "x-api-key: YOUR_API_KEY"

4⃣ Update Contact by ID

Endpoint

PUT /v1/contacts/{contactId}

Description

Update an existing contact.

Example

curl -X PUT "https://api.dmly.io/rest/v1/contacts/12345" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Updated",
    "stage": "Lead"
  }'

5⃣ Delete Contact by ID

Endpoint

DELETE /v1/contacts/{contactId}

Example

curl -X DELETE "https://api.dmly.io/rest/v1/contacts/12345" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "success": true
}

6⃣ Add Tags to Contact

Endpoint

POST /v1/contacts/{contactId}/tags/add

Example

curl -X POST "https://api.dmly.io/rest/v1/contacts/12345/tags/add" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["VIP", "Purchased"]
  }'

Response

{
  "id": "12345",
  "tags": ["VIP", "Purchased"]
}

7⃣ Remove Tags from Contact

Endpoint

POST /v1/contacts/{contactId}/tags/remove

Example

curl -X POST "https://api.dmly.io/rest/v1/contacts/12345/tags/remove" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["VIP"]
  }'

📦 Contact Schema

{
  "id": "string",
  "name": "string",
  "phoneNumber": "string",
  "workspace": {
    "id": "string",
    "title": "string"
  },
  "stage": "Subscriber | Engaged | Lead | Marketing qualified lead (MQL) | Sales qualified lead (SQL)",
  "notes": "string",
  "customFields": {},
  "tags": ["string"]
}

🏷 Tag Response Schema

{
  "id": "string",
  "tags": ["string"]
}

🗑 Delete Response Schema

{
  "success": true
}

⚠️ Best Practices

• Always validate phone numbers in international format.

• Use pagination when fetching large contact lists.

• Avoid frequent bulk updates to prevent rate limiting.

• Store contact IDs after creation for efficient updates.

• Secure your API key — never expose it in frontend code.