Phone.inc

Employees

An employee is someone on your team who can answer calls, make outbound calls, and access the Phone.inc dashboard. Use the Employees API to add new team members, update their details, and remove people who've left.

The employee model

Each employee has a stable public id, a display name, contact details, and an invitation status that tells you whether they've accepted their account invitation.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the employee.

  • Name
    name
    Type
    string
    Description

    The employee's display name, e.g. Alex Wong.

  • Name
    email
    Type
    string
    Description

    The employee's email address. Must be unique across all Phone.inc accounts.

  • Name
    phone
    Type
    string
    Description

    The employee's phone number. May be null. Not used for inbound call routing.

  • Name
    invitation_pending
    Type
    boolean
    Description

    true if the employee hasn't signed in yet (invitation was sent but not accepted).

  • Name
    status
    Type
    string
    Description

    Live presence for this employee. One of on_call, do_not_disturb, ringing, available, logged_out, or unknown. Point-in-time snapshot — poll the endpoint to refresh. See status values below.

  • Name
    do_not_disturb
    Type
    boolean
    Description

    true when the employee has enabled do-not-disturb and will not be offered inbound calls.

  • Name
    do_not_disturb_activated_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when do-not-disturb was last enabled. null when do-not-disturb is off.

  • Name
    do_not_disturb_expires_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when do-not-disturb will turn off automatically. null when do-not-disturb is off or set indefinitely.

  • Name
    created_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when the employee was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when the employee was last modified.

Passwords and two-factor authentication settings are not exposed through this API and cannot be changed via API calls. Employees manage these through the dashboard.

Status values

status is derived from live signals (browser softphone, mobile app reachability, do-not-disturb, and in-progress calls). Precedence is on_call > do_not_disturb > ringing > available > logged_out.

  • Name
    on_call
    Description

    The employee is on an active call right now.

  • Name
    do_not_disturb
    Description

    The employee has enabled do-not-disturb and will not be offered inbound calls. If they enable it while on a call, status stays on_call until the call ends.

  • Name
    ringing
    Description

    An inbound call is currently ringing this employee. May not be reported on all accounts.

  • Name
    available
    Description

    The employee has a live browser softphone session or a reachable mobile app and can take calls.

  • Name
    logged_out
    Description

    No live browser session and no reachable mobile app — or the invitation is still pending.

  • Name
    unknown
    Description

    Status could not be determined. Treat as a defensive fallback.

GET/v1/employees

List all employees

Returns every employee on the authenticated company. The response is a single array — there's no pagination.

Request

GET
/v1/employees
curl https://app.phone.inc/api/v1/employees \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "employees": [
    {
      "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
      "name": "Alex Wong",
      "email": "alex@example.com",
      "phone": "+14155551234",
      "invitation_pending": false,
      "status": "available",
      "do_not_disturb": false,
      "do_not_disturb_activated_at": null,
      "do_not_disturb_expires_at": null,
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-05-10T08:30:00Z"
    },
    {
      "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21",
      "name": "Jamie Chen",
      "email": "jamie@example.com",
      "phone": null,
      "invitation_pending": true,
      "status": "logged_out",
      "do_not_disturb": false,
      "do_not_disturb_activated_at": null,
      "do_not_disturb_expires_at": null,
      "created_at": "2026-05-14T16:00:00Z",
      "updated_at": "2026-05-14T16:00:00Z"
    }
  ]
}
POST/v1/employees

Create an employee

Creates a new employee and sends them an invitation email. The employee will appear with invitation_pending: true until they accept the invitation and sign in for the first time.

A random password is generated server-side — the employee sets their own password through the invitation flow.

Required attributes

  • Name
    name
    Type
    string
    Description

    The employee's display name.

  • Name
    email
    Type
    string
    Description

    The employee's email address. Must be unique.

Optional attributes

  • Name
    phone
    Type
    string
    Description

    The employee's phone number. Not used for inbound call routing.

Request

POST
/v1/employees
curl -X POST https://app.phone.inc/api/v1/employees \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jamie Chen","email":"jamie@example.com","phone":"+14155559876"}'

Response

