Common Topics

Response Status Codes

All API endpoints return standard HTTP status codes:

Code	Description	Common Causes
200	Success	Request completed successfully
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters, malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Resource not found or doesn't belong to your organization
409	Conflict	Resource already exists
500	Internal Server Error	Server error, please retry
503	Service Unavailable	Service temporarily unavailable

Error Response Format

Error responses typically include:

{
  "statusCode": 400,
  "message": "Error message",
  "error": "Bad Request"
}

Or for validation errors:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    // Detailed validation errors
  ]
}

Pagination

Endpoints that return lists support pagination:

Query Parameters

Parameter	Type	Default	Description
size	integer	100	Number of items per page (max varies by endpoint)
start	integer	1	Starting index (1-based)

Pagination Response

{
  "data": [...],
  "pagination": {
    "start": 1,
    "requested_size": 100,
    "returned_count": 50,
    "total": 150,
    "hasMore": true
  }
}

UUID Format

All IDs in the API use UUID v4 format:

• Example: 22222222-2222-2222-2222-222222222222
• Pattern: [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}

Timestamps

API responses return timestamps in ISO 8601 format with UTC timezone:

• Response format: YYYY-MM-DDTHH:mm:ss.sssZ
• Response example: 2024-01-15T10:00:00.000Z

API requests accept ISO 8601 timestamps with any timezone offset:

• Accepted formats: YYYY-MM-DDTHH:mm:ss.sssZ, YYYY-MM-DDTHH:mm:ss.sss+HH:MM, YYYY-MM-DDTHH:mm:ss.sss-HH:MM
• Request examples: 2024-01-15T10:00:00.000Z, 2024-01-15T10:00:00.000+00:00, 2024-01-15T10:00:00.000-05:00

Phone Number Format

Phone numbers should be provided in E.164 format:

• Format: +[country code][subscriber number]
• Example: +14155552671 (US number)
• Example: +442071838750 (UK number)

Extended Fields

Patient and call resources support an extended field for storing custom data:

• Must be a valid JSON object
• Preserved across updates unless explicitly modified
• Useful for storing integration-specific data

Example:

{
  "extended": {
    "appointment": {
      "name": "General Check Up",
      "start_time": "August 22, 2025 at 10:30 AM",
      "end_time": "August 22, 2025 at 12:30 PM"
    },
    "customField": "value"
  }
}

Async Operations

Some operations are processed asynchronously. Periodically check to be updated on the statuses

Best Practices

Security

1. Never expose API keys in client-side code
2. Use environment variables for API keys
3. Rotate API keys regularly
4. Use HTTPS for all webhook endpoints
5. Validate all input data before processing

Performance

1. Use pagination for large datasets
2. Implement exponential backoff for retries
3. Cache responses where appropriate
4. Batch operations when possible

Error Handling

1. Always check response status codes
2. Log error responses for debugging
3. Implement proper retry logic for 5xx errors

Monitoring

1. Track API usage and performance
2. Monitor webhook delivery success
3. Set up alerts for repeated failures
4. Log all API interactions for audit

Support

For API support:

1. Check the error message and status code
2. Verify your API key is valid and has proper permissions
3. Ensure request format matches documentation