API Documentation

Introduction

The Developer API allows you to programmatically access your companies, contacts, and conversations data. You can use this API to build custom integrations, automated workflows, or external applications that need to interact with your data.

All API requests must be authenticated using an API key. The API returns JSON responses and uses standard HTTP response codes to indicate success or failure.

Authentication

All API requests require authentication

To authenticate your API requests, include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Note: Keep your API keys secure and never commit them to version control. If an API key is compromised, delete it immediately and create a new one.

Base URL

All API endpoints are relative to:

https://your-domain.com/api/v1

Replace your-domain.com with your actual domain or Replit URL.

API Endpoints

GET /api/v1/companies

Returns all companies

Description

Retrieves a list of all companies in your account, including their details such as name, website, industry, deal value, and stage information.

Example Request

curl -X GET "https://your-domain.com/api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "website": "https://acme.com",
    "industry": "Technology",
    "dealValue": 50000,
    "stageId": "stage-123",
    "position": 0,
    "logoUrl": "https://example.com/logo.png",
    "notes": "Important client",
    "lastContact": "2024-01-15T10:30:00Z",
    "isCustomer": false,
    "createdBy": "user-456",
    "createdAt": "2024-01-01T08:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]

GET /api/v1/contacts

Returns all contacts, optionally filtered by company

Description

Retrieves a list of all contacts. You can optionally filter by company using the companyId query parameter.

Query Parameters

companyId (optional) Filter contacts by company ID

Example Request

# Get all contacts
curl -X GET "https://your-domain.com/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get contacts for a specific company
curl -X GET "https://your-domain.com/api/v1/contacts?companyId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "contact-123",
    "companyId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john@acme.com",
    "phone": "+1-555-0123",
    "title": "CEO",
    "role": "Decision Maker",
    "notes": "Primary contact",
    "isPrimary": true,
    "userId": "user-456",
    "createdAt": "2024-01-01T08:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]

GET /api/v1/conversations

Returns all chat conversations, optionally filtered by company

Description

Retrieves a list of all chat conversations from your helpdesk. You can optionally filter by company using the companyId query parameter.

Query Parameters

companyId (optional) Filter conversations by company ID

Example Request

# Get all conversations
curl -X GET "https://your-domain.com/api/v1/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get conversations for a specific company
curl -X GET "https://your-domain.com/api/v1/conversations?companyId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "conv-123",
    "companyId": "123e4567-e89b-12d3-a456-426614174000",
    "visitorName": "Jane Smith",
    "visitorEmail": "jane@example.com",
    "visitorIp": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "referrerUrl": "https://google.com",
    "pageUrl": "https://acme.com/pricing",
    "status": "open",
    "assignedToUserId": "user-456",
    "isRead": false,
    "trustUploads": false,
    "tags": ["support", "urgent"],
    "lastMessageAt": "2024-01-15T14:30:00Z",
    "createdAt": "2024-01-15T14:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  }
]

Error Responses

Standard HTTP error codes are used

The API uses standard HTTP response codes to indicate the success or failure of requests:

200

Success

Request completed successfully

401

Unauthorized

Invalid or missing API key

404

Not Found

The requested resource doesn't exist

500

Server Error

An error occurred on our end

Rate Limits

Currently, there are no strict rate limits on API requests. However, we recommend implementing reasonable rate limiting in your applications (e.g., no more than 100 requests per minute) to ensure optimal performance for all users.

Need Help?

If you have questions or need assistance with the API, please contact our support team or check our knowledge base for more information.

Visit Settings → Developer to manage your API keys.