Skip to main content

POST /users

Create a user

Scopeusers:write
Role permissionUsers — the role must be allowed to manage users
CostFree, 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​

FieldTypeRequiredDescription
usernamestringyesThe login the user signs in with. Must not be taken.
passwordstringyesThe user's sign-in password. Never returned.
firstNamestringyesThe user's first name.
lastNamestringyesThe user's last name.
roleintegernoThe admin-center role id. Defaults to 5, Limited User.
emailstringnoThe user's email address.
mobilestringnoThe personal/cell number on the user's profile.
titlestringnoJob title. Free text.
timeZonestringnoAn IANA zone, such as America/New_York.
extensionstringnoGives 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.
mailboxobjectnoCreates a voicemail box for the user.
mailbox.mailboxstringnoThe mailbox number.
mailbox.pinstringnoThe mailbox PIN.
mailbox.descriptionstringnoA label for the mailbox.
sendWelcomeEmailbooleannoEmail 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.

FieldTypeDescription
idintegerThe 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.
usernamestringThe login this person signs in with. Empty for a user created without portal access.
firstNamestringThe user's first name.
lastNamestringThe user's last name.
titlestringJob title as entered in the portal. Free text.
emailstringThe user's email address. May be blank.
mobilestringThe personal/cell number on the user's profile — not a number on the account. May be blank.
companystringThe 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.
timeZonestringThe user's IANA zone. Every timestamp on this surface is UTC; this is what turns one into the wall-clock time this person saw.
extensionstringThe 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.
extensionsstring[]The PBX extensions assigned to this user — what a colleague dials internally.
linesstring[]The SIP lines (devices/registrations) the user owns.
numbersstring[]The account DIDs owned by this user. A number with no owner appears on nobody.
voicemailsstring[]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​

StatusMeaning
400invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403Two 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).
500internal_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}'

Try it in the playground →