Departments
A department brings employees together in one shared FIFO call queue. Calls from any business number or call flow join the same queue. Employees can belong to several departments.
The department model
- Name
id- Type
- string
- Description
- Stable public UUID. Also identifies the department's queue.
- Name
name- Type
- string
- Description
- Required. Unique within the account, up to 100 characters.
- Name
description- Type
- string
- Description
- Required, up to 300 characters. Explains which calls belong in this department.
- Name
employee_ids- Type
- array
- Description
- Public employee UUIDs. At least one account employee is required when saving. Pending invitations may be members but cannot answer until available.
Queue priority starts when a caller enters the department, not when the original call starts. Repeated entry into the same department preserves the queue timestamp and deadline. Moving to a different department starts a new position there. Employee membership is refreshed while callers wait.
Each caller keeps the originating business number's waiting audio, maximum wait and no-answer destination. Calls can therefore share queue order while having different deadlines. A department selected as the no-answer destination uses the existing indefinite fallback-queue behavior. Unavailable employees do not prevent callers joining the queue.
For TransferConfig or WelcomeTransferConfig, use department_id instead of employee_ids in any of the three business-number routing slots. Send employee_ids: [] when replacing an employee destination. Send department_id: null when switching back to employees. Do not combine both destination types. Phone-menu options continue to select employees.
All endpoints require an API key or an authorized OAuth token and are scoped to its account. Unknown department IDs return 404. Invalid names, descriptions, empty membership or foreign employee IDs return 422. Failed updates preserve existing membership.
List departments
Returns all departments in name order, with public employee IDs.
Request
curl https://app.phone.inc/api/v1/departments -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{"departments":[{"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}]}
Create a department
Provide name, description and a non-empty employee_ids array. Returns the department with status 201.
Request
curl https://app.phone.inc/api/v1/departments -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}'
Response
{"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}
Retrieve a department
Returns the current department and membership. Use its public UUID, not an internal database ID.
Request
curl "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}
Update a department
Omitted fields are unchanged. Providing employee_ids replaces the entire membership, so read the current department first. Returns status 200.
Request
curl -X PATCH "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"description":"New orders and product advice"}'
Response
{"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"New orders and product advice","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}
Delete a department
Returns 204 with no body. Remove call-flow assignments first. Queue entries, including retained queue history, also prevent deletion. In-use departments return 422.
Request
curl -X DELETE "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY"