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"
)
Events
Retrieve an Event
Request
curl -g "https://api.somleng.org/carrier/v1/events/20cc805d-0184-440a-afd7-af6342c6fa37" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer ka1BT3t5y6qMneHqhk2iLepilgTVIwLE8G38rJ6edmI"
Endpoint
GET https://api.somleng.org/carrier/v1/events/:id
GET https://api.somleng.org/carrier/v1/events/20cc805d-0184-440a-afd7-af6342c6fa37
Parameters
None known.
Response
200 OK
{
"data": {
"id": "20cc805d-0184-440a-afd7-af6342c6fa37",
"type": "event",
"attributes": {
"created_at": "2024-04-18T07:39:35Z",
"updated_at": "2024-04-18T07:39:35Z",
"type": "phone_call.completed",
"details": {
"data": {
"id": "40938508-3326-49ed-b085-bce791370529",
"type": "phone_call",
"attributes": {
"to": "+85512334667",
"from": "2442",
"price": null,
"status": "queued",
"duration": null,
"direction": "outbound-api",
"created_at": "2024-04-18T07:39:35Z",
"price_unit": null,
"updated_at": "2024-04-18T07:39:35Z"
},
"relationships": {
"account": {
"data": {
"id": "9a087e90-41a4-4155-92de-89dbd3e2f41f",
"type": "account"
}
}
}
}
}
}
}
}
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 -g "https://api.somleng.org/carrier/v1/events" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer heZVg6xnzjepmNX9bAUDi242bH3cJniSBM-omfjnSbc"
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": "acc2a94c-0ba9-4a20-81e8-ca7a81afe0a9",
"type": "event",
"attributes": {
"created_at": "2024-04-18T07:39:35Z",
"updated_at": "2024-04-18T07:39:35Z",
"type": "phone_call.completed",
"details": {
"data": {
"id": "04638c0b-5723-4d4d-814e-93590c921cf2",
"type": "phone_call",
"attributes": {
"to": "+85512334667",
"from": "2442",
"price": null,
"status": "queued",
"duration": null,
"direction": "outbound-api",
"created_at": "2024-04-18T07:39:35Z",
"price_unit": null,
"updated_at": "2024-04-18T07:39:35Z"
},
"relationships": {
"account": {
"data": {
"id": "f5d97b6e-2218-4f04-9f2a-bf998a18ee8c",
"type": "account"
}
}
}
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/events?page%5Bbefore%5D=acc2a94c-0ba9-4a20-81e8-ca7a81afe0a9",
"next": null
}
}
Phone Calls
Update a phone call
Request
curl "https://api.somleng.org/carrier/v1/phone_calls/c00a2464-4641-4e52-bc8f-323ab2ed9d9a" -d '{
"data": {
"id": "c00a2464-4641-4e52-bc8f-323ab2ed9d9a",
"type": "phone_call",
"attributes": {
"price": "-0.05",
"price_unit": "USD"
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer _AOu5lpTDCBwKUUBa55slFd1xUCNG6nV3byy7PD8u08"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_calls/:id
PATCH https://api.somleng.org/carrier/v1/phone_calls/c00a2464-4641-4e52-bc8f-323ab2ed9d9a
Parameters
{
"data": {
"id": "c00a2464-4641-4e52-bc8f-323ab2ed9d9a",
"type": "phone_call",
"attributes": {
"price": "-0.05",
"price_unit": "USD"
}
}
}
Name | Description |
---|---|
data[attributes][price] | The charge for this call. |
data[attributes][price_unit] | The currency in which price is measured, in ISO 4127 format. (e.g., USD , EUR , JPY ). Always capitalized for calls. |
Response
200 OK
{
"data": {
"id": "c00a2464-4641-4e52-bc8f-323ab2ed9d9a",
"type": "phone_call",
"attributes": {
"created_at": "2024-04-18T07:39:44Z",
"updated_at": "2024-04-18T07:39:44Z",
"to": "+85512334667",
"from": "2442",
"price": "-0.05",
"price_unit": "USD",
"duration": "5",
"direction": "outbound-api",
"status": "completed"
},
"relationships": {
"account": {
"data": {
"id": "0df55920-1e4d-4031-96d7-2acee287ea71",
"type": "account"
}
}
}
}
}
List phone calls
Request
curl -g "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]=2a4b41f6-3480-4c15-9ca2-7c5e1efe0590&filter[direction]=outbound-api" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer BWjyaf74m-MkgW3WStyNIOIYZ9VnVkxgqIalsyKdM_I"
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]=2a4b41f6-3480-4c15-9ca2-7c5e1efe0590&filter[direction]=outbound-api
Parameters
filter: {"status"=>"queued", "from_date"=>"2021-11-01T00:00:00Z", "to_date"=>"2021-11-01T00:00:00Z", "account"=>"2a4b41f6-3480-4c15-9ca2-7c5e1efe0590", "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 and outbound-api |
filter[status] | One of queued , ringing , in-progress , busy , failed , no-answer , completed , and canceled |
Response
200 OK
{
"data": [
{
"id": "4ab5130e-e4fc-436e-836a-5a878f7726fd",
"type": "phone_call",
"attributes": {
"created_at": "2021-11-01T00:00:00Z",
"updated_at": "2024-04-18T07:39:44Z",
"to": "+85512334667",
"from": "2442",
"price": null,
"price_unit": null,
"duration": null,
"direction": "outbound-api",
"status": "queued"
},
"relationships": {
"account": {
"data": {
"id": "2a4b41f6-3480-4c15-9ca2-7c5e1efe0590",
"type": "account"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/phone_calls?filter%5Baccount%5D=2a4b41f6-3480-4c15-9ca2-7c5e1efe0590&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=4ab5130e-e4fc-436e-836a-5a878f7726fd",
"next": null
}
}
Retrieve a phone call
Request
curl -g "https://api.somleng.org/carrier/v1/phone_calls/1542b315-ca1b-40c5-9318-b88b43549187" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 68xdPDKXuHB-NczsyXphk2KurQIX_U9un4zktvHZn7g"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_calls/:id
GET https://api.somleng.org/carrier/v1/phone_calls/1542b315-ca1b-40c5-9318-b88b43549187
Parameters
None known.
Response
200 OK
{
"data": {
"id": "1542b315-ca1b-40c5-9318-b88b43549187",
"type": "phone_call",
"attributes": {
"created_at": "2024-04-18T07:39:45Z",
"updated_at": "2024-04-18T07:39:45Z",
"to": "+85512334667",
"from": "2442",
"price": null,
"price_unit": null,
"duration": null,
"direction": "outbound-api",
"status": "queued"
},
"relationships": {
"account": {
"data": {
"id": "8dd077de-7dcf-4173-8bf8-3f8d94db98a0",
"type": "account"
}
}
}
}
}
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 YbaSKF-ye75OL7EQRuluphYH7KTdts4iehb6RAmuUfo"
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": "4159fe34-455d-4106-8225-9fff06555fa4",
"type": "account",
"attributes": {
"created_at": "2024-04-18T07:40:00Z",
"updated_at": "2024-04-18T07:40:00Z",
"name": "Rocket Rides",
"metadata": {
"foo": "bar"
},
"status": "enabled",
"type": "carrier_managed",
"auth_token": "RpNP2wTh-OLjFJSofaZXBpPxtjRw8wyAkZxm1adZ98c",
"default_tts_voice": "Basic.Kal"
}
}
}
Update an account
Request
curl "https://api.somleng.org/carrier/v1/accounts/91967f16-5a5c-4513-a7cf-8572c952429e" -d '{
"data": {
"attributes": {
"status": null,
"name": "Bob Cats",
"status": "disabled",
"default_tts_voice": "Basic.Kal",
"metadata": {
"bar": "foo"
}
},
"type": "account",
"id": "91967f16-5a5c-4513-a7cf-8572c952429e"
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer LBl7CLfHMhAJK52Z2vvkjJ_4ae9SiWQ5l1R-rnu3Tgg"
Endpoint
PATCH https://api.somleng.org/carrier/v1/accounts/:id
PATCH https://api.somleng.org/carrier/v1/accounts/91967f16-5a5c-4513-a7cf-8572c952429e
Parameters
{
"data": {
"attributes": {
"status": null,
"name": "Bob Cats",
"status": "disabled",
"default_tts_voice": "Basic.Kal",
"metadata": {
"bar": "foo"
}
},
"type": "account",
"id": "91967f16-5a5c-4513-a7cf-8572c952429e"
}
}
Name | Description |
---|---|
data[attributes][status] | Update the status of the account. One of either enabled or disabled . |
Response
200 OK
{
"data": {
"id": "91967f16-5a5c-4513-a7cf-8572c952429e",
"type": "account",
"attributes": {
"created_at": "2024-04-18T07:40:01Z",
"updated_at": "2024-04-18T07:40:01Z",
"name": "Bob Cats",
"metadata": {
"foo": "bar",
"bar": "foo"
},
"status": "disabled",
"type": "carrier_managed",
"auth_token": "DCqCAHz1hk15pghaMlTZzsfZWXGRC1CbSEzWHsU7TP8",
"default_tts_voice": "Basic.Kal"
}
}
}
Retrieve an account
Request
curl -g "https://api.somleng.org/carrier/v1/accounts/f73d17bd-92d2-4089-8433-118b4911e2b1" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer -GwxTiEIerz5dAo2vLYY---FIrJYYQ177Q4YjTHELbA"
Endpoint
GET https://api.somleng.org/carrier/v1/accounts/:id
GET https://api.somleng.org/carrier/v1/accounts/f73d17bd-92d2-4089-8433-118b4911e2b1
Parameters
Name | Description |
---|---|
id required | The id of the account to be retrieved. |
Response
200 OK
{
"data": {
"id": "f73d17bd-92d2-4089-8433-118b4911e2b1",
"type": "account",
"attributes": {
"created_at": "2024-04-18T07:40:01Z",
"updated_at": "2024-04-18T07:40:01Z",
"name": "Rocket Rides",
"metadata": {
},
"status": "enabled",
"type": "carrier_managed",
"auth_token": "OPDAsyxvFzKDP3rKvOSQkF7UZCT4r6IMi4S6WnPc6cI",
"default_tts_voice": "Basic.Kal"
}
}
}
List all accounts
Request
curl -g "https://api.somleng.org/carrier/v1/accounts" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer EVubn8S5bIePaNlkRpeCpr4ZrjMSWlZU6MA4j6vW11A"
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": "5ca80701-0c76-4d05-957e-07bf683d2527",
"type": "account",
"attributes": {
"created_at": "2024-04-18T07:40:01Z",
"updated_at": "2024-04-18T07:40:01Z",
"name": "Telco Net",
"metadata": {
},
"status": "enabled",
"type": "carrier_managed",
"auth_token": "Wanhr7FwqIN0boXHZz7mFa6Pq7LB7OwIvahzVhp23mo",
"default_tts_voice": "Basic.Kal"
}
},
{
"id": "478b5a9e-79b2-43a4-a7d7-4210ef772dcc",
"type": "account",
"attributes": {
"created_at": "2024-04-18T07:40:01Z",
"updated_at": "2024-04-18T07:40:01Z",
"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=5ca80701-0c76-4d05-957e-07bf683d2527",
"next": null
}
}
Delete an account
Request
curl "https://api.somleng.org/carrier/v1/accounts/d42e1a21-a40c-4493-adcf-2e70a6c06b76" -d '' -X DELETE \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer sCeuCLk0QchZiZWOl1T7xa4zLIdpnHr1Nn_3QNfqYLM"
Endpoint
DELETE https://api.somleng.org/carrier/v1/accounts/:id
DELETE https://api.somleng.org/carrier/v1/accounts/d42e1a21-a40c-4493-adcf-2e70a6c06b76
Parameters
None known.
Response
204 No Content
Phone Numbers
Retrieve a phone number
Request
curl -g "https://api.somleng.org/carrier/v1/phone_numbers/1320f14b-af36-4dbb-8ed0-2ef246b859c6" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer 9uNXzE78rhYeRt5O8aFrrkJQWlK97PYXWAdCLBP_DNs"
Endpoint
GET https://api.somleng.org/carrier/v1/phone_numbers/:id
GET https://api.somleng.org/carrier/v1/phone_numbers/1320f14b-af36-4dbb-8ed0-2ef246b859c6
Parameters
None known.
Response
200 OK
{
"data": {
"id": "1320f14b-af36-4dbb-8ed0-2ef246b859c6",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345772",
"enabled": true
},
"relationships": {
}
}
}
List all phone numbers
Request
curl -g "https://api.somleng.org/carrier/v1/phone_numbers" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer qGzUzllEA5qkag2LtUup6GGzUOzuXM1IDN-fKMZDyLQ"
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": "31112b4d-ab27-49b1-999e-f2a7e634c3b2",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345774",
"enabled": true
},
"relationships": {
}
},
{
"id": "13c4c94b-69b9-4558-aad2-5a03defbd3bc",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345773",
"enabled": true
},
"relationships": {
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/phone_numbers?page%5Bbefore%5D=31112b4d-ab27-49b1-999e-f2a7e634c3b2",
"next": null
}
}
Assign an account to a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/136ea1d6-319c-4097-9e90-de8f0e1f3750" -d '{
"data": {
"type": "phone_number",
"id": "136ea1d6-319c-4097-9e90-de8f0e1f3750",
"relationships": {
"account": {
"data": {
"type": "account",
"id": "580c764f-35a9-472c-8e01-b77a3a0ba774"
}
}
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer mri0EN0S1o3-HkLgiskWk663C-w71zZA-oAfF3-8G-w"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_numbers/:id
PATCH https://api.somleng.org/carrier/v1/phone_numbers/136ea1d6-319c-4097-9e90-de8f0e1f3750
Parameters
{
"data": {
"type": "phone_number",
"id": "136ea1d6-319c-4097-9e90-de8f0e1f3750",
"relationships": {
"account": {
"data": {
"type": "account",
"id": "580c764f-35a9-472c-8e01-b77a3a0ba774"
}
}
}
}
}
Name | Description |
---|---|
data[relationships][account] | The id of the account to associate the phone number with. |
Response
200 OK
{
"data": {
"id": "136ea1d6-319c-4097-9e90-de8f0e1f3750",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345776",
"enabled": true
},
"relationships": {
"account": {
"data": {
"id": "580c764f-35a9-472c-8e01-b77a3a0ba774",
"type": "account"
}
}
}
}
}
Update a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/3971df96-cf87-410b-a0fa-cd9047d8119b" -d '{
"data": {
"type": "phone_number",
"id": "3971df96-cf87-410b-a0fa-cd9047d8119b",
"attributes": {
"enabled": false
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer Swp8rig2vIDzser9W71jd551n_u4tpiSkqJkk5LK2GA"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_numbers/:id
PATCH https://api.somleng.org/carrier/v1/phone_numbers/3971df96-cf87-410b-a0fa-cd9047d8119b
Parameters
{
"data": {
"type": "phone_number",
"id": "3971df96-cf87-410b-a0fa-cd9047d8119b",
"attributes": {
"enabled": false
}
}
}
Name | Description |
---|---|
data[attributes][enabled] | Set to false to disable the phone number or true to enable it. Disabled phone numbers cannot be used by accounts. |
Response
200 OK
{
"data": {
"id": "3971df96-cf87-410b-a0fa-cd9047d8119b",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345777",
"enabled": false
},
"relationships": {
}
}
}
Delete a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/47dcf3c5-2a8f-4193-91a8-26628c20bba2" -d '' -X DELETE \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer b3P3B6ZEWseezor-s1OdyOEvd8u5SWwkDMkdXlEOec4"
Endpoint
DELETE https://api.somleng.org/carrier/v1/phone_numbers/:id
DELETE https://api.somleng.org/carrier/v1/phone_numbers/47dcf3c5-2a8f-4193-91a8-26628c20bba2
Parameters
None known.
Response
204 No Content
Release a phone number
Releases a phone number by unassigning the account and removing any configuration.
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers/f6f11562-2a0d-411f-9783-16b0c561613a/release" -d '' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer hIoaKU3w6xDT4ZfICrVaxZMVDYp639WHwdgp8hsag-4"
Endpoint
PATCH https://api.somleng.org/carrier/v1/phone_numbers/:id/release
PATCH https://api.somleng.org/carrier/v1/phone_numbers/f6f11562-2a0d-411f-9783-16b0c561613a/release
Parameters
None known.
Response
200 OK
{
"data": {
"id": "f6f11562-2a0d-411f-9783-16b0c561613a",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "855972345779",
"enabled": true
},
"relationships": {
}
}
}
Create a phone number
Request
curl "https://api.somleng.org/carrier/v1/phone_numbers" -d '{
"data": {
"type": "phone_number",
"attributes": {
"number": "1294"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "15dc381e-03bb-49be-b687-7869f9046053"
}
}
}
}
}' -X POST \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer DvEGhwik7CiBTschckmdin2Pei_mSocxZUxQv1Ou8YQ"
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"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "15dc381e-03bb-49be-b687-7869f9046053"
}
}
}
}
}
Name | Description |
---|---|
data[attributes][number] required | Phone number or shortcode. |
data[attributes][enabled] | Set to false to disable this number. Disabled phone numbers cannot be used by accounts. Enabled by default. |
data[relationships][account] | The id of the account to associate the phone number with. |
Response
201 Created
{
"data": {
"id": "b749733e-b086-4f48-b11c-aef50354079d",
"type": "phone_number",
"attributes": {
"created_at": "2024-04-18T07:40:04Z",
"updated_at": "2024-04-18T07:40:04Z",
"number": "1294",
"enabled": true
},
"relationships": {
"account": {
"data": {
"id": "15dc381e-03bb-49be-b687-7869f9046053",
"type": "account"
}
}
}
}
}
Messages
Update a message
Request
curl "https://api.somleng.org/carrier/v1/messages/ec17a0fd-cd9b-401f-b076-4d99ba1e56a9" -d '{
"data": {
"id": "ec17a0fd-cd9b-401f-b076-4d99ba1e56a9",
"type": "message",
"attributes": {
"price": "-0.05",
"price_unit": "USD"
}
}
}' -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer gk2ffbnvcNOmo85V-yRKXQTnLgIoxd3uw1vGqBFN4VQ"
Endpoint
PATCH https://api.somleng.org/carrier/v1/messages/:id
PATCH https://api.somleng.org/carrier/v1/messages/ec17a0fd-cd9b-401f-b076-4d99ba1e56a9
Parameters
{
"data": {
"id": "ec17a0fd-cd9b-401f-b076-4d99ba1e56a9",
"type": "message",
"attributes": {
"price": "-0.05",
"price_unit": "USD"
}
}
}
Name | Description |
---|---|
data[attributes][price] | The charge for this message. |
data[attributes][price_unit] | The currency in which price is measured, in ISO 4127 format. (e.g., USD , EUR , JPY ). Always capitalized for messages. |
Response
200 OK
{
"data": {
"id": "ec17a0fd-cd9b-401f-b076-4d99ba1e56a9",
"type": "message",
"attributes": {
"created_at": "2024-04-18T07:40:05Z",
"updated_at": "2024-04-18T07:40:05Z",
"to": "+85512334667",
"from": "2442",
"price": "-0.05",
"price_unit": "USD",
"direction": "outbound-api",
"status": "sent",
"body": "Hello World"
},
"relationships": {
"account": {
"data": {
"id": "c7f8ad7a-d09c-4c11-965a-556a035afedc",
"type": "account"
}
}
}
}
}
List messages
Request
curl -g "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]=bf2a8955-3670-4521-9485-468f234851c9&filter[direction]=outbound-api" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer Ki4ml6keVukqYMecJ8e9FFzp1Usnyhh-Ie8OiDkzzR4"
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]=bf2a8955-3670-4521-9485-468f234851c9&filter[direction]=outbound-api
Parameters
filter: {"status"=>"sent", "from_date"=>"2021-11-01T00:00:00Z", "to_date"=>"2021-11-01T00:00:00Z", "account"=>"bf2a8955-3670-4521-9485-468f234851c9", "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": "ab649525-4014-4724-9c99-87f9534b5946",
"type": "message",
"attributes": {
"created_at": "2021-11-01T00:00:00Z",
"updated_at": "2024-04-18T07:40:05Z",
"to": "+85512334667",
"from": "2442",
"price": null,
"price_unit": null,
"direction": "outbound-api",
"status": "sent",
"body": "Hello World"
},
"relationships": {
"account": {
"data": {
"id": "bf2a8955-3670-4521-9485-468f234851c9",
"type": "account"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/messages?filter%5Baccount%5D=bf2a8955-3670-4521-9485-468f234851c9&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=ab649525-4014-4724-9c99-87f9534b5946",
"next": null
}
}
Retrieve a message
Request
curl -g "https://api.somleng.org/carrier/v1/messages/0b8591ba-57e3-48a7-9202-18f34305754b" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer AVRhgKA6UuLfysaKpaFLFejRxT0XV-uTqalnV7i6Ma8"
Endpoint
GET https://api.somleng.org/carrier/v1/messages/:id
GET https://api.somleng.org/carrier/v1/messages/0b8591ba-57e3-48a7-9202-18f34305754b
Parameters
None known.
Response
200 OK
{
"data": {
"id": "0b8591ba-57e3-48a7-9202-18f34305754b",
"type": "message",
"attributes": {
"created_at": "2024-04-18T07:40:05Z",
"updated_at": "2024-04-18T07:40:05Z",
"to": "+85512334667",
"from": "2442",
"price": null,
"price_unit": null,
"direction": "outbound-api",
"status": "accepted",
"body": "Hello World"
},
"relationships": {
"account": {
"data": {
"id": "f511623a-b51a-48df-9078-406c2522cac4",
"type": "account"
}
}
}
}
}
TTS Events
List all TTS events
Request
curl -g "https://api.somleng.org/carrier/v1/tts_events?filter[from_date]=2024-04-17&filter[account]=1b044d95-38eb-457d-b985-34cdec86413c&filter[phone_call]=bd75de95-4169-40e7-b48e-87ff47290f1a" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer sDYL4oSxJol8Q0JvZenu1LaWlvYtyp0eC7BL9zsR3u8"
Endpoint
GET https://api.somleng.org/carrier/v1/tts_events
GET https://api.somleng.org/carrier/v1/tts_events?filter[from_date]=2024-04-17&filter[account]=1b044d95-38eb-457d-b985-34cdec86413c&filter[phone_call]=bd75de95-4169-40e7-b48e-87ff47290f1a
Parameters
filter: {"from_date"=>"2024-04-17", "account"=>"1b044d95-38eb-457d-b985-34cdec86413c", "phone_call"=>"bd75de95-4169-40e7-b48e-87ff47290f1a"}
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": "9d974edf-28c3-49e5-8ce1-72113c02e040",
"type": "tts_event",
"attributes": {
"created_at": "2024-04-18T07:40:05Z",
"updated_at": "2024-04-18T07:40:05Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 200
},
"relationships": {
"account": {
"data": {
"id": "1b044d95-38eb-457d-b985-34cdec86413c",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "bd75de95-4169-40e7-b48e-87ff47290f1a",
"type": "phone_call"
}
}
}
},
{
"id": "c663436d-a265-4ef9-986b-8fa3a5284f3a",
"type": "tts_event",
"attributes": {
"created_at": "2024-04-18T07:40:05Z",
"updated_at": "2024-04-18T07:40:05Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 100
},
"relationships": {
"account": {
"data": {
"id": "1b044d95-38eb-457d-b985-34cdec86413c",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "bd75de95-4169-40e7-b48e-87ff47290f1a",
"type": "phone_call"
}
}
}
}
],
"links": {
"prev": "https://api.somleng.org/carrier/v1/tts_events?filter%5Baccount%5D=1b044d95-38eb-457d-b985-34cdec86413c&filter%5Bfrom_date%5D=2024-04-17&filter%5Bphone_call%5D=bd75de95-4169-40e7-b48e-87ff47290f1a&page%5Bbefore%5D=9d974edf-28c3-49e5-8ce1-72113c02e040",
"next": null
}
}
Retrieve a TTS Event
Request
curl -g "https://api.somleng.org/carrier/v1/tts_events/c21ea47c-67e5-4104-b0f7-122ad07bef46" -X GET \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer SosPW0v1YuY4XUm7XDzkJLd_wDRtnPwRFT4lFiMEiYI"
Endpoint
GET https://api.somleng.org/carrier/v1/tts_events/:id
GET https://api.somleng.org/carrier/v1/tts_events/c21ea47c-67e5-4104-b0f7-122ad07bef46
Parameters
None known.
Response
200 OK
{
"data": {
"id": "c21ea47c-67e5-4104-b0f7-122ad07bef46",
"type": "tts_event",
"attributes": {
"created_at": "2024-04-18T07:40:05Z",
"updated_at": "2024-04-18T07:40:05Z",
"voice": "Basic.Kal (Male, en-US)",
"characters": 100
},
"relationships": {
"account": {
"data": {
"id": "d91e12cd-56bd-41e4-a290-b6cb99954b71",
"type": "account"
}
},
"phone_call": {
"data": {
"id": "b7c7a3b4-0cb2-447e-afe1-5382fce29000",
"type": "phone_call"
}
}
}
}
}