TidySupport logo
TidySupport logo

  1. Home

    2. /

  2. Docs

    3. /

  3. API Reference

    4. /

  4. Contacts

Contacts API

Contacts represent the customers and end-users in your support inbox. Every conversation is associated with a contact. Use these endpoints to create contacts, look up customer details, and search across your workspace.

Authentication

All endpoints require a valid API key in the Authorization header. Contacts endpoints accept both user and api_user scopes.

Authorization: Bearer YOUR_API_KEY

All endpoints are workspace-scoped. Replace {workspaceId} with your workspace ID.

Endpoints

GET/v1/workspaces/{workspaceId}/support/inbox/customers

Lists all contacts (customers) in your support inbox with their latest conversation summary.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/customers?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "customers": {
    "items": [
      {
        "contact": {
          "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
          "email": "jane@example.com",
          "name": "Jane Doe",
          "avatarUrl": null,
          "lastMessageAt": "2025-03-12T14:30:00Z",
          "lastMessagePreview": "Hi, I need help with..."
        },
        "latestThread": {
          "id": "thd_xyz789",
          "status": "OPEN",
          "source": "EMAIL",
          "lastMessageAt": "2025-03-12T14:30:00Z",
          "lastMessagePreview": "Hi, I need help with...",
          "unreadCount": 2
        },
        "threadCount": 3
      }
    ],
    "hasMore": false
  }
}

GET/v1/workspaces/{workspaceId}/support/inbox/contacts/{contactId}

Retrieves the full details of a single contact.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/contacts/ctc_B7OSYsnTUVwBPOGrgYTjvSGS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "contact": {
    "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "avatarUrl": null,
    "phone": "+1-555-0123",
    "status": "ACTIVE",
    "source": "EMAIL",
    "lastMessageAt": "2025-03-12T14:30:00Z",
    "lastMessagePreview": "Hi, I need help with...",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

POST/v1/workspaces/{workspaceId}/support/inbox/contacts

Creates a new contact in your support inbox. If a contact with the same email already exists, the existing contact is returned.

Request

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone": "+1-555-0123"
  }'

Response

{
  "contact": {
    "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone": "+1-555-0123",
    "status": "ACTIVE",
    "source": "API",
    "createdAt": "2025-03-13T10:00:00Z"
  }
}

GET/v1/workspaces/{workspaceId}/support/inbox/search

Searches across contacts, conversations, and messages in your workspace. Returns matching results grouped by type.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/search?q=jane&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "results": {
    "contacts": [
      {
        "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
        "email": "jane@example.com",
        "name": "Jane Doe"
      }
    ],
    "conversations": [
      {
        "id": "thd_xyz789",
        "subject": "Billing question",
        "lastMessagePreview": "Hi Jane, regarding your invoice..."
      }
    ],
    "messages": []
  }
}

Contact Object

idstring
Unique identifier for the contact (prefixed with ctc_)
emailstring
Contact email address
namestring
Display name
avatarUrlstring | null
URL to the contact avatar image
phonestring | null
Phone number
statusstring
Contact status (ACTIVE, ARCHIVED)
sourcestring
How the contact was created (EMAIL, CHAT, API, FORM, IMPORT)
lastMessageAtstring | null
ISO 8601 timestamp of the most recent message
lastMessagePreviewstring | null
Preview of the most recent message
createdAtstring
ISO 8601 timestamp when the contact was created

Error Handling

400 - Bad Request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid email address format."
}

404 - Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Contact not found."
}

401 - Unauthorized

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key. Please double-check and try again."
}