NAV
cURL

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",
      "metadata": {
        "foo": "bar"
      }
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer pnlz7dnhHlLNbr412pF20aY2yyiOjOlmNUK5iW5DK_0"

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",
      "metadata": {
        "foo": "bar"
      }
    }
  }
}
Name Description
data[attributes][name] required A friendly name which identifies the account
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": "ec07fc9f-a92e-4431-9903-48acc474390d",
    "type": "account",
    "attributes": {
      "created_at": "2025-07-21T06:36:57Z",
      "updated_at": "2025-07-21T06:36:57Z",
      "name": "Rocket Rides",
      "metadata": {
        "foo": "bar"
      },
      "status": "enabled",
      "type": "carrier_managed",
      "auth_token": "bFdFuIAVBxjMHuNqxbc984YqT3DCBrNzbWW6wK_dETM",
      "default_tts_voice": "Basic.Kal"
    }
  }
}

Delete an account

Request

curl "https://api.somleng.org/carrier/v1/accounts/a2ff310b-32fd-4c8d-a157-681b6170dd5a" -d '' -X DELETE \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer wkvXS8Qq5oXzhlQKO-hHAnWDIYBnHZ9hsMkwvQeVOis"

Endpoint

DELETE https://api.somleng.org/carrier/v1/accounts/:id

DELETE https://api.somleng.org/carrier/v1/accounts/a2ff310b-32fd-4c8d-a157-681b6170dd5a

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 ELlmt170N1_eOA8bSC9b7Z9j33pbaKkd-WfyoCIAV00"

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": "e07b64b6-60b1-4faa-af4a-bd79473f78ce",
      "type": "account",
      "attributes": {
        "created_at": "2025-07-21T06:36:57Z",
        "updated_at": "2025-07-21T06:36:57Z",
        "name": "Telco Net",
        "metadata": {},
        "status": "enabled",
        "type": "carrier_managed",
        "auth_token": "ST77ciEX7hKDPhWUQEMSwJ7-dysRCqIWErKsiYRABkQ",
        "default_tts_voice": "Basic.Kal"
      }
    },
    {
      "id": "879b912f-79d0-4bc8-8861-800ce40a63e2",
      "type": "account",
      "attributes": {
        "created_at": "2025-07-21T06:36:57Z",
        "updated_at": "2025-07-21T06:36:57Z",
        "name": "Rocket Rides",
        "metadata": {},
        "status": "enabled",
        "type": "customer_managed",
        "default_tts_voice": "Basic.Kal"
      }
    }
  ],
  "links": {
    "prev": "https://api.somleng.org/carrier/v1/accounts?page%5Bbefore%5D=e07b64b6-60b1-4faa-af4a-bd79473f78ce",
    "next": null
  }
}

Retrieve an account

Request

curl "https://api.somleng.org/carrier/v1/accounts/b6a09478-6f31-47e5-9343-f6c4dd2f3300" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer -Xje1ZUidYPedkxpmh30XYSyfeVClfBy_o1qbEuX_xw"

Endpoint

GET https://api.somleng.org/carrier/v1/accounts/:id

GET https://api.somleng.org/carrier/v1/accounts/b6a09478-6f31-47e5-9343-f6c4dd2f3300

Parameters

Name Description
id required The id of the account to be retrieved.

Response


200 OK
{
  "data": {
    "id": "b6a09478-6f31-47e5-9343-f6c4dd2f3300",
    "type": "account",
    "attributes": {
      "created_at": "2025-07-21T06:36:57Z",
      "updated_at": "2025-07-21T06:36:57Z",
      "name": "Rocket Rides",
      "metadata": {},
      "status": "enabled",
      "type": "carrier_managed",
      "auth_token": "5lvq43s-gWqB3jdzAxsir-6WtrjFLaJVC8_wGvwe6Oc",
      "default_tts_voice": "Basic.Kal"
    }
  }
}

Update an account

Request

