Contacts API
Manage contacts for your organization.
Manage contacts for your organization.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/contacts | List contacts |
POST | /api/v1/contacts | Create contact |
GET | /api/v1/contacts/:id | Get by contact ID or email |
PUT | /api/v1/contacts/:id | Update by contact ID or email |
DELETE | /api/v1/contacts/:id | Delete by contact ID or email |
List contacts
GET /api/v1/contacts?page=1&limit=25&search=jane
Query params:
page(default1)limit(max100)searchsort_by(email,firstName,lastName,createdAt)sort_order(ascordesc)
Create contact
POST /api/v1/contacts
Body:
{
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Smith"
}
Returns 201 with created contact.
Get contact
id can be either:
- Convex contact ID
- URL-encoded email (for example
jane%40example.com)
Update contact
PUT /api/v1/contacts/:id
Partial updates are supported.
Delete contact
DELETE /api/v1/contacts/:id
Custom properties
Custom contact properties (such as language, timezone, and user-defined fields) are managed through the dashboard. The REST API currently handles core contact fields only (email, firstName, lastName, source, createdAt, updatedAt).
Contact response shape
{
"data": {
"id": "j57...",
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Smith",
"source": "api",
"createdAt": "2026-02-17T14:00:00.000Z",
"updatedAt": "2026-02-17T14:00:00.000Z"
}
}