Contacts API
The Contacts API allows you to programmatically manage contacts in your echowin account. You can create, read, update, and delete contacts, as well as manage custom fields and tags.
Table of Contents
Getting Started
Contact Operations
Notes Management
Assignments Management
Board Management
Tags & Custom Fields
Authentication
All API requests require authentication using an API key. Include your API key in the X-API-Key header:
X-API-Key: your-api-key-here/api/v1/contactsGet a paginated list of contacts for your team
Query Parameters
pageinteger(default: 1)Page number
limitinteger(default: 20)Number of results per page (max 100)
searchstringSearch contacts by name, email, or phone number
sortBystring(default: createdAt)Sort field: createdAt, firstName, lastName, email, number
sortOrderstring(default: desc)Sort order: asc or desc
tagIdsstringFilter by tag IDs (comma-separated)
Responses
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"number": "+15551234567",
"carrier": "AT&T",
"customFields": {
"company": "Acme Corp",
"role": "Manager"
},
"tags": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981"
},
{
"id": "tag-id-2",
"name": "Lead",
"color": "#3B82F6"
}
],
"crmStage": {
"id": "stage-id",
"name": "Lead"
},
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 150,
"totalPages": 8
},
"customFieldSchemas": [
{
"id": "field-id",
"name": "company",
"label": "Company",
"type": "text",
"required": false
}
],
"availableTags": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981"
},
{
"id": "tag-id-2",
"name": "Lead",
"color": "#3B82F6"
}
]
}API Tester
/api/v1/contacts/:contactIdGet detailed information about a specific contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Responses
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"number": "+15551234567",
"carrier": "AT&T",
"customFields": {
"company": "Acme Corp",
"role": "Manager"
},
"tags": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981"
}
],
"crmStage": {
"id": "stage-id",
"name": "Lead"
},
"notes": [
{
"id": "note-id",
"note": "Interested in premium plan",
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"createdAt": "2024-01-01T00:00:00.000Z"
},
"customFieldSchemas": [],
"availableTags": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981"
},
{
"id": "tag-id-2",
"name": "Lead",
"color": "#3B82F6"
}
]
}{
"error": "Contact not found"
}API Tester
/api/v1/contactsCreate a new contact
Request Body
firstNamestringContact's first name
lastNamestringContact's last name
emailstringContact's email address
numberstringrequiredContact's phone number (will be automatically cleaned)
carrierstringPhone carrier
customFieldsobjectCustom field values as key-value pairs
tagIdsarrayArray of existing tag IDs to assign
tagNamesarrayArray of tag names (will create new tags if they don't exist)
noteobjectOptional note to create for the contact. Object with 'note' (string, required) and 'type' (string, optional: GENERAL, INFO, WARNING, or DANGER)
assignUserIdsarrayArray of user IDs to assign to this contact
boardIdsarrayArray of board IDs to add the contact to
Responses
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"number": "+15551234567",
"carrier": "AT&T",
"customFields": {},
"tags": [
{
"id": "tag-id-1",
"name": "New Customer",
"color": "#3B82F6"
}
],
"createdAt": "2024-01-01T00:00:00.000Z"
},
"message": "Contact created successfully"
}{
"error": "Validation error",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}API Tester
/api/v1/contacts/:contactIdUpdate an existing contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Request Body
firstNamestringContact's first name
lastNamestringContact's last name
emailstringContact's email address
numberstringContact's phone number
carrierstringPhone carrier
customFieldsobjectCustom field values to update
crmStageIdstringCRM stage ID
tagIdsarrayArray of tag IDs (replaces all existing tags)
tagNamesarrayArray of tag names (creates new tags if needed, replaces all existing tags)
Responses
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"number": "+15551234567",
"customFields": {
"company": "New Company"
},
"tags": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981"
},
{
"id": "tag-id-2",
"name": "Customer",
"color": "#F59E0B"
}
]
},
"message": "Contact updated successfully"
}API Tester
/api/v1/contacts/:contactIdDelete a contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Responses
{
"message": "Contact deleted successfully"
}{
"error": "Contact not found"
}API Tester
/api/v1/contacts/bulkCreate multiple contacts in a single request
Request Body
contactsarrayrequiredArray of contact objects (max 100)
Responses
{
"message": "Bulk contact creation completed",
"summary": {
"requested": 2,
"created": 2,
"errors": 0
}
}API Tester
Notes Management
/api/v1/contacts/:contactId/notesGet all notes for a specific contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Responses
{
"data": [
{
"id": "note-id-1",
"note": "Discussed pricing options",
"type": "INFO",
"createdAt": "2024-01-01T00:00:00.000Z",
"creator": {
"id": "user-id",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
},
{
"id": "note-id-2",
"note": "Follow up needed",
"type": "WARNING",
"createdAt": "2024-01-02T00:00:00.000Z",
"creator": {
"id": "user-id",
"firstName": "Jane",
"lastName": "Smith",
"email": "[email protected]"
}
}
]
}API Tester
/api/v1/contacts/:contactId/notesCreate a new note for a contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Request Body
notestringrequiredThe content of the note
typestring(default: GENERAL)Note type: GENERAL, INFO, WARNING, or DANGER
Responses
{
"data": {
"id": "new-note-id",
"note": "Customer interested in enterprise plan",
"type": "INFO",
"createdAt": "2024-01-01T00:00:00.000Z",
"creator": {
"id": "user-id",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
},
"message": "Note created successfully"
}API Tester
Assignments Management
/api/v1/contacts/:contactId/assignmentsGet all team member assignments for a contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Responses
{
"data": [
{
"id": "assignment-id-1",
"contactId": "contact-id",
"userId": "user-id-1",
"assignedAt": "2024-01-01T00:00:00.000Z",
"user": {
"id": "user-id-1",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"picture": null
}
},
{
"id": "assignment-id-2",
"contactId": "contact-id",
"userId": "user-id-2",
"assignedAt": "2024-01-01T00:00:00.000Z",
"user": {
"id": "user-id-2",
"firstName": "Jane",
"lastName": "Smith",
"email": "[email protected]",
"picture": "https://example.com/avatar.jpg"
}
}
]
}API Tester
/api/v1/contacts/:contactId/assignmentsAdd team members to a contact (keeps existing assignments)
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Request Body
userIdsarrayrequiredArray of user IDs to assign to the contact
Responses
{
"data": [
{
"id": "assignment-id",
"contactId": "contact-id",
"userId": "user-id",
"assignedAt": "2024-01-01T00:00:00.000Z",
"user": {
"id": "user-id",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
}
],
"message": "Added 1 assignment(s)"
}{
"error": "Some users are not members of this team"
}API Tester
/api/v1/contacts/:contactId/assignmentsReplace all team member assignments for a contact
Path Parameters
contactIdstringrequiredThe unique identifier of the contact
Request Body
userIdsarrayrequiredArray of user IDs to assign (replaces all existing assignments)
Responses
{
"data": [
{
"id": "assignment-id",
"contactId": "contact-id",
"userId": "user-id",
"assignedAt": "2024-01-01T00:00:00.000Z",
"user": {
"id": "user-id",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
}
],
"message": "Assignments updated successfully"
}API Tester
Tags Management
/api/v1/tagsGet all tags for your team
Responses
{
"data": [
{
"id": "tag-id-1",
"name": "VIP",
"color": "#10B981",
"contactCount": 25,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
},
{
"id": "tag-id-2",
"name": "Lead",
"color": "#3B82F6",
"contactCount": 150,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
]
}API Tester
/api/v1/tagsCreate a new tag
Request Body
namestringrequiredTag name (must be unique per team)
colorstring(default: #3B82F6)Hex color code (e.g., #3B82F6)
Responses
{
"data": {
"id": "new-tag-id",
"name": "Premium",
"color": "#10B981",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
},
"message": "Tag created successfully"
}{
"error": "A tag with this name already exists"
}API Tester
/api/v1/contacts/custom-fieldsGet the custom field schemas configured for contacts
Responses
{
"data": [
{
"id": "field-id",
"name": "company",
"label": "Company",
"type": "text",
"required": false,
"placeholder": "Enter company name",
"helpText": "The company the contact works for",
"order": 1
},
{
"id": "field-id-2",
"name": "role",
"label": "Role",
"type": "select",
"required": true,
"options": [
"Manager",
"Employee",
"Executive"
],
"order": 2
}
]
}API Tester
Board Operations
/api/v1/contacts/:contactId/boardsList all boards a contact is assigned to
Responses
{
"data": [
{
"id": "board-id-123",
"name": "Sales Pipeline",
"description": "Main sales tracking board",
"customFieldSchema": {
"id": "schema-id-123",
"name": "sales_fields",
"label": "Sales Fields",
"type": "object"
},
"contactCount": 45,
"createdAt": "2024-01-15T10:30:00Z"
}
]
}API Tester
/api/v1/contacts/:contactId/boardsAssign a contact to one or more boards
Request Body
boardIdsarrayrequiredArray of board IDs to assign the contact to
Responses
{
"data": {
"message": "Contact assigned to 2 boards successfully",
"boards": [
{
"id": "board-id-123",
"name": "Sales Pipeline"
},
{
"id": "board-id-456",
"name": "Support Queue"
}
]
}
}API Tester
/api/v1/contacts/:contactId/boardsUpdate a contact's board assignments (replaces existing assignments)
Request Body
boardIdsarrayrequiredArray of board IDs to assign (replaces all existing assignments)
Responses
{
"data": {
"message": "Contact board assignments updated successfully",
"removedFrom": 2,
"addedTo": 1,
"boards": [
{
"id": "board-id-789",
"name": "Customer Success"
}
]
}
}API Tester
/api/v1/contacts/:contactId/boardsRemove a contact from all boards
Responses
{
"data": {
"message": "Contact removed from all boards successfully",
"removedFrom": 3
}
}API Tester
Board Management
/api/v1/boardsList all available boards for your team
Responses
{
"data": [
{
"id": "board-id-123",
"name": "Sales Pipeline",
"description": "Main sales tracking board",
"customFieldSchema": {
"id": "schema-id-123",
"name": "sales_fields",
"label": "Sales Fields",
"type": "object",
"options": {
"fields": [
{
"name": "deal_value",
"type": "number",
"label": "Deal Value"
},
{
"name": "stage",
"type": "select",
"label": "Sales Stage",
"options": [
"Lead",
"Qualified",
"Proposal",
"Closed"
]
}
]
}
},
"contactCount": 45,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:20:00Z"
},
{
"id": "board-id-456",
"name": "Support Queue",
"description": "Customer support tracking",
"customFieldSchema": {
"id": "schema-id-456",
"name": "support_fields",
"label": "Support Fields",
"type": "object"
},
"contactCount": 23,
"createdAt": "2024-01-10T09:00:00Z"
}
]
}