iTrade Internet API — Guide v1.2.0

Authentication

Every versioned endpoint requires your iTrade API key in the X-API-Key header. Keys are issued by iTrade and are specific to your application. Send them from your server; do not embed them in a browser or mobile client.

curl -sS https://api.itradeinternet.com/voice/v1/departments \
  -H "X-API-Key: <your_itrade_api_key>"

A missing or unrecognised key returns 401 with code UNAUTHORIZED.

Response format

Every JSON response uses one envelope.

Success

{
  "status": "ok",
  "request_id": "9f1c2b7a4d0e5f31",
  "message": "Request completed successfully.",
  "data": { }
}

Failure

{
  "status": "error",
  "request_id": "9f1c2b7a4d0e5f31",
  "error": "The request contains invalid data.",
  "code": "VALIDATION_ERROR",
  "details": { "contact_number": "A valid contact number is required." }
}

details appears only when field-level feedback is available. request_id identifies the request in iTrade's logs — quote it when contacting support.

Error codes

Code	HTTP	Meaning
BAD_REQUEST	400	The request could not be parsed or is malformed.
UNAUTHORIZED	401	Missing or invalid API key.
FORBIDDEN	403	The operation is not permitted for your account.
NOT_FOUND	404	No such route or resource.
METHOD_NOT_ALLOWED	405	The path exists but not for this method.
CONFLICT	409	Conflicts with current state, or an idempotent request is still running.
PAYLOAD_TOO_LARGE	413	Request body exceeds 10 MB.
VALIDATION_ERROR	422	Input failed validation; see details.
RATE_LIMITED	429	Too many requests; see Retry-After.
CAPABILITY_UNAVAILABLE	501	The capability is not enabled for your account.
NOT_IMPLEMENTED	501	The operation is not offered.
SERVICE_UNAVAILABLE	503	Temporarily unavailable; retry later.
UPSTREAM_TIMEOUT	504	The request timed out; retry.
GATEWAY_ERROR	502	The request could not be completed.

Idempotency

Endpoints that create billable or duplicable actions accept an optional X-Idempotency-Key header (8–128 characters, A–Z a–z 0–9 . _ -). Repeating a request with the same key and body replays the original response instead of performing the action again. A repeat sent while the first is still in flight returns 409 CONFLICT. Endpoints published before v1.2.0 are unaffected: without the header, behaviour is exactly as before.

Rate limiting

Limits are applied per API key. When a limit is exceeded the API returns 429 with code RATE_LIMITED and a Retry-After header giving the number of seconds to wait. Build retries with backoff and honour Retry-After.

Pagination

List endpoints that support paging accept limit and page, or limit and last_seen_id for cursor-style paging, depending on the resource. Supported parameters are listed against each endpoint below and in /openapi.json.

Call recordings

Call detail records may include a recording_url. These are iTrade URLs of the form /voice/v1/recordings/{ref}. Fetch them with your API key like any other endpoint. References are opaque and expire, so resolve them when you need the audio rather than storing them long-term.

Endpoints

Auto-Attendant Broadcast Contacts DND Departments Dialer IVR Interactions Hub Lead Lists Leads Numbers Schedule Calls Time Groups Users Voice

Auto-Attendant

Method	Path	Purpose	Notes
GET	/voice/v1/auto-attendants	List auto attendants
POST	/voice/v1/auto-attendants	Create a auto attendant
DELETE	/voice/v1/auto-attendants/{id}	Delete a auto attendant
GET	/voice/v1/auto-attendants/{id}	Fetch a auto attendant
PUT	/voice/v1/auto-attendants/{id}	Update a auto attendant

Broadcast

Method	Path	Purpose	Notes
POST	/voice/v1/broadcasts	Create a broadcast	accepts X-Idempotency-Key
GET	/voice/v1/broadcasts/batch-status/{id}	Fetch batch status for broadcasts
DELETE	/voice/v1/broadcasts/{id}	Delete a broadcast
GET	/voice/v1/broadcasts/{id}	Fetch a broadcast
PUT	/voice/v1/broadcasts/{id}	Update a broadcast
POST	/voice/v1/broadcasts/{id}:end	End broadcasts
POST	/voice/v1/broadcasts/{id}:pause	Pause broadcasts
POST	/voice/v1/broadcasts/{id}:resume	Resume broadcasts
POST	/voice/v1/broadcasts/{id}:start	Start broadcasts	accepts X-Idempotency-Key; billable; query: start_date_time, end_date_time
GET	/voice/v2/broadcasts	List broadcasts	query: limit, broadcast_id, page

Contacts

Method	Path	Purpose	Notes
GET	/voice/v1/contact-groups	List contact groups	query: contact_group_id, updated_after, limit, page
POST	/voice/v1/contact-groups	Create a contact group
DELETE	/voice/v1/contact-groups/{id}	Delete a contact group
PUT	/voice/v1/contact-groups/{id}	Update a contact group
GET	/voice/v1/contacts	List contacts	query: contact_id, contact_group_id, updated_after, limit, page
DELETE	/voice/v1/contacts/{id}	Delete a contact
POST	/voice/v1/contacts/{id}	Create a contact
PUT	/voice/v1/contacts/{id}	Update a contact
POST	/voice/v1/contacts/{id}:bulk	Bulk create contacts	accepts X-Idempotency-Key