curl "https://api.somleng.org/carrier/v1/accounts/53458d87-fc5c-4492-a7f6-7ef07cb0c5e2" -d '{
  "data": {
    "attributes": {
      "status": null,
      "name": "Bob Cats",
      "status": "disabled",
      "default_tts_voice": "Basic.Kal",
      "metadata": {
        "bar": "foo"
      }
    },
    "type": "account",
    "id": "53458d87-fc5c-4492-a7f6-7ef07cb0c5e2"
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer SndWSY5Ei7qtMS6caDi2VLHwmNFNxAi9xkupzElmsjo"

Endpoint

PATCH https://api.somleng.org/carrier/v1/accounts/:id

PATCH https://api.somleng.org/carrier/v1/accounts/53458d87-fc5c-4492-a7f6-7ef07cb0c5e2

Parameters

{
  "data": {
    "attributes": {
      "status": null,
      "name": "Bob Cats",
      "status": "disabled",
      "default_tts_voice": "Basic.Kal",
      "metadata": {
        "bar": "foo"
      }
    },
    "type": "account",
    "id": "53458d87-fc5c-4492-a7f6-7ef07cb0c5e2"
  }
}
Name Description
data[attributes][status] Update the status of the account. One of either enabled or disabled.

Response


200 OK
{
  "data": {
    "id": "53458d87-fc5c-4492-a7f6-7ef07cb0c5e2",
    "type": "account",
    "attributes": {
      "created_at": "2025-07-21T06:36:57Z",
      "updated_at": "2025-07-21T06:36:57Z",
      "name": "Bob Cats",
      "metadata": {
        "foo": "bar",
        "bar": "foo"
      },
      "status": "disabled",
      "type": "carrier_managed",
      "auth_token": "wyMGVf28yvk_GG53khCRQLMorFT7XuFVf-xs3NxSASc",
      "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 ZPodipR2KAuSPrUmFad8aw-2Bj7RDaTyeNCg-xq92Pw"

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": "e9c7eff0-7eb2-4ec5-af9a-517433286864",
      "type": "event",
      "attributes": {
        "created_at": "2025-07-21T06:37:08Z",
        "updated_at": "2025-07-21T06:37:08Z",
        "type": "phone_call.completed",
        "details": {
          "data": {
            "id": "4a1c564d-8cee-4900-9846-c3ff1b77ecba",
            "type": "phone_call",
            "attributes": {
              "to": "+85512334667",
              "from": "2442",
              "price": null,
              "status": "queued",
              "duration": null,
              "direction": "outbound-api",
              "created_at": "2025-07-21T06:37:08Z",
              "price_unit": null,
              "updated_at": "2025-07-21T06:37:08Z"
            },
            "relationships": {
              "account": {
                "data": {
                  "id": "8d1f09a5-e12f-4981-8728-20f53b86fb2a",
                  "type": "account"
                }
              }
            }
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.somleng.org/carrier/v1/events?page%5Bbefore%5D=e9c7eff0-7eb2-4ec5-af9a-517433286864",
    "next": null
  }
}

Retrieve an Event

Request

curl "https://api.somleng.org/carrier/v1/events/e66115a6-ff28-43d7-b075-b5aeb32541b7" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer lBCtSL6zaxF0dceLiWDbzc-2kAeCwj2_a5iS5WDR7Hs"

Endpoint

GET https://api.somleng.org/carrier/v1/events/:id

GET https://api.somleng.org/carrier/v1/events/e66115a6-ff28-43d7-b075-b5aeb32541b7

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "e66115a6-ff28-43d7-b075-b5aeb32541b7",
    "type": "event",
    "attributes": {
      "created_at": "2025-07-21T06:37:08Z",
      "updated_at": "2025-07-21T06:37:08Z",
      "type": "phone_call.completed",
      "details": {
        "data": {
          "id": "97776d2a-dcc4-44e0-82b8-5d48985e5115",
          "type": "phone_call",
          "attributes": {
            "to": "+85512334667",
            "from": "2442",
            "price": null,
            "status": "queued",
            "duration": null,
            "direction": "outbound-api",
            "created_at": "2025-07-21T06:37:08Z",
            "price_unit": null,
            "updated_at": "2025-07-21T06:37:08Z"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "ff12bb10-ff0f-4e93-9b8c-39cf1f3f5f01",
                "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]=dcf724d4-6568-4fd6-9f24-c0e1844e1326&filter[direction]=outbound-api" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer quK2T6Nznv2RMwxrMlLaJtG1q2LgfDNT8coYTQv_BAo"

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]=dcf724d4-6568-4fd6-9f24-c0e1844e1326&filter[direction]=outbound-api

Parameters

{
  "filter": {
    "status": "sent",
    "from_date": "2021-11-01T00:00:00Z",
    "to_date": "2021-11-01T00:00:00Z",
    "account": "dcf724d4-6568-4fd6-9f24-c0e1844e1326",
    "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": "8987fd7d-9192-4dac-8f1b-9fbd0e95025a",
      "type": "message",
      "attributes": {
        "created_at": "2021-11-01T01:00:00Z",
        "updated_at": "2025-07-21T06:35:48Z",
        "to": "+85512334667",
        "from": "2442",
        "price": null,
        "price_unit": null,
        "direction": "outbound-api",
        "status": "sent",
        "body": "Hello World"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "dcf724d4-6568-4fd6-9f24-c0e1844e1326",
            "type": "account"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.somleng.org/carrier/v1/messages?filter%5Baccount%5D=dcf724d4-6568-4fd6-9f24-c0e1844e1326&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=8987fd7d-9192-4dac-8f1b-9fbd0e95025a",
    "next": null
  }
}

Retrieve a message

Request

curl "https://api.somleng.org/carrier/v1/messages/c82e6eda-23a0-49a1-923f-1dcf4534b0a9" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer qV3VENGrES1XlN7nuSFL5pujZvThLFaqsl70UGd0sL0"

Endpoint

GET https://api.somleng.org/carrier/v1/messages/:id

GET https://api.somleng.org/carrier/v1/messages/c82e6eda-23a0-49a1-923f-1dcf4534b0a9

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "c82e6eda-23a0-49a1-923f-1dcf4534b0a9",
    "type": "message",
    "attributes": {
      "created_at": "2025-07-21T06:35:48Z",
      "updated_at": "2025-07-21T06:35:48Z",
      "to": "+85512334667",
      "from": "2442",
      "price": null,
      "price_unit": null,
      "direction": "outbound-api",
      "status": "accepted",
      "body": "Hello World"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "76c053b4-24eb-4a41-87fb-ec520346d0fe",
          "type": "account"
        }
      }
    }
  }
}

Update a message

Request

curl "https://api.somleng.org/carrier/v1/messages/833e4e2d-bc07-4353-b93f-167afded9eec" -d '{
  "data": {
    "id": "833e4e2d-bc07-4353-b93f-167afded9eec",
    "type": "message",
    "attributes": {
      "price": "-0.05"
    }
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer 4rakmudIOor_UbI4UhmVYT-yPY_K9YE_4f66jMt684k"

Endpoint

PATCH https://api.somleng.org/carrier/v1/messages/:id

PATCH https://api.somleng.org/carrier/v1/messages/833e4e2d-bc07-4353-b93f-167afded9eec

Parameters

{
  "data": {
    "id": "833e4e2d-bc07-4353-b93f-167afded9eec",
    "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": "833e4e2d-bc07-4353-b93f-167afded9eec",
    "type": "message",
    "attributes": {
      "created_at": "2025-07-21T06:35:48Z",
      "updated_at": "2025-07-21T06:35:48Z",
      "to": "+85512334667",
      "from": "2442",
      "price": "-0.05",
      "price_unit": "USD",
      "direction": "outbound-api",
      "status": "sent",
      "body": "Hello World"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "f53ce427-e77d-468a-a653-baacc01e21eb",
          "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]=9f7d1999-85e8-462c-bddf-4ee0536cb442&filter[direction]=outbound-api" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer qqGgJoOPX2a93H-lrfvvEVwwnUv7AT_Vr7_QUif5iYU"

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]=9f7d1999-85e8-462c-bddf-4ee0536cb442&filter[direction]=outbound-api

Parameters

{
  "filter": {
    "status": "queued",
    "from_date": "2021-11-01T00:00:00Z",
    "to_date": "2021-11-01T00:00:00Z",
    "account": "9f7d1999-85e8-462c-bddf-4ee0536cb442",
    "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": "0bcafdb9-8ff8-4657-81f7-f2b7c2e99a24",
      "type": "phone_call",
      "attributes": {
        "created_at": "2021-11-01T01:00:00Z",
        "updated_at": "2025-07-21T06:36:44Z",
        "to": "+85512334667",
        "from": "2442",
        "price": null,
        "price_unit": null,
        "duration": null,
        "direction": "outbound-api",
        "status": "queued"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "9f7d1999-85e8-462c-bddf-4ee0536cb442",
            "type": "account"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.somleng.org/carrier/v1/phone_calls?filter%5Baccount%5D=9f7d1999-85e8-462c-bddf-4ee0536cb442&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=0bcafdb9-8ff8-4657-81f7-f2b7c2e99a24",
    "next": null
  }
}

Retrieve a phone call

Request

curl "https://api.somleng.org/carrier/v1/phone_calls/1434d60b-7e5a-4d06-b968-9b936d945f77" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer ZBipnh8mZfpfxxwwpNpfyyPa7BotMB4c9XZsQ3vgS4o"

Endpoint

GET https://api.somleng.org/carrier/v1/phone_calls/:id

GET https://api.somleng.org/carrier/v1/phone_calls/1434d60b-7e5a-4d06-b968-9b936d945f77

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "1434d60b-7e5a-4d06-b968-9b936d945f77",
    "type": "phone_call",
    "attributes": {
      "created_at": "2025-07-21T06:36:44Z",
      "updated_at": "2025-07-21T06:36:44Z",
      "to": "+85512334667",
      "from": "2442",
      "price": null,
      "price_unit": null,
      "duration": null,
      "direction": "outbound-api",
      "status": "queued"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "58200e9c-b424-4d83-a874-138c7c92e4a1",
          "type": "account"
        }
      }
    }
  }
}

Update a phone call

Request

curl "https://api.somleng.org/carrier/v1/phone_calls/ea457b3b-a8d3-4524-a1bc-0c37d62188fa" -d '{
  "data": {
    "id": "ea457b3b-a8d3-4524-a1bc-0c37d62188fa",
    "type": "phone_call",
    "attributes": {
      "price": "-0.05"
    }
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer l1GQv-ls4EMbu7vqU91Fzcg_scGvAzXv7oTjnSCgL90"

Endpoint

PATCH https://api.somleng.org/carrier/v1/phone_calls/:id

PATCH https://api.somleng.org/carrier/v1/phone_calls/ea457b3b-a8d3-4524-a1bc-0c37d62188fa

Parameters

{
  "data": {
    "id": "ea457b3b-a8d3-4524-a1bc-0c37d62188fa",
    "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": "ea457b3b-a8d3-4524-a1bc-0c37d62188fa",
    "type": "phone_call",
    "attributes": {
      "created_at": "2025-07-21T06:36:44Z",
      "updated_at": "2025-07-21T06:36:44Z",
      "to": "+85512334667",
      "from": "2442",
      "price": "-0.05",
      "price_unit": "USD",
      "duration": "5",
      "direction": "outbound-api",
      "status": "completed"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "5e6743ed-0f95-4221-aee5-37271414b94e",
          "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 bo1JmYy9SCEISADxzr6MYRYFNOrBq0fTAaEy3jLKuG8"

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": "df620d20-6317-42bc-89ce-5d70495fcc43",
    "type": "phone_number",
    "attributes": {
      "created_at": "2025-07-21T06:35:47Z",
      "updated_at": "2025-07-21T06:35:47Z",
      "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/94780a94-e353-49c8-a885-b39514eaef7a" -d '{
  "data": {
    "type": "phone_number",
    "id": "94780a94-e353-49c8-a885-b39514eaef7a",
    "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 GR1fK70yyhD4kW-OtubvLJ3g3LsQNc0Bh5a3x-qCBNo"

Endpoint

PATCH https://api.somleng.org/carrier/v1/phone_numbers/:id

PATCH https://api.somleng.org/carrier/v1/phone_numbers/94780a94-e353-49c8-a885-b39514eaef7a

Parameters

{
  "data": {
    "type": "phone_number",
    "id": "94780a94-e353-49c8-a885-b39514eaef7a",
    "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": "94780a94-e353-49c8-a885-b39514eaef7a",
    "type": "phone_number",
    "attributes": {
      "created_at": "2025-07-21T06:35:46Z",
      "updated_at": "2025-07-21T06:35:46Z",
      "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/27355f57-e0a8-4644-9180-a09e63a3f1dc" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer _gYB8ptukvvWaHMnUsBuKbGg_0Eb1BF_IwrBjtxHqjc"

Endpoint

GET https://api.somleng.org/carrier/v1/phone_numbers/:id

GET https://api.somleng.org/carrier/v1/phone_numbers/27355f57-e0a8-4644-9180-a09e63a3f1dc

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "27355f57-e0a8-4644-9180-a09e63a3f1dc",
    "type": "phone_number",
    "attributes": {
      "created_at": "2025-07-21T06:35:47Z",
      "updated_at": "2025-07-21T06:35:47Z",
      "number": "+855972345690",
      "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 gXW451z6y8qhHvKinzZfl0D8Lb235tU0Z9wh-t6nbOM"

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": "a4931048-b234-453b-bbd3-740ae9c11983",
      "type": "phone_number",
      "attributes": {
        "created_at": "2025-07-21T06:35:46Z",
        "updated_at": "2025-07-21T06:35:46Z",
        "number": "+855972345688",
        "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": "cf29fe8c-faa4-4d61-81ae-c1737e146373",
      "type": "phone_number",
      "attributes": {
        "created_at": "2025-07-21T06:35:46Z",
        "updated_at": "2025-07-21T06:35:46Z",
        "number": "+855972345687",
        "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=a4931048-b234-453b-bbd3-740ae9c11983",
    "next": null
  }
}

05. Delete a phone number

Request

curl "https://api.somleng.org/carrier/v1/phone_numbers/07a5ec89-cd1b-4669-aa5c-ca96ea6d2f6b" -d '' -X DELETE \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer isUmJfQnbIGPuF1DJMQkaar0Ka6O_4Em9QSWuGNUIU4"

Endpoint

DELETE https://api.somleng.org/carrier/v1/phone_numbers/:id

DELETE https://api.somleng.org/carrier/v1/phone_numbers/07a5ec89-cd1b-4669-aa5c-ca96ea6d2f6b

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 jTdzmLn6q4nzwF-8_MdcxBQUxeMnzPdZM7v31Qn9wSk"

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]=2025-07-20&filter[account]=9fa35ebf-6763-40fd-a42e-567f432c3c40&filter[phone_call]=9dacbae5-c49e-4749-99ff-721c4c43a06c" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer _ZijlhWWbamJqpXxtZn4Kix3ZWMa2VM-VwJFcbXBVF8"

Endpoint

GET https://api.somleng.org/carrier/v1/tts_events

GET https://api.somleng.org/carrier/v1/tts_events?filter[from_date]=2025-07-20&filter[account]=9fa35ebf-6763-40fd-a42e-567f432c3c40&filter[phone_call]=9dacbae5-c49e-4749-99ff-721c4c43a06c

Parameters

{
  "filter": {
    "from_date": "2025-07-20",
    "account": "9fa35ebf-6763-40fd-a42e-567f432c3c40",
    "phone_call": "9dacbae5-c49e-4749-99ff-721c4c43a06c"
  }
}
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": "8fd31f29-f44b-445b-af82-12fe69232fd7",
      "type": "tts_event",
      "attributes": {
        "created_at": "2025-07-21T06:36:55Z",
        "updated_at": "2025-07-21T06:36:55Z",
        "voice": "Basic.Kal (Male, en-US)",
        "characters": 200
      },
      "relationships": {
        "account": {
          "data": {
            "id": "9fa35ebf-6763-40fd-a42e-567f432c3c40",
            "type": "account"
          }
        },
        "phone_call": {
          "data": {
            "id": "9dacbae5-c49e-4749-99ff-721c4c43a06c",
            "type": "phone_call"
          }
        }
      }
    },
    {
      "id": "8f128331-c9a2-4453-95ae-782d1bbdcee1",
      "type": "tts_event",
      "attributes": {
        "created_at": "2025-07-21T06:36:55Z",
        "updated_at": "2025-07-21T06:36:55Z",
        "voice": "Basic.Kal (Male, en-US)",
        "characters": 100
      },
      "relationships": {
        "account": {
          "data": {
            "id": "9fa35ebf-6763-40fd-a42e-567f432c3c40",
            "type": "account"
          }
        },
        "phone_call": {
          "data": {
            "id": "9dacbae5-c49e-4749-99ff-721c4c43a06c",
            "type": "phone_call"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.somleng.org/carrier/v1/tts_events?filter%5Baccount%5D=9fa35ebf-6763-40fd-a42e-567f432c3c40&filter%5Bfrom_date%5D=2025-07-20&filter%5Bphone_call%5D=9dacbae5-c49e-4749-99ff-721c4c43a06c&page%5Bbefore%5D=8fd31f29-f44b-445b-af82-12fe69232fd7",
    "next": null
  }
}

Retrieve a TTS Event

Request

curl "https://api.somleng.org/carrier/v1/tts_events/89cc9b9b-f8b5-4613-8ccf-9c3bc16be3b1" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer 9DelBc6tWNJ5mma52KS3vBrq6QpFcrTomSnFMUOYoNk"

Endpoint

GET https://api.somleng.org/carrier/v1/tts_events/:id

GET https://api.somleng.org/carrier/v1/tts_events/89cc9b9b-f8b5-4613-8ccf-9c3bc16be3b1

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "89cc9b9b-f8b5-4613-8ccf-9c3bc16be3b1",
    "type": "tts_event",
    "attributes": {
      "created_at": "2025-07-21T06:36:55Z",
      "updated_at": "2025-07-21T06:36:55Z",
      "voice": "Basic.Kal (Male, en-US)",
      "characters": 100
    },
    "relationships": {
      "account": {
        "data": {
          "id": "1f3b7e17-3de4-4768-a63e-ca130a7a4e29",
          "type": "account"
        }
      },
      "phone_call": {
        "data": {
          "id": "d1e07639-3f12-423b-9482-22dcfd8822ac",
          "type": "phone_call"
        }
      }
    }
  }
}