Users
The company's users — this is what turns a user id or an extension into a person.
Who is in the list
Whoever your credential is allowed to see in the portal. This endpoint honours the same Users permission the admin center does.
| Credential | Sees |
|---|---|
| API key | The whole account. A key is the account's own credential, so it is not narrowed to any one person's permissions. |
| OAuth token | Exactly the users the authorizing person sees on the portal's Users page. |
A delegated app cannot enumerate staff its own user cannot open. If your OAuth integration gets a shorter list than you expect, the authorizing user's role is restricted to specific users — widen it in the portal under Roles, or use an API key for account-wide reads.
A role that permits no users returns 200 with an empty array, not 403. You are
allowed to ask; there is just nobody to show you.
The account's internal service login (the pseudo-admin, username
[Account Name]) is excluded. It is not a person.
:::info Changed from the teleconsole endpoint
The legacy /people showed every colleague to every user, ignoring roles. This
endpoint follows the admin center instead, so there is one answer to "who may see
this user" across the portal, a delegated app and an API key.
:::
Two kinds of extension
Easy to conflate, and they are different:
| Field | What it is |
|---|---|
extension | The dial-by-name extension — the digits the auto-attendant matches for this person. Not necessarily a number they can be reached on. |
extensions | The PBX extensions assigned to them — what a colleague actually dials internally. |
Similarly, mobile is the personal/cell number on their profile, not a number
on the account. numbers holds the account DIDs they own.
What is not here
Personal contacts
This is the bigger change from the legacy endpoint.
The teleconsole /people returned two different things merged into one array:
- the company's users — colleagues, extensions, the corporate list; and
- the calling user's own address book — contacts that person had typed into their softphone, stored privately against their user id.
You told them apart by a contactType field. This endpoint returns only (1).
The reason is what your credential is. An API key authenticates an account,
not a person, so there is no "my contacts" for it to read — the personal half would
always come back empty, and you would have no way to tell "this user saved no
contacts" from "this credential can never see contacts". Merging two sets with
different owners, different lifetimes and different privacy weight behind one
type= parameter hides that distinction rather than expressing it.
If you were consuming the personal half, tell us — it would be published as its own resource, where the ownership rules can be stated honestly.
Photos
The portal stores an avatar path, not a URL, and a path is not useful to you. Ask if you need this exposed properly.
Presence and status
Whether someone is on a call is real-time state, not directory data. Use the call webhooks for that.
Limits
- No paging, no filtering, no search. The response is every user you can see. Accounts are typically tens to hundreds of users; if yours is large enough for this to hurt, tell us and paging gets added. See Pagination.
- No writes. Creating a user provisions extensions, voicemail and a switch
identity — a portal operation, not something a third-party integration should do
through a REST
POST. - Read live, no cache. A user added in the portal appears on the next call.
- Sorted by last name, then first name, then id — so diffing two responses is meaningful.