DND

Method	Path	Purpose	Notes
GET	/voice/v1/dnd-leads	List DND leads	query: limit, last_seen_id, list_id, id
POST	/voice/v1/dnd-leads	Create a DND lead
DELETE	/voice/v1/dnd-leads/{id}	Delete a DND lead
PUT	/voice/v1/dnd-leads/{id}	Update a DND lead
GET	/voice/v1/dnd-lists	List DND lists	query: limit, sort_dir, cursor, name, updated_after
POST	/voice/v1/dnd-lists	Create a DND list
DELETE	/voice/v1/dnd-lists/{id}	Delete a DND list
PUT	/voice/v1/dnd-lists/{id}	Update a DND list
DELETE	/voice/v1/dnd-lists/{id}/leads:bulk	Bulk delete DND leads
POST	/voice/v1/dnd-lists/{id}/leads:bulk	Bulk create DND leads	accepts X-Idempotency-Key

Departments

Method	Path	Purpose	Notes
GET	/voice/v1/departments	List departments	available since v1.1.0
POST	/voice/v1/departments	Create a department
DELETE	/voice/v1/departments/{id}	Delete a department
PUT	/voice/v1/departments/{id}	Update a department	available since v1.1.0

Dialer

Method	Path	Purpose	Notes
GET	/voice/v1/dialer/agent-scripts	List agent scripts
POST	/voice/v1/dialer/agent-scripts	Create a agent script
DELETE	/voice/v1/dialer/agent-scripts/{id}	Delete a agent script
GET	/voice/v1/dialer/agent-scripts/{id}	Fetch a agent script
PUT	/voice/v1/dialer/agent-scripts/{id}	Update a agent script
GET	/voice/v1/dialer/break-lists	List break lists
POST	/voice/v1/dialer/break-lists	Create a break list
DELETE	/voice/v1/dialer/break-lists/{id}	Delete a break list
PUT	/voice/v1/dialer/break-lists/{id}	Update a break list
POST	/voice/v1/dialer/breaks:end	End breaks
POST	/voice/v1/dialer/breaks:start	Start breaks
GET	/voice/v1/dialer/callbacks	List callbacks	query: from_date, to_date
POST	/voice/v1/dialer/callbacks	Create a callback	accepts X-Idempotency-Key
GET	/voice/v1/dialer/callbacks/{callback_id}	Fetch a callback
PUT	/voice/v1/dialer/callbacks/{callback_id}	Update a callback
POST	/voice/v1/dialer/calls:disconnect	Disconnect calls
GET	/voice/v1/dialer/campaigns	List campaigns
POST	/voice/v1/dialer/campaigns	Create a campaign
DELETE	/voice/v1/dialer/campaigns/{id}	Delete a campaign
GET	/voice/v1/dialer/campaigns/{id}	Fetch a campaign
PUT	/voice/v1/dialer/campaigns/{id}	Update a campaign
GET	/voice/v1/dialer/disposition-lists	List disposition lists
POST	/voice/v1/dialer/disposition-lists	Create a disposition list
DELETE	/voice/v1/dialer/disposition-lists/{id}	Delete a disposition list
PUT	/voice/v1/dialer/disposition-lists/{id}	Update a disposition list
POST	/voice/v1/dialer/disposition-statuses	Create a disposition statuse
DELETE	/voice/v1/dialer/disposition-statuses/{id}	Delete a disposition statuse
GET	/voice/v1/dialer/disposition-statuses/{id}	Fetch a disposition statuse
PUT	/voice/v1/dialer/disposition-statuses/{id}	Update a disposition statuse
POST	/voice/v1/dialer/disposition-statuses:bulk	Bulk create disposition statuses	accepts X-Idempotency-Key
POST	/voice/v1/dialer/dispositions:update-details	Update a disposition
GET	/voice/v1/dialer/inbound-queues	List inbound queues
POST	/voice/v1/dialer/inbound-queues	Create a inbound queue
DELETE	/voice/v1/dialer/inbound-queues/{id}	Delete a inbound queue
GET	/voice/v1/dialer/inbound-queues/{id}	Fetch a inbound queue
PUT	/voice/v1/dialer/inbound-queues/{id}	Update a inbound queue
POST	/voice/v1/dialer/pause-codes	Create a pause code
DELETE	/voice/v1/dialer/pause-codes/{id}	Delete a pause code
GET	/voice/v1/dialer/pause-codes/{id}	Fetch a pause code
PUT	/voice/v1/dialer/pause-codes/{id}	Update a pause code
GET	/voice/v1/dialer/quick-transfer-lists	List quick transfer lists
POST	/voice/v1/dialer/quick-transfer-lists	Create a quick transfer list
DELETE	/voice/v1/dialer/quick-transfer-lists/{id}	Delete a quick transfer list
PUT	/voice/v1/dialer/quick-transfer-lists/{id}	Update a quick transfer list
POST	/voice/v1/dialer/quick-transfer-numbers	Create a quick transfer number
DELETE	/voice/v1/dialer/quick-transfer-numbers/{id}	Delete a quick transfer number
GET	/voice/v1/dialer/quick-transfer-numbers/{id}	Fetch a quick transfer number
PUT	/voice/v1/dialer/quick-transfer-numbers/{id}	Update a quick transfer number
POST	/voice/v1/dialer/sessions:call	Call sessions	accepts X-Idempotency-Key; billable
POST	/voice/v1/dialer/sessions:logout	Logout sessions
GET	/voice/v1/dialer/skill-lists	List skill lists
GET	/voice/v1/dialer/skill-lists/{skill_list_id}/skills	List skills	query: limit

