Skip to main content
POST
/
v1
/
sms
/
phone-numbers
/
{phone_number}
/
assign
Assign SMS Number
curl --request POST \
  --url https://api.example.com/v1/sms/phone-numbers/{phone_number}/assign \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "user_id": "<string>"
}
'
{
  "success": true,
  "phone_number": "<string>",
  "user_id": "<string>",
  "assigned_at": "<string>"
}
Multi-SMS Feature: This endpoint is only available for tenants with multiple SMS numbers per organization enabled. The standard configuration is one SMS number per organization.

​
Assign SMS Number to User

Assign an available SMS phone number to a specific user within the organization. Once assigned, the user’s campaigns will automatically use this number.
Admin Only: This endpoint requires admin permissions. Only organization admins can assign phone numbers.

​
Authentication

​
X-API-Key
string
required
Your API key
​
Authorization
string
required
Bearer token with admin role

​
Path Parameters

​
phone_number
string
required
The phone number to assign (E.164 format, URL encoded if needed)

​
Query Parameters

​
organization_id
string
Organization unique_id. Required when a user exists in multiple organizations to ensure correct permission scoping.

​
Request Body

​
user_id
string
required
The user’s unique_id to assign the number to

​
Response

​
success
boolean
Whether the assignment was successful
​
phone_number
string
The assigned phone number
​
user_id
string
The user who now owns the number
​
assigned_at
string
ISO timestamp of assignment

​
Example Request

curl -X POST "https://api.teli.ai/v1/sms/phone-numbers/+14155551234/assign" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xyz789"
  }'

​
Example Response

{
  "success": true,
  "phone_number": "+14155551234",
  "user_id": "user_xyz789",
  "assigned_at": "2024-01-15T10:30:00Z",
  "powered_by": "Teli"
}

​
Error Responses

​
403 Forbidden - Admin Required

{
  "success": false,
  "error": "Admin permission required",
  "detail": "This action requires admin privileges"
}

​
400 Bad Request

{
  "success": false,
  "error": "Phone number not found"
}

{
  "success": false,
  "error": "Phone number already assigned to a user"
}

{
  "success": false,
  "error": "User not found"
}

​
Notes

  • Only unassigned numbers can be assigned
  • To reassign, first unassign from current user
  • Assignment is immediate and affects all future campaigns

​
Unassign SMS Number

​
DELETE /v1/sms/phone-numbers//assign

Remove a user’s assignment from an SMS number, returning it to the organization’s available pool.
Admin Only: This endpoint requires admin permissions.

​
Example Request

curl -X DELETE "https://api.teli.ai/v1/sms/phone-numbers/+14155551234/assign" \
  -H "X-API-Key: your-api-key" \
  -H "Authorization: Bearer your-jwt-token"

​
Example Response

{
  "success": true,
  "phone_number": "+14155551234",
  "powered_by": "Teli"
}

​
Notes

  • Does not delete the phone number, only removes user assignment
  • Number becomes available for assignment to another user
  • Active campaigns using this number continue to work