DevelopersAPI referencePhone
Phone ring groups API
REST endpoints for phone ring groups in SKUFlow: 4 operations with parameters, request and response fields, permissions and curl examples.
Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.
| Operation | Endpoint | Risk |
|---|---|---|
| List ring groups | GET /organizations/{organizationId}/phone/ring-groups | read |
| Create a ring group | POST /organizations/{organizationId}/phone/ring-groups | write |
| Change a ring group | PATCH /organizations/{organizationId}/phone/ring-groups/{ringGroupId} | write |
| Delete a ring group | DELETE /organizations/{organizationId}/phone/ring-groups/{ringGroupId} | sensitive |
List ring groups
GET /organizations/{organizationId}/phone/ring-groups
Who rings for a call: team members answering in the browser and / or forwarded mobile numbers, all at once, optionally for one business unit. Read-only.
| Permission | phone.read (Owner, Admin, Staff, Member) |
| Risk | read, OAuth scope skuflow.read. Read: reads only. |
| MCP tool | phoneRingGroups_list (toolset marketing) |
Example
curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/phone/ring-groups" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
items | array of object | |
items[].id | string | |
items[].name | string | |
items[].businessUnitId | string or null | |
items[].userIds | array of string | |
items[].forwardNumbers | array of string | |
items[].ringTimeoutSeconds | integer or null | |
items[].createdAt | string (date-time) | |
items[].updatedAt | string (date-time) |
Create a ring group
POST /organizations/{organizationId}/phone/ring-groups
A ring group of team members (members whose role answers calls) and / or forward numbers. The first one becomes the default for numbers without their own group. 409 on a duplicate name.
| Permission | phone.manage (Owner, Admin) |
| Risk | write, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it. |
| MCP tool | phoneRingGroups_create (toolset marketing) |
| Plan | Needs the Phone system add-on. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 80 characters. |
businessUnitId | string or null | No | |
userIds | array of string | No | Team members with phone access who answer in the browser. Up to 25 items. |
forwardNumbers | array of string | No | Up to 5 items. |
ringTimeoutSeconds | integer or null | No | 5–60. |
Example
curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/phone/ring-groups" \
-H "Authorization: Bearer $SKUFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Dana Whitfield"}'Response
201: the answer's fields
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
businessUnitId | string or null | |
userIds | array of string | |
forwardNumbers | array of string | |
ringTimeoutSeconds | integer or null | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Change a ring group
PATCH /organizations/{organizationId}/phone/ring-groups/{ringGroupId}
Change who rings, forward numbers, the unit or the timeout, from the next call.
| Permission | phone.manage (Owner, Admin) |
| Risk | write, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it. |
| MCP tool | phoneRingGroups_update (toolset marketing) |
| Plan | Needs the Phone system add-on. |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ringGroupId | path | string | Yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Up to 80 characters. |
businessUnitId | string or null | No | |
userIds | array of string | No | Team members with phone access who answer in the browser. Up to 25 items. |
forwardNumbers | array of string | No | Up to 5 items. |
ringTimeoutSeconds | integer or null | No | 5–60. |
Example
curl -X PATCH "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/phone/ring-groups/{ringGroupId}" \
-H "Authorization: Bearer $SKUFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Dana Whitfield","businessUnitId":"businessUnit_id","userIds":["user_id"]}'Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
businessUnitId | string or null | |
userIds | array of string | |
forwardNumbers | array of string | |
ringTimeoutSeconds | integer or null | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Delete a ring group
DELETE /organizations/{organizationId}/phone/ring-groups/{ringGroupId}
Destructive: numbers using it fall back to the default group (or voicemail). 409 while a menu still uses it.
| Permission | phone.manage (Owner, Admin) |
| Risk | sensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access. |
| MCP tool | phoneRingGroups_delete (toolset marketing) |
| Approval | Over MCP, this tool always waits for your approval in SKUFlow. See Approvals. |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ringGroupId | path | string | Yes |
Example
curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/phone/ring-groups/{ringGroupId}" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
ok | true |