Contacts

Contacts are the core of Tether - they represent leads, customers, and prospects in your organization. On this page, we will dive into the different contact endpoints you can use to manage contacts programmatically. We will look at how to query, create, update, and delete contacts.

GET/api/contacts

List all contacts

This endpoint allows you to retrieve a paginated list of all contacts. Supports filtering by search, source, owner, status, and date range.

Optional query parameters

  • Name
    page
    Type
    integer
    Description

    Page number for pagination (default: 1).

  • Name
    size
    Type
    integer
    Description

    Number of contacts per page (default: 10).

  • Name
    search
    Type
    string
    Description

    Search by first name, last name, phone number, or email.

  • Name
    source
    Type
    string
    Description

    Filter by source (e.g., "facebook", "sms", "webchat").

  • Name
    ownerFilter
    Type
    string
    Description

    Filter by owner - "my" (default), "all", or specific user ID.

  • Name
    status
    Type
    string
    Description

    Filter by pipeline status.

  • Name
    dateRange
    Type
    string
    Description

    JSON string with date range filter.

Request

GET
/api/contacts
curl -G https://your-tether-instance.com/api/contacts \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d size=10 \
  -d search="John"

Response

{
  "data": [
    {
      "isBulkSms": false,
      "_id": "507f1f77bcf86cd799439011",
      "userId": "507f1f77bcf86cd799439013",
      "organizationId": "507f1f77bcf86cd799439012",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+1234567890",
      "status": "New Lead",
      "isUpdated": false,
      "email": "john.doe@example.com",
      "createdBy": {
        "_id": "507f1f77bcf86cd799439013",
        "fullName": "Super Admin"
      },
      "assignees": ["507f1f77bcf86cd799439013"],
      "channelTypes": ["sms"],
      "process": "Sales Agent",
      "isAutopilot": false,
      "source": "CSV Upload",
      "files": [],
      "lastMessageTime": "2025-01-15T10:30:00.000Z",
      "__v": 0,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "latestMessage": "507f1f77bcf86cd799439014"
    },
    {
      "isBulkSms": false,
      "_id": "507f1f77bcf86cd799439015",
      "userId": "507f1f77bcf86cd799439013",
      "organizationId": "507f1f77bcf86cd799439012",
      "firstName": "Jane",
      "lastName": "Smith",
      "phoneNumber": "+1987654321",
      "status": "New Lead",
      "isUpdated": false,
      "email": "jane.smith@example.com",
      "createdBy": {
        "_id": "507f1f77bcf86cd799439013",
        "fullName": "Super Admin"
      },
      "assignees": ["507f1f77bcf86cd799439013"],
      "channelTypes": ["sms"],
      "process": "Sales Agent",
      "isAutopilot": false,
      "source": "CSV Upload",
      "files": [],
      "lastMessageTime": "2025-01-15T10:25:00.000Z",
      "__v": 0,
      "createdAt": "2025-01-15T10:25:00.000Z",
      "updatedAt": "2025-01-15T10:25:00.000Z",
      "latestMessage": "507f1f77bcf86cd799439016"
    }
    // ... 8 more entries
  ],
  "total": 150
}
POST/api/contact

Create a contact

This endpoint allows you to create a new contact. You must provide at least a phone number and organization context.

Required attributes

  • Name
    phoneNumber
    Type
    string
    Description

    The phone number for the contact (with country code).

Optional attributes

  • Name
    firstName
    Type
    string
    Description

    The first name of the contact.

  • Name
    lastName
    Type
    string
    Description

    The last name of the contact.

  • Name
    email
    Type
    string
    Description

    The email address for the contact.

  • Name
    source
    Type
    string
    Description

    The source of the contact (e.g., "manual", "facebook", "sms").

  • Name
    customData
    Type
    object
    Description

    Custom fields and data for the contact.

Request

POST
/api/contact
curl https://your-tether-instance.com/api/contact \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1234567890",
    "email": "john.doe@example.com",
    "source": "manual"
  }'

Response

{
  "isBulkSms": false,
  "_id": "507f1f77bcf86cd799439011",
  "userId": "507f1f77bcf86cd799439013",
  "organizationId": "507f1f77bcf86cd799439012",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "status": "New Lead",
  "isUpdated": false,
  "email": "john.doe@example.com",
  "createdBy": {
    "_id": "507f1f77bcf86cd799439013",
    "fullName": "Super Admin"
  },
  "assignees": ["507f1f77bcf86cd799439013"],
  "channelTypes": ["sms"],
  "process": "Sales Agent",
  "isAutopilot": false,
  "source": "Manual",
  "files": [],
  "lastMessageTime": "2025-01-15T10:30:00.000Z",
  "__v": 0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "latestMessage": "507f1f77bcf86cd799439014"
}
GET/api/contacts/:id

Retrieve a contact

This endpoint allows you to retrieve a contact by providing their ID.

Request

GET
/api/contacts/:id
curl https://your-tether-instance.com/api/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer {token}"

Response

{
  "isBulkSms": false,
  "_id": "507f1f77bcf86cd799439011",
  "userId": "507f1f77bcf86cd799439013",
  "organizationId": "507f1f77bcf86cd799439012",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "status": "New Lead",
  "isUpdated": false,
  "email": "john.doe@example.com",
  "createdBy": {
    "_id": "507f1f77bcf86cd799439013",
    "fullName": "Super Admin"
  },
  "assignees": ["507f1f77bcf86cd799439013"],
  "channelTypes": ["facebook"],
  "process": "Sales Agent",
  "isAutopilot": false,
  "source": "Facebook",
  "files": [],
  "lastMessageTime": "2025-01-15T10:30:00.000Z",
  "__v": 0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "latestMessage": "507f1f77bcf86cd799439014"
}
PUT/api/contact

Update a contact

This endpoint allows you to update an existing contact. You can update any contact fields including custom data.

Optional attributes

  • Name
    contactId
    Type
    string
    Description

    The ID of the contact to update (required in body).

  • Name
    firstName
    Type
    string
    Description

    Updated first name.

  • Name
    lastName
    Type
    string
    Description

    Updated last name.

  • Name
    email
    Type
    string
    Description

    Updated email address.

  • Name
    status
    Type
    string
    Description

    Updated pipeline status.

  • Name
    customData
    Type
    object
    Description

    Updated custom fields.

Request

PUT
/api/contact
curl -X PUT https://your-tether-instance.com/api/contact \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "507f1f77bcf86cd799439011",
    "firstName": "Jane",
    "status": "qualified"
  }'

Response

{
  "isBulkSms": false,
  "_id": "507f1f77bcf86cd799439011",
  "userId": "507f1f77bcf86cd799439013",
  "organizationId": "507f1f77bcf86cd799439012",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "status": "Qualified",
  "isUpdated": true,
  "email": "john.doe@example.com",
  "createdBy": {
    "_id": "507f1f77bcf86cd799439013",
    "fullName": "Super Admin"
  },
  "assignees": ["507f1f77bcf86cd799439013"],
  "channelTypes": ["sms"],
  "process": "Sales Agent",
  "isAutopilot": false,
  "source": "Manual",
  "files": [],
  "lastMessageTime": "2025-01-15T10:30:00.000Z",
  "__v": 0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T11:00:00.000Z",
  "latestMessage": "507f1f77bcf86cd799439014"
}
DELETE/api/contacts/:id

Delete a contact

This endpoint allows you to delete a contact. Note: This will also delete all conversations and messages associated with the contact.

Request

DELETE
/api/contacts/:id
curl -X DELETE https://your-tether-instance.com/api/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Contact deleted successfully"
}
POST/api/contacts/phoneNumber

Get contact by phone number

This endpoint allows you to retrieve a contact by their phone number.

Required attributes

  • Name
    phoneNumber
    Type
    string
    Description

    The phone number to search for.

Request

POST
/api/contacts/phoneNumber
curl https://your-tether-instance.com/api/contacts/phoneNumber \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+1234567890"}'

Response

{
  "isBulkSms": false,
  "_id": "507f1f77bcf86cd799439011",
  "userId": "507f1f77bcf86cd799439013",
  "organizationId": "507f1f77bcf86cd799439012",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "status": "New Lead",
  "isUpdated": false,
  "email": "john.doe@example.com",
  "createdBy": {
    "_id": "507f1f77bcf86cd799439013",
    "fullName": "Super Admin"
  },
  "assignees": ["507f1f77bcf86cd799439013"],
  "channelTypes": ["sms"],
  "process": "Sales Agent",
  "isAutopilot": false,
  "source": "Manual",
  "files": [],
  "lastMessageTime": "2025-01-15T10:30:00.000Z",
  "__v": 0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "latestMessage": "507f1f77bcf86cd799439014"
}

Was this page helpful?