Carrier API
This documentation is intended for carriers as defined in the carrier documentation. The API documentation for Somleng's Open Source implementation of Twilio's REST API is available here.
The Carrier API is intended for carriers who need to automate provisioning of carrier resources (e.g. Accounts) rather that using the dashboard. This API is written according to the JSON API Specification. We recommend using a JSON API Client for consuming this API.
Authentication
This API uses Bearer authentication. You must include your API key in the Authorization header for all requests. Your API key is available on the Carrier Dashboard.
Webhooks
Somleng uses webhooks to notify your application when an event happens in your account.
Somleng signs the webhook events it sends to your endpoint by including a signature in each event's Authorization header.
This allows you to verify that the events were sent by Somleng, not by a third party.
All requests are signed using JSON Web Token (JWT) Bearer authentication, according to the HS256 (HMAC-SHA256) algorithm.
You should verify the events that Somleng sends to your Webhook endpoints. On the right is an example in Ruby ---->
JWT.decode(
request.headers["Authorization"].sub("Bearer ", ""),
"[your-webhook-signing-secret]",
true,
algorithm: "HS256",
verify_iss: true,
iss: "Somleng"
)
Accounts
Create an account
Request
curl "https://api.somleng.org/carrier/v1/accounts" -d '{
"data": {
"type": "account",
"attributes": {
"name": "Rocket Rides",
"default_tts_voice": "Basic.Kal",
"billing_enabled": true,
"billing_mode": "prepaid",
"metadata": {
"foo": "bar"
}
}
}
}' -X POST \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer D1BbFYijds2ac-qy66IUfVNS3ZMH9iaWHhg-XXRG4dU"
Endpoint
POST https://api.somleng.org/carrier/v1/accounts
POST https://api.somleng.org/carrier/v1/accounts
Parameters
{
"data": {
"type": "account",
"attributes": {
"name": "Rocket Rides",
"default_tts_voice": "Basic.Kal",
"billing_enabled": true,
"billing_mode": "prepaid",
"metadata": {
"foo": "bar"
}
}
}
}
| Name | Description |
|---|---|
| data[attributes][name] required | A friendly name which identifies the account |
| data[attributes][billing_enabled] | Enable billing for the account. Defaults to false. |
| data[attributes][billing_mode] | The billing mode for the account. Only prepaid is supported at this time. |
| data[attributes][tts_voice] | The default TTS voice identifier. Defaults to: Basic.Kal |
| data[attributes][metadata] | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
Response
201 Created
{
"data": {
"id": "7fbf8092-6be1-4fc4-85e6-ac63a919d64b",
"type": "account",
"attributes": {
"created_at": "2026-07-25T09:07:15Z",
"updated_at": "2026-07-25T09:07:15Z",
"name": "Rocket Rides",
"metadata": {
"foo": "bar"
},
"status": "enabled",
"type": "carrier_managed",
"billing_enabled": true,
"billing_mode": "prepaid",
"auth_token": "5MR1bgOpHCp4xGr7WLdkhQAvnDdp8dFtKUYHO93Q2xw",
"default_tts_voice": "Basic.Kal"
}
}
}
Delete an account
Request
curl "https://api.somleng.org/carrier/v1/accounts/0e3f8f40-ee82-45e3-9819-54929a62ced5" -d '' -X DELETE \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer gG1lLN2WuTvKjDD3UYcAjNYYteMH1uzB8HzHLoxNcuI"
Endpoint
DELETE https://api.somleng.org/carrier/v1/accounts/:id
DELETE https://api.somleng.org/carrier/v1/accounts/0e3f8f40-ee82-45e3-9819-54929a62ced5
Parameters
None known.
Response
204 No Content
List all accounts
Request
curl "https://api.somleng.org/carrier/v1/accounts" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer P8s8Nr883QJc9uhKzelC_7-tYmcaGBq_bYZB-1b_t3I"
Endpoint
GET https://api.somleng.org/carrier/v1/accounts
GET https://api.somleng.org/carrier/v1/accounts
Parameters
None known.
Response
200 OK
{
"data": [
{
"id": "861d1663-efa7-42f4-bad7-e55ed97c4165",
"type": "account",
"attributes": {
"created_at": "2026-07-25T09:07:15Z",
"updated_at": "2026-07-25T09:07:15Z",
"name": "Telco Net",
"metadata": {},
"status": "enabled",
"type": "carrier_managed",
"billing_enabled": false,
"billing_mode": "prepaid",
"auth_token": "tG487MuW0yJvYnQm2_0St_ugeh0X0YqRpvnI0HhlrSo",
"default_tts_voice": "Basic.Kal"
}
},
{
"id": "10fad77e-c5db-498d-952d-83e6e30152f4",
"type": "account",
"attributes": {
"created_at": "2026-07-25T09:07:15Z",
"updated_at": "2026-07-25T09:07:15Z",
"name": "Rocket Rides",
"metadata": {},
"status": "enabled",
"type": "customer_managed",
"billing_enabled": false,
"billing_mode": "prepaid",
"default_tts_voice": "Basic.Kal"
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/accounts?page%5Bbefore%5D=861d1663-efa7-42f4-bad7-e55ed97c4165",
"next": null
}
}
Retrieve an account
Request
curl "https://api.somleng.org/carrier/v1/accounts/3ca59d1c-62a0-4162-8e4f-77db01dd78fa" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer MMEFqSXtjfivPlQXW5Aj2cZbu8Zykhe-QcDJGYeL810"
Endpoint
GET https://api.somleng.org/carrier/v1/accounts/:id
GET https://api.somleng.org/carrier/v1/accounts/3ca59d1c-62a0-4162-8e4f-77db01dd78fa
Parameters
| Name | Description |
|---|---|
| id required | The id of the account to be retrieved. |
Response
200 OK
{
"data": {
"id": "3ca59d1c-62a0-4162-8e4f-77db01dd78fa",
"type": "account",
"attributes": {
"created_at": "2026-07-25T09:07:15Z",
"updated_at": "2026-07-25T09:07:15Z",
"name": "Rocket Rides",
"metadata": {},
"status": "enabled",
"type": "carrier_managed",
"billing_enabled": false,
"billing_mode": "prepaid",
"auth_token": "MgRZRuQ-haVdwrm5kpg0pxqg64-ZXLiohHcN_57j0WE",
"default_tts_voice": "Basic.Kal"
}
}
}
Update an account
Request
curl "https://api.somleng.org/carrier/v1/accounts/6378abe1-0e2c-4dda-8503-be121406b3cc" -d '{
"data": {
"attributes": {
"status": null,
"name": "Bob Cats",
"status": "disabled",
"billing_enabled": false,
"default_tts_voice": "Basic.Kal",
"metadata": {
"bar": "foo"
}
},
"type": "account",
"id": "6378abe1-0e2c-4dda-8503-be121406b3cc"
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 0fyYq1lcBn5ArCbsJIz0G07-sy21uzfLHjGwwp7F3s4"
Endpoint
PATCH https://api.somleng.org/carrier/v1/accounts/:id
PATCH https://api.somleng.org/carrier/v1/accounts/6378abe1-0e2c-4dda-8503-be121406b3cc
Parameters
{
"data": {
"attributes": {
"status": null,
"name": "Bob Cats",
"status": "disabled",
"billing_enabled": false,
"default_tts_voice": "Basic.Kal",
"metadata": {
"bar": "foo"
}
},
"type": "account",
"id": "6378abe1-0e2c-4dda-8503-be121406b3cc"
}
}
| Name | Description |
|---|---|
| data[attributes][status] | Update the status of the account. One of either enabled or disabled. |
Response
200 OK
{
"data": {
"id": "6378abe1-0e2c-4dda-8503-be121406b3cc",
"type": "account",
"attributes": {
"created_at": "2026-07-25T09:07:15Z",
"updated_at": "2026-07-25T09:07:15Z",
"name": "Bob Cats",
"metadata": {
"foo": "bar",
"bar": "foo"
},
"status": "disabled",
"type": "carrier_managed",
"billing_enabled": false,
"billing_mode": "prepaid",
"auth_token": "8cHNRQDMDJzuTGadYEVoczfu77WfDVwlc2LIXVvbTD8",
"default_tts_voice": "Basic.Kal"
}
}
}
Events
List all events
Types of events
This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.
You'll notice that these events follow a pattern: resource.event.
Our goal is to design a consistent system that makes things easier to anticipate and code against.
| Event |
|---|
phone_call.completed |
message.sent |
message.delivered |
Request
curl "https://api.somleng.org/carrier/v1/events" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 48MxW5ho1-3SxGO6Z8K4spGNtwS1gx4u6CiufNiyD70"
Endpoint
GET https://api.somleng.org/carrier/v1/events
GET https://api.somleng.org/carrier/v1/events
Parameters
None known.
Response
200 OK
{
"data": [
{
"id": "71a25519-5411-4175-bfad-8bd0caf11172",
"type": "event",
"attributes": {
"created_at": "2026-07-25T09:06:38Z",
"updated_at": "2026-07-25T09:06:38Z",
"type": "phone_call.completed",
"details": {
"data": {
"id": "4d81a7e0-d152-469c-94fe-bd4b256c5ef8",
"type": "phone_call",
"attributes": {
"to": "+85512334667",
"from": "2442",
"price": null,
"status": "queued",
"duration": null,
"direction": "outbound-api",
"created_at": "2026-07-25T09:06:38Z",
"price_unit": null,
"updated_at": "2026-07-25T09:06:38Z"
},
"relationships": {
"account": {
"data": {
"id": "19ba2050-5158-4bfa-99ff-ea6f5f097f02",
"type": "account"
}
}
}
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/events?page%5Bbefore%5D=71a25519-5411-4175-bfad-8bd0caf11172",
"next": null
}
}
Retrieve an Event
Request
curl "https://api.somleng.org/carrier/v1/events/e23640e1-574e-4ef3-a63d-5a70261f434f" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer gKob-SMhFQjTaAQOJju6ZxAtPXEJt2q0M-FqZTs9TKs"
Endpoint
GET https://api.somleng.org/carrier/v1/events/:id
GET https://api.somleng.org/carrier/v1/events/e23640e1-574e-4ef3-a63d-5a70261f434f
Parameters
None known.
Response
200 OK
{
"data": {
"id": "e23640e1-574e-4ef3-a63d-5a70261f434f",
"type": "event",
"attributes": {
"created_at": "2026-07-25T09:06:38Z",
"updated_at": "2026-07-25T09:06:38Z",
"type": "phone_call.completed",
"details": {
"data": {
"id": "a7d0b48a-8afc-49fb-9ebf-e31e628ad89c",
"type": "phone_call",
"attributes": {
"to": "+85512334667",
"from": "2442",
"price": null,
"status": "queued",
"duration": null,
"direction": "outbound-api",
"created_at": "2026-07-25T09:06:38Z",
"price_unit": null,
"updated_at": "2026-07-25T09:06:38Z"
},
"relationships": {
"account": {
"data": {
"id": "f7fe5bd8-a3c9-4639-9c82-94d6c5bd642e",
"type": "account"
}
}
}
}
}
}
}
}
Messages
List messages
Request
curl "https://api.somleng.org/carrier/v1/messages?filter[status]=sent&filter[from_date]=2021-11-01T00%3A00%3A00Z&filter[to_date]=2021-11-01T00%3A00%3A00Z&filter[account]=8b1283ff-5ff7-4a92-b17a-f83d0a0d4cc1&filter[direction]=outbound-api" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer Vq0qcmfWxl-N8yb2D_GcktFKX9Ako9zBhRL23nwfHWw"
Endpoint
GET https://api.somleng.org/carrier/v1/messages
GET https://api.somleng.org/carrier/v1/messages?filter[status]=sent&filter[from_date]=2021-11-01T00%3A00%3A00Z&filter[to_date]=2021-11-01T00%3A00%3A00Z&filter[account]=8b1283ff-5ff7-4a92-b17a-f83d0a0d4cc1&filter[direction]=outbound-api
Parameters
{
"filter": {
"status": "sent",
"from_date": "2021-11-01T00:00:00Z",
"to_date": "2021-11-01T00:00:00Z",
"account": "8b1283ff-5ff7-4a92-b17a-f83d0a0d4cc1",
"direction": "outbound-api"
}
}
| Name | Description |
|---|---|
| filter[account] | Return messages from the provided account-sid |
| filter[from_date] | Return messages on or after the provided date/time in ISO 8601 format. |
| filter[to_date] | Return messages on or before the provided date/time in ISO 8601 format. |
| filter[direction] | One of inbound, outbound-api, outbound-call, outbound-reply, and outbound |
| filter[status] | One of accepted, scheduled, queued, sending, sent, failed, received, canceled, and delivered |
Response
200 OK
{
"data": [
{
"id": "057c7e24-a8d2-4cbb-a4a1-9e104eb78f08",
"type": "message",
"attributes": {
"created_at": "2021-11-01T01:00:00Z",
"updated_at": "2026-07-25T09:06:32Z",
"to": "+85512334667",
"from": "2442",
"price_unit": null,
"direction": "outbound-api",
"status": "sent",
"body": "Hello World",
"price": null
},
"relationships": {
"account": {
"data": {
"id": "8b1283ff-5ff7-4a92-b17a-f83d0a0d4cc1",
"type": "account"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/messages?filter%5Baccount%5D=8b1283ff-5ff7-4a92-b17a-f83d0a0d4cc1&filter%5Bdirection%5D=outbound-api&filter%5Bfrom_date%5D=2021-11-01T00%3A00%3A00Z&filter%5Bstatus%5D=sent&filter%5Bto_date%5D=2021-11-01T00%3A00%3A00Z&page%5Bbefore%5D=057c7e24-a8d2-4cbb-a4a1-9e104eb78f08",
"next": null
}
}
Retrieve a message
Request
curl "https://api.somleng.org/carrier/v1/messages/dac93572-454f-4c46-87ca-72ff5b4f8a02" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer wEYRVzggE_17KsQcYpbAaQvuY1tLCvpAku1k3dmhyAY"
Endpoint
GET https://api.somleng.org/carrier/v1/messages/:id
GET https://api.somleng.org/carrier/v1/messages/dac93572-454f-4c46-87ca-72ff5b4f8a02
Parameters
None known.
Response
200 OK
{
"data": {
"id": "dac93572-454f-4c46-87ca-72ff5b4f8a02",
"type": "message",
"attributes": {
"created_at": "2026-07-25T09:06:32Z",
"updated_at": "2026-07-25T09:06:32Z",
"to": "+85512334667",
"from": "2442",
"price_unit": null,
"direction": "outbound-api",
"status": "accepted",
"body": "Hello World",
"price": null
},
"relationships": {
"account": {
"data": {
"id": "99c664ac-b067-4cfd-9ebd-d2978710a51e",
"type": "account"
}
}
}
}
}
Update a message
Request
curl "https://api.somleng.org/carrier/v1/messages/4b783082-6bec-48d0-bb65-306532fe11d1" -d '{
"data": {
"id": "4b783082-6bec-48d0-bb65-306532fe11d1",
"type": "message",
"attributes": {
"price": "-0.05"
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer o4Sa3h9gHvlw-JxVgjoxHMfCuxKnYEOXtaPJLDfpbQk"
Endpoint
PATCH https://api.somleng.org/carrier/v1/messages/:id
PATCH https://api.somleng.org/carrier/v1/messages/4b783082-6bec-48d0-bb65-306532fe11d1
Parameters
{
"data": {
"id": "4b783082-6bec-48d0-bb65-306532fe11d1",
"type": "message",
"attributes": {
"price": "-0.05"
}
}
}
| Name | Description |
|---|---|
| data[attributes][price] | The charge for this call in the account's billing currency |
Response
200 OK
{
"data": {
"id": "4b783082-6bec-48d0-bb65-306532fe11d1",
"type": "message",
"attributes": {
"created_at": "2026-07-25T09:06:32Z",
"updated_at": "2026-07-25T09:06:32Z",
"to": "+85512334667",
"from": "2442",
"price_unit": "USD",
"direction": "outbound-api",
"status": "sent",
"body": "Hello World",
"price": "-0.05000"
},
"relationships": {
"account": {
"data": {
"id": "905e4d3f-c0db-455c-8d89-fd46898d5212",
"type": "account"
}
}
}
}
}
Phone Calls
List phone calls
Request
curl "https://api.somleng.org/carrier/v1/phone_calls?filter[status]=queued&filter[from_date]=2021-11-01T00%3A00%3A00Z&filter[to_date]=2021-11-01T00%3A00%3A00Z&filter[account]=21d893ab-913b-4a77-ba28-4c1dc72bbbd3&filter[direction]=outbound-api" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 7TE9W5Il2u8KuN-SVj0th-oo78o5w9sZHxlia3C8ikw"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_calls
GET https://api.somleng.org/carrier/v1/phone_calls?filter[status]=queued&filter[from_date]=2021-11-01T00%3A00%3A00Z&filter[to_date]=2021-11-01T00%3A00%3A00Z&filter[account]=21d893ab-913b-4a77-ba28-4c1dc72bbbd3&filter[direction]=outbound-api
Parameters
{
"filter": {
"status": "queued",
"from_date": "2021-11-01T00:00:00Z",
"to_date": "2021-11-01T00:00:00Z",
"account": "21d893ab-913b-4a77-ba28-4c1dc72bbbd3",
"direction": "outbound-api"
}
}
| Name | Description |
|---|---|
| filter[account] | Return phone calls from the provided account-sid |
| filter[from_date] | Return phone calls on or after the provided date/time in ISO 8601 format. |
| filter[to_date] | Return phone calls on or before the provided date/time in ISO 8601 format. |
| filter[direction] | One of inbound, outbound-api, and outbound-dial |
| filter[status] | One of queued, ringing, in-progress, busy, failed, no-answer, completed, and canceled |
Response
200 OK
{
"data": [
{
"id": "f937d96c-00e3-49aa-ac0d-05ec26cc5976",
"type": "phone_call",
"attributes": {
"created_at": "2021-11-01T01:00:00Z",
"updated_at": "2026-07-25T09:07:04Z",
"to": "+85512334667",
"from": "2442",
"price_unit": null,
"duration": null,
"direction": "outbound-api",
"status": "queued",
"price": null
},
"relationships": {
"account": {
"data": {
"id": "21d893ab-913b-4a77-ba28-4c1dc72bbbd3",
"type": "account"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/phone_calls?filter%5Baccount%5D=21d893ab-913b-4a77-ba28-4c1dc72bbbd3&filter%5Bdirection%5D=outbound-api&filter%5Bfrom_date%5D=2021-11-01T00%3A00%3A00Z&filter%5Bstatus%5D=queued&filter%5Bto_date%5D=2021-11-01T00%3A00%3A00Z&page%5Bbefore%5D=f937d96c-00e3-49aa-ac0d-05ec26cc5976",
"next": null
}
}
Retrieve a phone call
Request
curl "https://api.somleng.org/carrier/v1/phone_calls/7edc1aca-429c-412c-9761-e6ba4cc64f9d" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer Vm8cUaulZOdetMgNABzVirZKDHiDYM0tQsy8z9y3ovg"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_calls/:id
GET https://api.somleng.org/carrier/v1/phone_calls/7edc1aca-429c-412c-9761-e6ba4cc64f9d
Parameters
None known.
Response
200 OK
{
"data": {
"id": "7edc1aca-429c-412c-9761-e6ba4cc64f9d",
"type": "phone_call",
"attributes": {
"created_at": "2026-07-25T09:07:04Z",
"updated_at": "2026-07-25T09:07:04Z",
"to": "+85512334667",
"from": "2442",
"price_unit": null,
"duration": null,
"direction": "outbound-api",
"status": "queued",
"price": null
},
"relationships": {
"account": {
"data": {
"id": "919c8899-fcfa-4ff9-b5e7-7f9cb27fad73",
"type": "account"
}
}
}
}
}
Update a phone call
Request
curl "https://api.somleng.org/carrier/v1/phone_calls/b44cfacd-a94c-4587-8297-2e735eca7d4d" -d '{
"data": {
"id": "b44cfacd-a94c-4587-8297-2e735eca7d4d",
"type": "phone_call",
"attributes": {
"price": "-0.05"
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 02jno5PB2SDCxH2yyhnVNb9BQtPVXh9cryVLpX99vfg"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_calls/:id
PATCH https://api.somleng.org/carrier/v1/phone_calls/b44cfacd-a94c-4587-8297-2e735eca7d4d
Parameters
{
"data": {
"id": "b44cfacd-a94c-4587-8297-2e735eca7d4d",
"type": "phone_call",
"attributes": {
"price": "-0.05"
}
}
}
| Name | Description |
|---|---|
| data[attributes][price] | The charge for this call in the account's billing currency |
Response
200 OK
{
"data": {
"id": "b44cfacd-a94c-4587-8297-2e735eca7d4d",
"type": "phone_call",
"attributes": {
"created_at": "2026-07-25T09:07:04Z",
"updated_at": "2026-07-25T09:07:04Z",
"to": "+85512334667",
"from": "2442",
"price_unit": "USD",
"duration": "5",
"direction": "outbound-api",
"status": "completed",
"price": "-0.05000"
},
"relationships": {
"account": {
"data": {
"id": "aae92037-334e-4d31-bf16-c501e87e8a27",
"type": "account"
}
}
}
}
}
Phone Numbers
01. Create a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers" -d '{
"data": {
"type": "phone_number",
"attributes": {
"number": "1294",
"type": "short_code",
"metadata": {
"my_custom_field": "my_custom_field_value"
}
}
}
}' -X POST \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 1deahoOcl1HtPfA_Bwoes6VEWSy5JtddYZvQnYdvMg0"
Endpoint
POST https://api.somleng.org/carrier/v1/phone_numbers
POST https://api.somleng.org/carrier/v1/phone_numbers
Parameters
{
"data": {
"type": "phone_number",
"attributes": {
"number": "1294",
"type": "short_code",
"metadata": {
"my_custom_field": "my_custom_field_value"
}
}
}
}
| Name | Description |
|---|---|
| data[attributes][number] required | Phone number in E.164 format or shortcode. |
| data[attributes][type] required | The type of the phone number. Must be one of short_code, local, mobile, toll_free. |
| data[attributes][visibility] | The visibility of the phone number. Must be one of private, public, disabled. Defaults to public for phone numbers with a price and private for phone numbers without one |
| data[attributes][country] | The ISO 3166-1 alpha-2 country code of the phone number. If not specified, it's automatically resolved from the number parameter, or defaults to the carrier's country code if unresolvable. |
| data[attributes][price] | The price for the phone number in the billing currency of the carrier. |
| data[attributes][region] | The state or province abbreviation of this phone number's location. |
| data[attributes][locality] | The locality or city of this phone number's location. |
| data[attributes][lata] | The LATA of this phone number. Applicable only to phone numbers from the US and Canada. |
| data[attributes][rate_center] | The rate center of this phone number. Applicable only to phone numbers from the US and Canada. |
| data[attributes][latitude] | The latitude of this phone number's location. Applicable only for phone numbers from the US and Canada. |
| data[attributes][longitude] | The longitude of this phone number's location. Applicable only for phone numbers from the US and Canada. |
| data[attributes][metadata] | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
Response
201 Created
{
"data": {
"id": "b016a5f3-28c6-4f2a-814a-278aa26094fa",
"type": "phone_number",
"attributes": {
"created_at": "2026-07-25T09:06:52Z",
"updated_at": "2026-07-25T09:06:52Z",
"number": "1294",
"country": "KH",
"visibility": "private",
"type": "short_code",
"locality": null,
"rate_center": null,
"lata": null,
"latitude": null,
"longitude": null,
"metadata": {
"my_custom_field": "my_custom_field_value"
},
"currency": "KHR",
"price": "0.00",
"region": null
}
}
}
02. Update a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/21611ea5-bacc-43ce-b678-73c40f27b7fb" -d '{
"data": {
"type": "phone_number",
"id": "21611ea5-bacc-43ce-b678-73c40f27b7fb",
"attributes": {
"type": "mobile",
"visibility": "public",
"country": "US",
"price": "1.15",
"region": "AR",
"locality": "Little Rock",
"rate_center": "LITTLEROCK",
"lata": "528",
"latitude": "34.748463",
"longitude": "-92.284434",
"metadata": {
"my_custom_field": "my_custom_field_value"
}
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer kl3q51SVAfCdxnIPDE1M4pb4etuLl1mhUmaHOp3jWFY"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_numbers/:id
PATCH https://api.somleng.org/carrier/v1/phone_numbers/21611ea5-bacc-43ce-b678-73c40f27b7fb
Parameters
{
"data": {
"type": "phone_number",
"id": "21611ea5-bacc-43ce-b678-73c40f27b7fb",
"attributes": {
"type": "mobile",
"visibility": "public",
"country": "US",
"price": "1.15",
"region": "AR",
"locality": "Little Rock",
"rate_center": "LITTLEROCK",
"lata": "528",
"latitude": "34.748463",
"longitude": "-92.284434",
"metadata": {
"my_custom_field": "my_custom_field_value"
}
}
}
}
| Name | Description |
|---|---|
| data[attributes][type] | The type of the phone number. Must be one of short_code, local, mobile, toll_free. |
| data[attributes][visibility] | The visibility of the phone number. Must be one of private, public, disabled. Defaults to public for phone numbers with a price and private for phone numbers without one |
| data[attributes][country] | The ISO 3166-1 alpha-2 country code of the phone number. If not specified, it's automatically resolved from the number parameter, or defaults to the carrier's country code if unresolvable. |
| data[attributes][price] | The price for the phone number in the billing currency of the carrier. |
| data[attributes][region] | The state or province abbreviation of this phone number's location. |
| data[attributes][locality] | The locality or city of this phone number's location. |
| data[attributes][lata] | The LATA of this phone number. Applicable only to phone numbers from the US and Canada. |
| data[attributes][rate_center] | The rate center of this phone number. Applicable only to phone numbers from the US and Canada. |
| data[attributes][latitude] | The latitude of this phone number's location. Applicable only for phone numbers from the US and Canada. |
| data[attributes][longitude] | The longitude of this phone number's location. Applicable only for phone numbers from the US and Canada. |
| data[attributes][metadata] | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
Response
200 OK
{
"data": {
"id": "21611ea5-bacc-43ce-b678-73c40f27b7fb",
"type": "phone_number",
"attributes": {
"created_at": "2026-07-25T09:06:52Z",
"updated_at": "2026-07-25T09:06:52Z",
"number": "+15067020972",
"country": "US",
"visibility": "public",
"type": "mobile",
"locality": "Little Rock",
"rate_center": "LITTLEROCK",
"lata": "528",
"latitude": "34.748463",
"longitude": "-92.284434",
"metadata": {
"my_custom_field": "my_custom_field_value"
},
"currency": "CAD",
"price": "1.15",
"region": "AR"
}
}
}
03. Retrieve a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/6b9b971b-5406-4f8a-b893-854afec95b99" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer Pd0e4qaYI15hsk1cHGLv43ZIVpMi7fL4I5P2pfyca2g"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_numbers/:id
GET https://api.somleng.org/carrier/v1/phone_numbers/6b9b971b-5406-4f8a-b893-854afec95b99
Parameters
None known.
Response
200 OK
{
"data": {
"id": "6b9b971b-5406-4f8a-b893-854afec95b99",
"type": "phone_number",
"attributes": {
"created_at": "2026-07-25T09:06:53Z",
"updated_at": "2026-07-25T09:06:53Z",
"number": "+855972345770",
"country": "KH",
"visibility": "private",
"type": "mobile",
"locality": null,
"rate_center": null,
"lata": null,
"latitude": null,
"longitude": null,
"metadata": {},
"currency": "KHR",
"price": "0.00",
"region": null
}
}
}
04. List all phone numbers
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer pNv8n7-xumRh0GFTRFMz_SJ7cnGOKkHLEGoH_JRr8W0"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_numbers
GET https://api.somleng.org/carrier/v1/phone_numbers
Parameters
None known.
Response
200 OK
{
"data": [
{
"id": "4ff1f127-d9be-48ca-8598-c21d9ba7749b",
"type": "phone_number",
"attributes": {
"created_at": "2026-07-25T09:06:53Z",
"updated_at": "2026-07-25T09:06:53Z",
"number": "+855972345768",
"country": "KH",
"visibility": "private",
"type": "mobile",
"locality": null,
"rate_center": null,
"lata": null,
"latitude": null,
"longitude": null,
"metadata": {},
"currency": "KHR",
"price": "0.00",
"region": null
}
},
{
"id": "9512a6e3-3883-4ff7-b969-f79ac8c2be6f",
"type": "phone_number",
"attributes": {
"created_at": "2026-07-25T09:06:53Z",
"updated_at": "2026-07-25T09:06:53Z",
"number": "+855972345767",
"country": "KH",
"visibility": "private",
"type": "mobile",
"locality": null,
"rate_center": null,
"lata": null,
"latitude": null,
"longitude": null,
"metadata": {},
"currency": "KHR",
"price": "0.00",
"region": null
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/phone_numbers?page%5Bbefore%5D=4ff1f127-d9be-48ca-8598-c21d9ba7749b",
"next": null
}
}
05. Delete a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/4b2d647f-a8fc-4dd2-a2f0-24bb42ae0e92" -d '' -X DELETE \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer iFs0YsMsFO8lxxTjG9BryqbJ5vr_AvsI2m05SZhtQYE"
Endpoint
DELETE https://api.somleng.org/carrier/v1/phone_numbers/:id
DELETE https://api.somleng.org/carrier/v1/phone_numbers/4b2d647f-a8fc-4dd2-a2f0-24bb42ae0e92
Parameters
None known.
Response
204 No Content
06. Get number of available phone numbers per locality having a count less than 2
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/stats?filter[available]=true&filter[type]=local&group_by[]=country&group_by[]=region&group_by[]=locality&having[count][lt]=2" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer g9fKcxinxz29pSSlyH4g9CRZgAeW-UAXl8ylWs83Uqo"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_numbers/stats
GET https://api.somleng.org/carrier/v1/phone_numbers/stats?filter[available]=true&filter[type]=local&group_by[]=country&group_by[]=region&group_by[]=locality&having[count][lt]=2
Parameters
{
"filter": {
"available": "true",
"type": "local"
},
"group_by": [
"country",
"region",
"locality"
],
"having": {
"count": {
"lt": "2"
}
}
}
| Name | Description |
|---|---|
| filter[available] required | Return only available phone numbers. Must be true |
| filter[type] required | The phone number type. Must be local |
| filter[country] | The ISO country code. E.g. US |
| filter[region] | The ISO region code. E.g. AR |
| filter[locality] | The locality or city name. e.g. Little Rock |
| group_by required | An array of fields to group by. Must be ['country', 'region', 'locality'] |
| having[count][operator] | One of eq, neq, gt, gteq, lt, lteq |
| having[count][value] | The value of the count. Must be an integer greater than or equal to 0 |
Response
200 OK
{
"data": [
{
"id": "2e02a6de3fa86617dec16e762a756a2fc82f7f474215485effa2577b1a869e64",
"type": "aggregate_data",
"attributes": {
"statistic": {
"country": "US",
"region": "AL",
"locality": "Birmingham",
"value": 1
}
}
},
{
"id": "dbcd7a4b79acfdbeb7bc78dfcded1098b8a5b0ca1cb63619ae65864b89162520",
"type": "aggregate_data",
"attributes": {
"statistic": {
"country": "US",
"region": "AL",
"locality": "Huntsville",
"value": 1
}
}
},
{
"id": "7bb81870f4f3d4a6756f30d8a4ecbf98c0da08ec74cae4af760843e07bee7ec6",
"type": "aggregate_data",
"attributes": {
"statistic": {
"country": "US",
"region": "AL",
"locality": "Tuscaloosa",
"value": 1
}
}
},
{
"id": "f0e41da727a633bc8890195abcfb907391e664682d2da4cbd0a14f5e520bb7f4",
"type": "aggregate_data",
"attributes": {
"statistic": {
"country": "US",
"region": "AR",
"locality": "Hot Springs",
"value": 1
}
}
},
{
"id": "79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621",
"type": "aggregate_data",
"attributes": {
"statistic": {
"country": "US",
"region": null,
"locality": null,
"value": 1
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/phone_numbers/stats?filter%5Bavailable%5D=true&filter%5Btype%5D=local&group_by%5B%5D=country&group_by%5B%5D=region&group_by%5B%5D=locality&having%5Bcount%5D%5Blt%5D=2&page%5Bbefore%5D=2e02a6de3fa86617dec16e762a756a2fc82f7f474215485effa2577b1a869e64",
"next": null
}
}
TTS Events
List all TTS events
Request
curl "https://api.somleng.org/carrier/v1/tts_events?filter[from_date]=2026-07-24&filter[account]=851ca9e4-59ec-4ece-8320-fd176b418f72&filter[phone_call]=4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer oKNtNZlkYRpXFBusfb059nH40QZl9hGm2yhT7uYfqjA"
Endpoint
GET https://api.somleng.org/carrier/v1/tts_events
GET https://api.somleng.org/carrier/v1/tts_events?filter[from_date]=2026-07-24&filter[account]=851ca9e4-59ec-4ece-8320-fd176b418f72&filter[phone_call]=4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b
Parameters
{
"filter": {
"from_date": "2026-07-24",
"account": "851ca9e4-59ec-4ece-8320-fd176b418f72",
"phone_call": "4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b"
}
}
| Name | Description |
|---|---|
| filter[account] | Return TTS Events from the provided account SID |
| filter[phone_call] | Return TTS Events from the provided phone call SID |
| filter[from_date] | Return TTS events on or after the provided date/time in ISO 8601 format. |
| filter[to_date] | Return TTS events on or before the provided date/time in ISO 8601 format. |
Response
200 OK
{
"data": [
{
"id": "6049fd9b-3952-45cc-a227-651a0b2e4898",
"type": "tts_event",
"attributes": {
"created_at": "2026-07-25T09:06:07Z",
"updated_at": "2026-07-25T09:06:07Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 200
},
"relationships": {
"account": {
"data": {
"id": "851ca9e4-59ec-4ece-8320-fd176b418f72",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b",
"type": "phone_call"
}
}
}
},
{
"id": "6fcbdc80-7513-4fa3-8788-8518ca928f59",
"type": "tts_event",
"attributes": {
"created_at": "2026-07-25T09:06:07Z",
"updated_at": "2026-07-25T09:06:07Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 100
},
"relationships": {
"account": {
"data": {
"id": "851ca9e4-59ec-4ece-8320-fd176b418f72",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b",
"type": "phone_call"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/tts_events?filter%5Baccount%5D=851ca9e4-59ec-4ece-8320-fd176b418f72&filter%5Bfrom_date%5D=2026-07-24&filter%5Bphone_call%5D=4c24b192-bbb2-4550-8f0f-f6c5c1e8c10b&page%5Bbefore%5D=6049fd9b-3952-45cc-a227-651a0b2e4898",
"next": null
}
}
Retrieve a TTS Event
Request
curl "https://api.somleng.org/carrier/v1/tts_events/739c5f9d-fd72-4ff5-b67e-b95a345ab852" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 7gV8rEU9TfD3RgcaoUvo9c1wSirLV4guXUyjJt_EjpE"
Endpoint
GET https://api.somleng.org/carrier/v1/tts_events/:id
GET https://api.somleng.org/carrier/v1/tts_events/739c5f9d-fd72-4ff5-b67e-b95a345ab852
Parameters
None known.
Response
200 OK
{
"data": {
"id": "739c5f9d-fd72-4ff5-b67e-b95a345ab852",
"type": "tts_event",
"attributes": {
"created_at": "2026-07-25T09:06:07Z",
"updated_at": "2026-07-25T09:06:07Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 100
},
"relationships": {
"account": {
"data": {
"id": "8ab69c3b-5377-4a7d-a5ed-12a3f0cd533b",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "a783e2d8-665f-48c3-afd7-893ba298121d",
"type": "phone_call"
}
}
}
}
}