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"
)

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"
        }
      }
    }
  }
}
cURL