POST /users
Create a user
| Scope | users:write |
| Role permission | Users — the role must be allowed to manage users |
| Cost | Free, unless you send extension — that adds a billable line |
Runs exactly what the admin center's Add User does: it creates the user on the phone system, optionally a voicemail box, an extension on a new line, and the user's portal access — and refuses exactly what the admin center refuses.
extension adds a billable line. A user created without one costs
nothing; a user created with one gets a new line on the account, and
Telebroad is notified so the line is added to billing, just as when
the line is added in the admin center.
role is an admin-center role id. Leave it out and the user gets
Limited User (5) — the least access, so a new user never starts
with more than you meant to give.
Unknown fields are rejected (400), so a misspelled field name never
silently does nothing. What a value may be — a free username, an
unused extension, a valid time zone — is the phone system's decision;
a value it refuses is a 400 that says why.
Returns 201 with the new user, in the same shape GET /users
lists it.
Deleting needs users:delete; users:write alone is not enough.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
username | string | yes | The login the user signs in with. Must not be taken. |
password | string | yes | The user's sign-in password. Never returned. |
firstName | string | yes | The user's first name. |
lastName | string | yes | The user's last name. |
role | integer | no | The admin-center role id. Defaults to 5, Limited User. |
email | string | no | The user's email address. |
mobile | string | no | The personal/cell number on the user's profile. |
title | string | no | Job title. Free text. |
timeZone | string | no | An IANA zone, such as America/New_York. |
extension | string | no | Gives the user this extension on a new line. A line is billable — Telebroad is notified so the line is added to billing. Leave it out to create a user with no line. Must not be in use. |
mailbox | object | no | Creates a voicemail box for the user. |
mailbox.mailbox | string | no | The mailbox number. |
mailbox.pin | string | no | The mailbox PIN. |
mailbox.description | string | no | A label for the mailbox. |
sendWelcomeEmail | boolean | no | Email the new user their sign-in details. |
{
"username": "dspencer",
"password": "a-long-unique-password",
"firstName": "Dana",
"lastName": "Spencer",
"email": "dana@acme.example",
"title": "Support Lead",
"timeZone": "America/New_York",
"extension": "204",
"mailbox": {
"mailbox": "204",
"pin": "8264",
"description": "Dana Spencer"
},
"sendWelcomeEmail": true
}
Responses
201
Created. The new user, as GET /users lists it.
| Field | Type | Description |
|---|---|---|
id | integer | The user's id on the phone system. This is the value every other endpoint means by a user id — the entries in SMSLine.userIds are these ids. |
username | string | The login this person signs in with. Empty for a user created without portal access. |
firstName | string | The user's first name. |
lastName | string | The user's last name. |
title | string | Job title as entered in the portal. Free text. |
email | string | The user's email address. May be blank. |
mobile | string | The personal/cell number on the user's profile — not a number on the account. May be blank. |
company | string | The per-user company override, falling back to the account's own name — so it is always populated and always a name a caller would recognize. |
timeZone | string | The user's IANA zone. Every timestamp on this surface is UTC; this is what turns one into the wall-clock time this person saw. |
extension | string | The dial-by-name extension — the digits the auto-attendant matches for this person. Not necessarily a phone extension they can be reached on; see extensions. |
extensions | string[] | The PBX extensions assigned to this user — what a colleague dials internally. |
lines | string[] | The SIP lines (devices/registrations) the user owns. |
numbers | string[] | The account DIDs owned by this user. A number with no owner appears on nobody. |
voicemails | string[] | The mailbox names the user owns. |
{
"data": {
"id": 481920,
"username": "dspencer",
"firstName": "Dana",
"lastName": "Spencer",
"title": "Support Lead",
"email": "dana@acme.example",
"mobile": "",
"company": "Acme Inc",
"timeZone": "America/New_York",
"extension": "204",
"extensions": [
"204"
],
"lines": [
"acme-204"
],
"numbers": [],
"voicemails": [
"204"
]
}
}
Errors
| Status | Meaning |
|---|---|
400 | invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged. |
401 | unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted. |
403 | Two different failures share this status; the type field tells them apart — insufficient_scope (the credential lacks the scope) or permission_denied (the scope is fine, but the user's role lacks the permission). |
500 | internal_error — something failed on our side, not with your request. Safe to retry. |
See Errors for the full catalog and what to do about each.
Example
curl -X POST 'https://api.account.telebroad.com/api/public/v1/users' \
-H "Authorization: Bearer $TB_KEY" \
-H 'Content-Type: application/json' \
-d '{"username":"dspencer","password":"a-long-unique-password","firstName":"Dana","lastName":"Spencer","email":"dana@acme.example","title":"Support Lead","timeZone":"America/New_York","extension":"204","mailbox":{"mailbox":"204","pin":"8264","description":"Dana Spencer"},"sendWelcomeEmail":true}'