Contacts API

Manage contacts and identity resolution.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/contacts	List contacts
POST	/api/agents/{id}/contacts	Create contact
GET	/api/agents/{id}/contacts/{contactId}	Get contact
PUT	/api/agents/{id}/contacts/{contactId}	Update contact
DELETE	/api/agents/{id}/contacts/{contactId}	Delete contact

List Contacts

GET /api/agents/{id}/contacts?search=john&limit=50

Query Parameters

Parameter	Type	Description
search	string	Search name, email, phone
tag	string	Filter by tag
limit	number	Max results (default: 50)
offset	number	Skip results

Response

{
  "contacts": [
    {
      "id": "contact-123",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "telegram": "@johndoe",
      "tags": ["customer", "vip"],
      "created_at": "2024-12-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 500,
    "limit": 50,
    "offset": 0
  }
}

Create Contact

POST /api/agents/{id}/contacts
Content-Type: application/json

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "telegram": "@johndoe",
  "whatsapp": "+1234567890",
  "twitter": "@johndoe",
  "external_id": "crm-123",
  "notes": "VIP customer",
  "tags": ["customer", "vip"],
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}

Response

{
  "id": "contact-123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-12-15T10:00:00Z"
}

Get Contact

GET /api/agents/{id}/contacts/{contactId}

Response

{
  "id": "contact-123",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "telegram": "@johndoe",
  "whatsapp": "+1234567890",
  "twitter": "@johndoe",
  "external_id": "crm-123",
  "notes": "VIP customer",
  "tags": ["customer", "vip"],
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise"
  },
  "created_at": "2024-12-01T00:00:00Z",
  "updated_at": "2024-12-15T10:00:00Z"
}

Update Contact

PUT /api/agents/{id}/contacts/{contactId}
Content-Type: application/json

Request Body

{
  "name": "John D. Doe",
  "tags": ["customer", "vip", "enterprise"],
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise",
    "mrr": 5000
  }
}

Delete Contact

DELETE /api/agents/{id}/contacts/{contactId}

Contact Fields

Field	Type	Description
name	string	Contact name (required)
email	string	Email address
phone	string	Phone number
telegram	string	Telegram username
whatsapp	string	WhatsApp number
twitter	string	Twitter handle
external_id	string	External system ID
notes	string	Free-form notes
tags	string[]	Array of tags
metadata	object	Custom metadata

Identity Resolution

Resolve contact by any identifier:

GET /api/agents/{id}/contacts/resolve?email=john@example.com
GET /api/agents/{id}/contacts/resolve?phone=+1234567890
GET /api/agents/{id}/contacts/resolve?telegram=@johndoe

Response

{
  "contact": {
    "id": "contact-123",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "matched_by": "email"
}

Import Contacts

POST /api/agents/{id}/contacts/import
Content-Type: multipart/form-data

CSV Format

name,email,phone,telegram,tags
John Doe,john@example.com,+1234567890,@johndoe,"customer,vip"
Jane Smith,jane@example.com,+0987654321,@janesmith,prospect

Export Contacts

GET /api/agents/{id}/contacts/export?format=csv

Errors

Code	Description
400	Invalid contact data
404	Contact not found
409	Duplicate contact

Examples

Create with Metadata

curl -X POST .../contacts \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "metadata": {
      "source": "website",
      "campaign": "summer-2024"
    }
  }'

Search by Tag

curl ".../contacts?tag=vip&limit=100"