{
  "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21",
  "name": "Jamie Chen",
  "email": "jamie@example.com",
  "phone": "+14155559876",
  "invitation_pending": true,
  "status": "logged_out",
  "do_not_disturb": false,
  "do_not_disturb_activated_at": null,
  "do_not_disturb_expires_at": null,
  "created_at": "2026-05-15T16:00:00Z",
  "updated_at": "2026-05-15T16:00:00Z"
}
GET/v1/employees/:id

Retrieve an employee

Returns a single employee by their public id. Returns 404 if the employee doesn't exist on this company's account.

Request

GET
/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20
curl https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
  "name": "Alex Wong",
  "email": "alex@example.com",
  "phone": "+14155551234",
  "invitation_pending": false,
  "status": "available",
  "do_not_disturb": false,
  "do_not_disturb_activated_at": null,
  "do_not_disturb_expires_at": null,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-05-10T08:30:00Z"
}
PATCH/v1/employees/:id

Update an employee

Updates an employee's profile fields. Pass only the fields you want to change. Passwords and two-factor authentication settings cannot be changed through this endpoint.

Optional attributes

  • Name
    name
    Type
    string
    Description

    New display name.

  • Name
    email
    Type
    string
    Description

    New email address. Must be unique.

  • Name
    phone
    Type
    string
    Description

    New phone number, or null to clear it. Not used for inbound call routing.

Request

PATCH
/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20
curl -X PATCH https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20 \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex W."}'

Response

{
  "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
  "name": "Alex W.",
  "email": "alex@example.com",
  "phone": "+14155551234",
  "invitation_pending": false,
  "status": "available",
  "do_not_disturb": false,
  "do_not_disturb_activated_at": null,
  "do_not_disturb_expires_at": null,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-05-15T16:10:00Z"
}
DELETE/v1/employees/:id

Delete an employee

Permanently deletes an employee. Their devices and API keys are cleaned up automatically.

Returns an empty response with a 204 status code on success.

You cannot delete the employee who created the API key you're authenticating with. The API returns 403 Forbidden if you try. You also can't delete an employee who is assigned as a call target on a business number — remove them from those first.

Request

DELETE
/v1/employees/0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21
curl -X DELETE https://app.phone.inc/api/v1/employees/0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"
GET/v1/employees/:id/do_not_disturb

Get do not disturb

Returns whether do-not-disturb is enabled for the employee, when it was activated, when it expires (if timed), and which business numbers would go straight to no answer if they enable it (because no other assigned employee is currently available, ringing, or on a call). Returns 404 if the employee doesn't exist on this company's account.

Use this before enabling do-not-disturb if you want to warn about coverage gaps — the same check the dashboard uses. Success responses use 200.

Request

GET
/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb
curl https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "enabled": false,
  "activated_at": null,
  "expires_at": null,
  "at_risk_main_numbers": [
    { "id": "0193f4b0-cccc-7c00-9e3d-2b2b8a7f1c22", "name": "Support" }
  ]
}
PUT/v1/employees/:id/do_not_disturb

Set do not disturb

Enables or disables do-not-disturb for an employee. While enabled, they are not offered inbound calls on any business number. Assignment on transfer configs is left alone — turning do-not-disturb off restores them automatically. Returns 404 if the employee doesn't exist on this company's account.

Enabling cancels any in-flight ring offers for that employee so their devices stop ringing immediately. Success responses use 200 and return the updated employee.

Pass an optional expires_at when enabling to turn do-not-disturb off automatically at that time. Omit it (or send null) for indefinite do-not-disturb. expires_at is ignored when enabled is false.

Required attributes

  • Name
    enabled
    Type
    boolean
    Description

    true to enable do-not-disturb, false to disable it.

Optional attributes

  • Name
    expires_at
    Type
    timestamp
    Description

    ISO 8601 timestamp in the future when do-not-disturb should turn off. Omit or null for indefinite. Must be in the future when provided; past values return 422.

Request

PUT
/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb
curl -X PUT https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"enabled\": true, \"expires_at\": \"$(date -u -v+1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)\"}"

Response

{
  "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
  "name": "Alex Wong",
  "email": "alex@example.com",
  "phone": "+14155551234",
  "invitation_pending": false,
  "status": "do_not_disturb",
  "do_not_disturb": true,
  "do_not_disturb_activated_at": "2026-08-31T16:10:00Z",
  "do_not_disturb_expires_at": "2026-08-31T17:10:00Z",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-08-31T16:10:00Z"
}