Skip to main content
The ContactShip API connects your systems to the operations documented in this reference. Most endpoints use https://api.contactship.ai; any legacy endpoint with a different host states its full URL on the page.

​
Authenticate

Create an organization key in Organization → API Keys with a plan that includes API access and the required permissions. The key belongs to one organization. Send it in the x-api-key header and keep it in a server-side credential store. Start with a read-only balance request:
Do not put organization keys in website JavaScript or public repositories. Rotate a disclosed key and update its integrations.

​
Requests and responses

Use each endpoint’s method, path, and fields. JSON write requests need Content-Type: application/json. Path IDs identify different resources: an agent ID is not a voice ID, and a number ID is not a phone-number string. The public API normally wraps successful responses as statusCode and data; paginated responses also include pagination. Legacy integration endpoints can differ. Check the response description on the endpoint you use. Creation or update can have immediate effects. API voice-agent creation publishes version 1, and updating an agent publishes its result. Call and message requests can contact real people. Confirm destinations and payloads before running examples.

​
Handle failures

  • For validation errors, correct the fields rather than retrying unchanged.
  • For authentication failures, check the key, organization, and access.
  • For 429, honor Retry-After when present and reduce request frequency.
  • After a timeout on a write, inspect the resulting resource before repeating it to avoid duplicate calls, comments, or tasks.
A 401 response alone does not establish that a URL is a supported endpoint. Use the contracts in this reference. See Rate limits, Webhooks, and API keys. Contact support@contactship.ai with the method, endpoint, timestamp, and sanitized response when investigating an integration.

​
Plan your integration

Integration guide

Choose the API, webhook, or automation and find the records you need.

Guía de integración en español

Elegí cómo conectar tu sistema y dónde obtener cada dato.

HTTP tool execution

Inspect what your endpoint receives during a voice or text conversation.