IVR

Method	Path	Purpose	Notes
GET	/voice/v1/ivrs	List IVRs
POST	/voice/v1/ivrs	Create a IVR
DELETE	/voice/v1/ivrs/{id}	Delete a IVR
PUT	/voice/v1/ivrs/{id}	Update a IVR

Interactions Hub

Method	Path	Purpose	Notes
POST	/voice/v1/interactions:click-to-interaction	Click interactions	accepts X-Idempotency-Key; billable

Lead Lists

Method	Path	Purpose	Notes
GET	/voice/v1/lead-lists	List lead lists
POST	/voice/v1/lead-lists	Create a lead list
DELETE	/voice/v1/lead-lists/{id}	Delete a lead list
PUT	/voice/v1/lead-lists/{id}	Update a lead list
PATCH	/voice/v1/lead-lists/{id}/leads	Patch the leads in lead lists

Leads

Method	Path	Purpose	Notes
GET	/voice/v1/lead-lists/{id}/leads	List leads	query: number
POST	/voice/v1/lead-lists/{id}/leads	Create a lead
DELETE	/voice/v1/lead-lists/{id}/leads:bulk	Bulk delete leads
POST	/voice/v1/lead-lists/{id}/leads:bulk	Bulk create leads	accepts X-Idempotency-Key
DELETE	/voice/v1/leads/{id}	Delete a lead
PUT	/voice/v1/leads/{id}	Update a lead

Numbers

Method	Path	Purpose	Notes
GET	/voice/v1/blocked-numbers	List blocked numbers
POST	/voice/v1/blocked-numbers	Create a blocked number
DELETE	/voice/v1/blocked-numbers/{id}	Delete a blocked number
PUT	/voice/v1/blocked-numbers/{id}	Update a blocked number
GET	/voice/v1/my-numbers	List DID numbers	available since v1.1.0
PUT	/voice/v1/my-numbers/{id}	Update a DID number	available since v1.1.0

Schedule Calls

Method	Path	Purpose	Notes
GET	/voice/v1/schedule-calls	List scheduled calls	query: limit, type, to_date, page, from_date
POST	/voice/v1/schedule-calls	Create a scheduled call	accepts X-Idempotency-Key
DELETE	/voice/v1/schedule-calls/{id}	Delete a scheduled call
PUT	/voice/v1/schedule-calls/{id}	Update a scheduled call

Time Groups

Method	Path	Purpose	Notes
GET	/voice/v1/time-groups	List time groups
POST	/voice/v1/time-groups	Create a time group
DELETE	/voice/v1/time-groups/{id}	Delete a time group

Users

Method	Path	Purpose	Notes
GET	/voice/v1/users	List users	available since v1.1.0
POST	/voice/v1/users	Create a user
DELETE	/voice/v1/users/{id}	Delete a user
GET	/voice/v1/users/{id}	Fetch a user
PATCH	/voice/v1/users/{id}	Update a user	available since v1.1.0

Voice

Method	Path	Purpose	Notes
GET	/voice/v1/call-notes/by-number/{client_number}	List call notes	query: limit, page
DELETE	/voice/v1/call-notes/{id}	Delete a call note
PUT	/voice/v1/call-notes/{id}	Update a call note
GET	/voice/v1/call-records	List call detail records	available since v1.1.0
POST	/voice/v1/calls/{id}/notes	Create a call note
POST	/voice/v1/calls:clicktocall	Start calls	available since v1.1.0; billable; alias: /voice/v1/calls:click_to_call
POST	/voice/v1/calls:clicktocallsupport	Clicktocallsupport calls	available since v1.1.0; billable; alias: /voice/v1/calls:click_to_call_support
POST	/voice/v1/calls:hangup	Hang up calls	available since v1.1.0
POST	/voice/v1/calls:options	Apply options to calls	available since v1.1.0
GET	/voice/v1/live-calls	List active calls	available since v1.1.0
GET	/voice/v1/live-calls:search	Search active calls	query: agent_number, extension, did_number, call_id

Machine-readable specification: /openapi.json