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. Used as a fallback destination when they're not connected via WebRTC. May be null.
Name
invitation_pending
Type
boolean
Description
true if the employee hasn't signed in yet (invitation was sent but not accepted).
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.

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": "[email protected]",
      "phone": "+14155551234",
      "invitation_pending": false,
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-05-10T08:30:00Z"
    },
    {
      "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21",
      "name": "Jamie Chen",
      "email": "[email protected]",
      "phone": null,
      "invitation_pending": true,
      "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
A phone number to reach this employee when they're not connected via WebRTC.

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":"[email protected]","phone":"+14155559876"}'

Response

{
  "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21",
  "name": "Jamie Chen",
  "email": "[email protected]",
  "phone": "+14155559876",
  "invitation_pending": true,
  "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": "[email protected]",
  "phone": "+14155551234",
  "invitation_pending": false,
  "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.

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": "[email protected]",
  "phone": "+14155551234",
  "invitation_pending": false,
  "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 main 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"