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 full display name, e.g. Alex Wong.

  • Name
    departments
    Type
    array
    Description

    Department memberships, each containing a public id and name. Manage memberships through the Departments API. An employee can belong to several departments.

  • Name
    first_name
    Type
    string
    Description

    The employee's first name.

  • Name
    last_name
    Type
    string
    Description

    The employee's last name.

  • 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",
      "first_name": "Alex",
      "last_name": "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",
      "first_name": "Jamie",
      "last_name": "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

When the company's entitlements.add_employees is false, this endpoint returns HTTP 403 with {"error":"upgrade_required","feature":"add_employees"}. No employee or invitation is created. Upgrade to Pro before retrying. Existing employee updates remain available. Read the current entitlements from the company API.

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.

Provide email and either name or both first_name and last_name. When structured name fields are present, they take precedence over name.

Required attributes

  • Name
    name
    Type
    string
    Description

    The employee's full display name. Required unless both first_name and last_name are provided. Must contain at least two words. The final word is stored as the last name.

  • Name
    first_name
    Type
    string
    Description

    The employee's first name. If supplied, last_name must also be supplied, even when name is present.

  • Name
    last_name
    Type
    string
    Description

    The employee's last name. If supplied, first_name must also be supplied, even when name is present.

  • 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",
  "first_name": "Jamie",
  "last_name": "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",
  "first_name": "Alex",
  "last_name": "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.

Returns 409 Conflict if another request changes or deletes the employee while the update is in progress. Retrieve the employee again before retrying; a deleted employee returns 404.

Optional attributes

  • Name
    name
    Type
    string
    Description

    New full display name. Must contain at least two words. The final word is stored as the last name.

  • Name
    first_name
    Type
    string
    Description

    New first name. Takes precedence over name when either structured name field is present.

  • Name
    last_name
    Type
    string
    Description

    New last name. Takes precedence over name when either structured name field is present.

  • 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.",
  "first_name": "Alex",
  "last_name": "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

Marks the employee as deleted and erases their name, email, phone numbers, and authentication data. Deleted employees disappear from employee lists and cannot sign in. Their billable seat is removed through an asynchronous subscription update; the company's subscription stays active.

The employee record is retained so calls, transfers, messages, and other historical references remain intact. Historical employee references use the name Deleted employee. Devices are removed, sessions and OAuth credentials are revoked, and company API keys are retained without an employee owner.

Anonymization applies to the Phone.inc employee record. Existing contacts in external CRM, support, or marketing systems, including Zero, Plain, and Loops, are not erased by this endpoint.

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

Retrieving, updating, or deleting the employee again returns 404 Not Found. Their email address can be used for a new employee.

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 the last employee, an employee assigned as a call target on a business number, or the last kept member of a department. Reassign call targets and add another department member or delete the department first. Successful employee deletion removes their department memberships. These safeguards return 422 Unprocessable Entity.

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_business_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",
  "first_name": "Alex",
  "last_name": "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"
}