NAV
cURL

Introduction

Dive into our full API Reference Documentation and seamlessly integrate Voice and SMS functionalities into your website or application. This API uses HTTP verbs and a RESTful endpoint structure. Your Account SID and Auth Token is used as the API Authorization framework. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

Make an HTTP Request

There are a lot of ways you can make an HTTP request to Somleng. You can use a Helper Library or SDK for your preferred programming language or you can make a raw HTTP request in your code by using a tool like Postman.

Credentials

All requests to Somleng need to be authenticated. Somleng using HTTP basic auth, which use the following username/password schemes:

Account SID and Auth Token

The account SID and auth token are the master keys to your account.

Username Password
AccountSid AuthToken

Store Your Somleng Credentials Securely

It's important to keep credentials such as your Somleng Account SID and Auth token secure by storing them in a way that prevents unauthorized access. One common method is to store them in environment variables which are then accessed from your app. This keeps them out of code and other places where credentials don't belong.

On the right is an example in Node.js ---->

const accountSid = process.env.SOMLENG_ACCOUNT_SID;
const authToken = process.env.SOMLENG_AUTH_TOKEN;
const client = require('somleng')(accountSid, authToken);

// Make API calls here...

Helper Libraries

The following is a list of officially supported helper libraries for Somleng. Please refer to the documentation in each library for more details.

Demo Applications

The following is a list of demo applications which you can use to get started with Somleng.

Accounts

1. Fetch an account

Returns a representation of an account, including the properties above.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6" \
    -u 373b8f4c-2a69-4fd3-bc79-2644886199c6:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:Sid

GET https://api.somleng.org/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6

Parameters

Name Description
Sid Path Parameter: The Account Sid that uniquely identifies the account to fetch.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "373b8f4c-2a69-4fd3-bc79-2644886199c6",
  "date_created": "Mon, 13 May 2024 11:23:44 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:44 -0000",
  "auth_token": "s00wB-E4gt-89IDVwLalEjC7udytGitMn_BqmLJ9bwQ",
  "friendly_name": "Rocket Rides",
  "owner_account_sid": "373b8f4c-2a69-4fd3-bc79-2644886199c6",
  "status": "active",
  "type": "Full",
  "uri": "/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6",
  "subresource_uris": {
    "calls": "/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6/Calls",
    "messages": "/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6/Messages",
    "recordings": "/2010-04-01/Accounts/373b8f4c-2a69-4fd3-bc79-2644886199c6/Recordings"
  }
}

Available Phone Numbers

1. List the available Local phone numbers for a specific country

This API lets you search for Local phone numbers that are available for you to purchase.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/a5c4742c-7a3c-4f15-ae14-7c2771ac79a3/AvailablePhoneNumbers/CA/Local" \
    -u a5c4742c-7a3c-4f15-ae14-7c2771ac79a3:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type

GET https://api.somleng.org/2010-04-01/Accounts/a5c4742c-7a3c-4f15-ae14-7c2771ac79a3/AvailablePhoneNumbers/CA/Local

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the AvailablePhoneNumber resources.
CountryCode Path Parameter: The ISO-3166-1 country code of the country from which to read phone numbers.
Type Path Parameter: Type of phone numbers to read. One of ShortCode, Local, Mobile, TollFree.
AreaCode Query Parameter: The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Response


200 OK

{
  "available_phone_numbers": [
    {
      "friendly_name": "+1 (251) 309-5500",
      "phone_number": "+12513095500",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "CA",
      "address_requirements": "none",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/a5c4742c-7a3c-4f15-ae14-7c2771ac79a3/AvailablePhoneNumbers/CA/Local",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/a5c4742c-7a3c-4f15-ae14-7c2771ac79a3/AvailablePhoneNumbers/CA/Local?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/a5c4742c-7a3c-4f15-ae14-7c2771ac79a3/AvailablePhoneNumbers/CA/Local?Page=0&PageToken=PB97cf1f7a-f643-4f52-82a5-2986b6a65596",
  "next_page_uri": null
}

2. Find available local phone numbers by area code

Find available Local phone numbers in Canada in the 201 area code.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/7a01a164-5149-4297-b62c-ab45f226014a/AvailablePhoneNumbers/CA/Local?AreaCode=201" \
    -u 7a01a164-5149-4297-b62c-ab45f226014a:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type

GET https://api.somleng.org/2010-04-01/Accounts/7a01a164-5149-4297-b62c-ab45f226014a/AvailablePhoneNumbers/CA/Local?AreaCode=201

Parameters

AreaCode: 201
Name Description
AccountSid Path Parameter: The SID of the Account requesting the AvailablePhoneNumber resources.
CountryCode Path Parameter: The ISO-3166-1 country code of the country from which to read phone numbers.
Type Path Parameter: Type of phone numbers to read. One of ShortCode, Local, Mobile, TollFree.
AreaCode Query Parameter: The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Response


200 OK

{
  "available_phone_numbers": [
    {
      "friendly_name": "+1 (201) 309-5500",
      "phone_number": "+12013095500",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "CA",
      "address_requirements": "none",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/7a01a164-5149-4297-b62c-ab45f226014a/AvailablePhoneNumbers/CA/Local?AreaCode=201",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/7a01a164-5149-4297-b62c-ab45f226014a/AvailablePhoneNumbers/CA/Local?AreaCode=201&Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/7a01a164-5149-4297-b62c-ab45f226014a/AvailablePhoneNumbers/CA/Local?AreaCode=201&Page=0&PageToken=PBefddf954-d123-4292-82bc-923194607c99",
  "next_page_uri": null
}

3. List the available Mobile phone numbers for a specific country

This API lets you search for Mobile phone numbers that are available for you to purchase.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/f0e80d6f-412c-482f-8094-000489154514/AvailablePhoneNumbers/CA/Mobile" \
    -u f0e80d6f-412c-482f-8094-000489154514:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type

GET https://api.somleng.org/2010-04-01/Accounts/f0e80d6f-412c-482f-8094-000489154514/AvailablePhoneNumbers/CA/Mobile

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the AvailablePhoneNumber resources.
CountryCode Path Parameter: The ISO-3166-1 country code of the country from which to read phone numbers.
Type Path Parameter: Type of phone numbers to read. One of ShortCode, Local, Mobile, TollFree.
AreaCode Query Parameter: The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Response


200 OK

{
  "available_phone_numbers": [
    {
      "friendly_name": "+1 (251) 309-5500",
      "phone_number": "+12513095500",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "CA",
      "address_requirements": "none",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/f0e80d6f-412c-482f-8094-000489154514/AvailablePhoneNumbers/CA/Mobile",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/f0e80d6f-412c-482f-8094-000489154514/AvailablePhoneNumbers/CA/Mobile?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/f0e80d6f-412c-482f-8094-000489154514/AvailablePhoneNumbers/CA/Mobile?Page=0&PageToken=PBc27cb98b-c4c8-406e-a00b-29b950bf0fb4",
  "next_page_uri": null
}

4. List the available Toll Free phone numbers for a specific country

This API lets you search for TollFree phone numbers that are available for you to purchase.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/0cfb5e46-48d4-4c98-a125-6efa93f613c0/AvailablePhoneNumbers/CA/TollFree" \
    -u 0cfb5e46-48d4-4c98-a125-6efa93f613c0:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type

GET https://api.somleng.org/2010-04-01/Accounts/0cfb5e46-48d4-4c98-a125-6efa93f613c0/AvailablePhoneNumbers/CA/TollFree

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the AvailablePhoneNumber resources.
CountryCode Path Parameter: The ISO-3166-1 country code of the country from which to read phone numbers.
Type Path Parameter: Type of phone numbers to read. One of ShortCode, Local, Mobile, TollFree.
AreaCode Query Parameter: The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Response


200 OK

{
  "available_phone_numbers": [
    {
      "friendly_name": "+1 (877) 731-8091",
      "phone_number": "+18777318091",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "CA",
      "address_requirements": "none",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/0cfb5e46-48d4-4c98-a125-6efa93f613c0/AvailablePhoneNumbers/CA/TollFree",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/0cfb5e46-48d4-4c98-a125-6efa93f613c0/AvailablePhoneNumbers/CA/TollFree?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/0cfb5e46-48d4-4c98-a125-6efa93f613c0/AvailablePhoneNumbers/CA/TollFree?Page=0&PageToken=PB9e545722-190a-4741-a05e-c271efb99a81",
  "next_page_uri": null
}

5. List the available Short Code numbers for a specific country

This API lets you search for Short Code phone numbers that are available for you to purchase.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/fc09cf21-c144-459a-94f9-d1aa20b7e800/AvailablePhoneNumbers/CA/ShortCode" \
    -u fc09cf21-c144-459a-94f9-d1aa20b7e800:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type

GET https://api.somleng.org/2010-04-01/Accounts/fc09cf21-c144-459a-94f9-d1aa20b7e800/AvailablePhoneNumbers/CA/ShortCode

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the AvailablePhoneNumber resources.
CountryCode Path Parameter: The ISO-3166-1 country code of the country from which to read phone numbers.
Type Path Parameter: Type of phone numbers to read. One of ShortCode, Local, Mobile, TollFree.
AreaCode Query Parameter: The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Response


200 OK

{
  "available_phone_numbers": [
    {
      "friendly_name": "1294",
      "phone_number": "1294",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "CA",
      "address_requirements": "none",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/fc09cf21-c144-459a-94f9-d1aa20b7e800/AvailablePhoneNumbers/CA/ShortCode",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/fc09cf21-c144-459a-94f9-d1aa20b7e800/AvailablePhoneNumbers/CA/ShortCode?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/fc09cf21-c144-459a-94f9-d1aa20b7e800/AvailablePhoneNumbers/CA/ShortCode?Page=0&PageToken=PBb33544e4-54e4-495d-bc91-6f13a2eda66f",
  "next_page_uri": null
}

6. Read a list of countries

You can query the AvailablePhoneNumbers to get a list of subresources available for your account by ISO Country. This API gets the subresources available for all supported countries.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers" \
    -u 018f347c-19ab-44f9-98b8-77d9f660439b:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers

GET https://api.somleng.org/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the available phone number Country resources.

Response


200 OK

{
  "countries": [
    {
      "country_code": "CA",
      "country": "Canada",
      "uri": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/CA",
      "beta": false,
      "subresource_uris": {
        "short_code": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/CA/ShortCode",
        "local": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/CA/Local",
        "mobile": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/CA/Mobile",
        "toll_free": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/CA/TollFree"
      }
    },
    {
      "country_code": "KH",
      "country": "Cambodia",
      "uri": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/KH",
      "beta": false,
      "subresource_uris": {
        "short_code": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/KH/ShortCode",
        "local": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/KH/Local",
        "mobile": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/KH/Mobile",
        "toll_free": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers/KH/TollFree"
      }
    }
  ],
  "uri": "/2010-04-01/Accounts/018f347c-19ab-44f9-98b8-77d9f660439b/AvailablePhoneNumbers"
}

7. Fetch a specific country

Fetch the subresources available for a specific country. The subresources will contain a list of endpoints which can be used to fetch available phone numbers for that country.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA" \
    -u a0601f03-837b-4c6b-979c-8447fe1610d5:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode

GET https://api.somleng.org/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account requesting the available phone number Country resource.
CountryCode Path Parameter: The ISO-3166-1 country code of the country to fetch available phone number information about.

Response


200 OK

{
  "country_code": "CA",
  "country": "Canada",
  "uri": "/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA",
  "beta": false,
  "subresource_uris": {
    "short_code": "/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA/ShortCode",
    "local": "/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA/Local",
    "mobile": "/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA/Mobile",
    "toll_free": "/2010-04-01/Accounts/a0601f03-837b-4c6b-979c-8447fe1610d5/AvailablePhoneNumbers/CA/TollFree"
  }
}

Incoming Phone Numbers

An IncomingPhoneNumber resource represents a phone number provisioned to your account. The IncomingPhoneNumbers list resource represents an account's phone numbers. You can POST to the list resource to provision a new number. To find a new number to provision use the subresources of the [Available Phone Numbers] resource.

1. Provision a Phone Number

You can POST to this API to provision a new phone number. To find a new number to provision use the Available Phone Numbers API.

You will be charged when you provision the number, and the number will appear on the Active Numbers page in the console.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/1107615f-b7fb-4b90-adc9-3ba33bbae053/IncomingPhoneNumbers" \
    -u 1107615f-b7fb-4b90-adc9-3ba33bbae053:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "PhoneNumber=+12513095500"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers

POST https://api.somleng.org/2010-04-01/Accounts/1107615f-b7fb-4b90-adc9-3ba33bbae053/IncomingPhoneNumbers

Parameters

{
  "PhoneNumber": "+12513095500"
}
Name Description
AccountSid Path Parameter: The SID of the Account that will create the resource.
PhoneNumber required Request Body Parameter: The phone number to purchase specified in E.164 format.
FriendlyName Request Body Parameter: A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.
SmsUrl Request Body Parameter: The URL we should call when the new phone number receives an incoming SMS message.
SmsMethod Request Body Parameter: The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.
VoiceUrl Request Body Parameter: The URL that we should call to answer a call to the new phone number.
VoiceMethod Request Body Parameter: The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application.
StatusCallbackMethod Request Body Parameter: The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "2cef259b-ada4-420f-88f3-eb16ff29aa17",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "1107615f-b7fb-4b90-adc9-3ba33bbae053",
  "address_requirements": "none",
  "address_sid": null,
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": false,
    "fax": false
  },
  "emergency_status": "Inactive",
  "emergency_address_sid": null,
  "emergency_address_status": "unregistered",
  "friendly_name": "+1 (251) 309-5500",
  "identity_sid": null,
  "origin": "hosted",
  "phone_number": "+12513095500",
  "sms_application_sid": null,
  "sms_fallback_method": "POST",
  "sms_fallback_url": null,
  "sms_method": "POST",
  "sms_url": null,
  "status_callback": null,
  "status_callback_method": "POST",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/1107615f-b7fb-4b90-adc9-3ba33bbae053/IncomingPhoneNumbers/2cef259b-ada4-420f-88f3-eb16ff29aa17",
  "voice_application_sid": null,
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "POST",
  "voice_fallback_url": null,
  "voice_method": "POST",
  "voice_url": null,
  "bundle_sid": null,
  "voice_receive_mode": "voice",
  "status": "in-use"
}

2. Provision a Phone Number with a Voice URL

You will receive a HTTP request to this URL when a call comes in to your phone number.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/6230a480-153b-4466-880d-c2c5f2033c4d/IncomingPhoneNumbers" \
    -u 6230a480-153b-4466-880d-c2c5f2033c4d:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "PhoneNumber=+12513095500" \
    --data-urlencode "VoiceUrl=https://www.your-voice-url.com/example"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers

POST https://api.somleng.org/2010-04-01/Accounts/6230a480-153b-4466-880d-c2c5f2033c4d/IncomingPhoneNumbers

Parameters

{
  "PhoneNumber": "+12513095500",
  "VoiceUrl": "https://www.your-voice-url.com/example"
}
Name Description
AccountSid Path Parameter: The SID of the Account that will create the resource.
PhoneNumber required Request Body Parameter: The phone number to purchase specified in E.164 format.
FriendlyName Request Body Parameter: A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.
SmsUrl Request Body Parameter: The URL we should call when the new phone number receives an incoming SMS message.
SmsMethod Request Body Parameter: The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.
VoiceUrl Request Body Parameter: The URL that we should call to answer a call to the new phone number.
VoiceMethod Request Body Parameter: The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application.
StatusCallbackMethod Request Body Parameter: The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "c5db1a6b-dcec-4d8b-876a-af59b86e049c",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "6230a480-153b-4466-880d-c2c5f2033c4d",
  "address_requirements": "none",
  "address_sid": null,
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": false,
    "fax": false
  },
  "emergency_status": "Inactive",
  "emergency_address_sid": null,
  "emergency_address_status": "unregistered",
  "friendly_name": "+1 (251) 309-5500",
  "identity_sid": null,
  "origin": "hosted",
  "phone_number": "+12513095500",
  "sms_application_sid": null,
  "sms_fallback_method": "POST",
  "sms_fallback_url": null,
  "sms_method": "POST",
  "sms_url": null,
  "status_callback": null,
  "status_callback_method": "POST",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/6230a480-153b-4466-880d-c2c5f2033c4d/IncomingPhoneNumbers/c5db1a6b-dcec-4d8b-876a-af59b86e049c",
  "voice_application_sid": null,
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "POST",
  "voice_fallback_url": null,
  "voice_method": "POST",
  "voice_url": "https://www.your-voice-url.com/example",
  "bundle_sid": null,
  "voice_receive_mode": "voice",
  "status": "in-use"
}

3. Provision a Phone Number with an SMS URL

You will receive a HTTP request to this URL when an SMS is sent to your phone number.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/c741db34-2601-4df1-b4d1-a775e99faa1f/IncomingPhoneNumbers" \
    -u c741db34-2601-4df1-b4d1-a775e99faa1f:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "PhoneNumber=+12513095500" \
    --data-urlencode "SmsUrl=https://www.your-sms-url.com/example"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers

POST https://api.somleng.org/2010-04-01/Accounts/c741db34-2601-4df1-b4d1-a775e99faa1f/IncomingPhoneNumbers

Parameters

{
  "PhoneNumber": "+12513095500",
  "SmsUrl": "https://www.your-sms-url.com/example"
}
Name Description
AccountSid Path Parameter: The SID of the Account that will create the resource.
PhoneNumber required Request Body Parameter: The phone number to purchase specified in E.164 format.
FriendlyName Request Body Parameter: A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.
SmsUrl Request Body Parameter: The URL we should call when the new phone number receives an incoming SMS message.
SmsMethod Request Body Parameter: The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.
VoiceUrl Request Body Parameter: The URL that we should call to answer a call to the new phone number.
VoiceMethod Request Body Parameter: The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application.
StatusCallbackMethod Request Body Parameter: The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "00085126-33a5-4645-8265-ee397aaaff6e",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "c741db34-2601-4df1-b4d1-a775e99faa1f",
  "address_requirements": "none",
  "address_sid": null,
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": false,
    "fax": false
  },
  "emergency_status": "Inactive",
  "emergency_address_sid": null,
  "emergency_address_status": "unregistered",
  "friendly_name": "+1 (251) 309-5500",
  "identity_sid": null,
  "origin": "hosted",
  "phone_number": "+12513095500",
  "sms_application_sid": null,
  "sms_fallback_method": "POST",
  "sms_fallback_url": null,
  "sms_method": "POST",
  "sms_url": "https://www.your-sms-url.com/example",
  "status_callback": null,
  "status_callback_method": "POST",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/c741db34-2601-4df1-b4d1-a775e99faa1f/IncomingPhoneNumbers/00085126-33a5-4645-8265-ee397aaaff6e",
  "voice_application_sid": null,
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "POST",
  "voice_fallback_url": null,
  "voice_method": "POST",
  "voice_url": null,
  "bundle_sid": null,
  "voice_receive_mode": "voice",
  "status": "in-use"
}

4. Fetch an IncomingPhoneNumber resource

Fetch an IncomingPhoneNumber

Request

curl "https://api.somleng.org/2010-04-01/Accounts/3eb59310-e5c0-4864-a6f1-af8e4b8174eb/IncomingPhoneNumbers/a0484d3a-2c20-4249-ac31-dc1a4b27ddc9" \
    -u 3eb59310-e5c0-4864-a6f1-af8e4b8174eb:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers/:Sid

GET https://api.somleng.org/2010-04-01/Accounts/3eb59310-e5c0-4864-a6f1-af8e4b8174eb/IncomingPhoneNumbers/a0484d3a-2c20-4249-ac31-dc1a4b27ddc9

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the IncomingPhoneNumber resource to fetch.
Sid Path Parameter: The SID of the IncomingPhoneNumber resource to be fetched.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "a0484d3a-2c20-4249-ac31-dc1a4b27ddc9",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "3eb59310-e5c0-4864-a6f1-af8e4b8174eb",
  "address_requirements": "none",
  "address_sid": null,
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": false,
    "fax": false
  },
  "emergency_status": "Inactive",
  "emergency_address_sid": null,
  "emergency_address_status": "unregistered",
  "friendly_name": "+1 (251) 309-5500",
  "identity_sid": null,
  "origin": "hosted",
  "phone_number": "+12513095500",
  "sms_application_sid": null,
  "sms_fallback_method": "POST",
  "sms_fallback_url": null,
  "sms_method": "POST",
  "sms_url": null,
  "status_callback": null,
  "status_callback_method": "POST",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/3eb59310-e5c0-4864-a6f1-af8e4b8174eb/IncomingPhoneNumbers/a0484d3a-2c20-4249-ac31-dc1a4b27ddc9",
  "voice_application_sid": null,
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "POST",
  "voice_fallback_url": null,
  "voice_method": "POST",
  "voice_url": null,
  "bundle_sid": null,
  "voice_receive_mode": "voice",
  "status": "in-use"
}

5. Read a list of Incoming Phone Numbers

List all IncomingPhoneNumber resources for your account.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers?PhoneNumber=%2B12513095500" \
    -u 25c17a87-2023-40d1-a99e-50f6c33a14eb:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers

GET https://api.somleng.org/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers?PhoneNumber=%2B12513095500

Parameters

PhoneNumber: +12513095500
Name Description
AccountSid Path Parameter: The SID of the Account that created the IncomingPhoneNumber resource to read.
PhoneNumber Query Parameter: The phone number of the IncomingPhoneNumber resources to read.

Response


200 OK

{
  "incoming_phone_numbers": [
    {
      "api_version": "2010-04-01",
      "sid": "caee72c4-b364-4520-8fea-0bf2974fc417",
      "date_created": "Mon, 13 May 2024 11:23:59 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
      "account_sid": "25c17a87-2023-40d1-a99e-50f6c33a14eb",
      "address_requirements": "none",
      "address_sid": null,
      "beta": false,
      "capabilities": {
        "voice": true,
        "sms": true,
        "mms": false,
        "fax": false
      },
      "emergency_status": "Inactive",
      "emergency_address_sid": null,
      "emergency_address_status": "unregistered",
      "friendly_name": "+1 (251) 309-5500",
      "identity_sid": null,
      "origin": "hosted",
      "phone_number": "+12513095500",
      "sms_application_sid": null,
      "sms_fallback_method": "POST",
      "sms_fallback_url": null,
      "sms_method": "POST",
      "sms_url": null,
      "status_callback": null,
      "status_callback_method": "POST",
      "trunk_sid": null,
      "uri": "/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers/caee72c4-b364-4520-8fea-0bf2974fc417",
      "voice_application_sid": null,
      "voice_caller_id_lookup": false,
      "voice_fallback_method": "POST",
      "voice_fallback_url": null,
      "voice_method": "POST",
      "voice_url": null,
      "bundle_sid": null,
      "voice_receive_mode": "voice",
      "status": "in-use"
    }
  ],
  "uri": "/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers?PhoneNumber=%2B12513095500",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers?Page=0&PhoneNumber=%2B12513095500",
  "previous_page_uri": "/2010-04-01/Accounts/25c17a87-2023-40d1-a99e-50f6c33a14eb/IncomingPhoneNumbers?Page=0&PageToken=PBcaee72c4-b364-4520-8fea-0bf2974fc417&PhoneNumber=%2B12513095500",
  "next_page_uri": null
}

6. Update IncomingPhoneNumber to use a new Voice URL

You will receive a HTTP request to this URL when a call comes in to your phone number.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/9d50d47e-e0d0-46b6-84ba-44e16b59f8bd/IncomingPhoneNumbers/d8da0508-0ec2-446b-8cb1-b3250a24cee8" \
    -u 9d50d47e-e0d0-46b6-84ba-44e16b59f8bd:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "VoiceUrl=https://www.your-voice-url.com/example"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/9d50d47e-e0d0-46b6-84ba-44e16b59f8bd/IncomingPhoneNumbers/d8da0508-0ec2-446b-8cb1-b3250a24cee8

Parameters

{
  "VoiceUrl": "https://www.your-voice-url.com/example"
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the IncomingPhoneNumber resource to update.
Sid Path Parameter: The SID of the IncomingPhoneNumber resource to update.
FriendlyName Request Body Parameter: A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.
SmsUrl Request Body Parameter: The URL we should call when the new phone number receives an incoming SMS message.
SmsMethod Request Body Parameter: The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.
VoiceUrl Request Body Parameter: The URL that we should call to answer a call to the new phone number.
VoiceMethod Request Body Parameter: The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application.
StatusCallbackMethod Request Body Parameter: The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "d8da0508-0ec2-446b-8cb1-b3250a24cee8",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "9d50d47e-e0d0-46b6-84ba-44e16b59f8bd",
  "address_requirements": "none",
  "address_sid": null,
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": false,
    "fax": false
  },
  "emergency_status": "Inactive",
  "emergency_address_sid": null,
  "emergency_address_status": "unregistered",
  "friendly_name": "+855 97 234 5779",
  "identity_sid": null,
  "origin": "hosted",
  "phone_number": "+855972345779",
  "sms_application_sid": null,
  "sms_fallback_method": "POST",
  "sms_fallback_url": null,
  "sms_method": "POST",
  "sms_url": null,
  "status_callback": null,
  "status_callback_method": "POST",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/9d50d47e-e0d0-46b6-84ba-44e16b59f8bd/IncomingPhoneNumbers/d8da0508-0ec2-446b-8cb1-b3250a24cee8",
  "voice_application_sid": null,
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "POST",
  "voice_fallback_url": null,
  "voice_method": "POST",
  "voice_url": "https://www.your-voice-url.com/example",
  "bundle_sid": null,
  "voice_receive_mode": "voice",
  "status": "in-use"
}

7. Delete an IncomingPhoneNumber

Release this phone number from your account. We will no longer answer calls to this number, and you will stop being billed the monthly phone number fee. The phone number will be recycled and potentially given to another customer, so use with care.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/ce5ac514-8885-43c0-8896-2ecb69711014/IncomingPhoneNumbers/cd065c56-d20d-43d8-8a76-2b8021a62627" -d '' -X DELETE \
    -u ce5ac514-8885-43c0-8896-2ecb69711014:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded"

Endpoint

DELETE https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers/:Sid

DELETE https://api.somleng.org/2010-04-01/Accounts/ce5ac514-8885-43c0-8896-2ecb69711014/IncomingPhoneNumbers/cd065c56-d20d-43d8-8a76-2b8021a62627

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the IncomingPhoneNumber resource to delete.
Sid Path Parameter: The SID of the IncomingPhoneNumber resource to delete.

Response


204 No Content

Messages

1. Send an SMS Message

The example below shows how to create a Message resource with an SMS recipient. Sending this POST request creates text message from +855716788999 (a phone number belonging to the Account sending the request) to +855716788123. The content of the text message is Hello World.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/7ab7b3a0-fb2f-461c-b06d-7caf7f424c2f/Messages" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 7ab7b3a0-fb2f-461c-b06d-7caf7f424c2f:AuthToken \
    --data-urlencode "To=+855716788123" \
    --data-urlencode "From=+855716788999" \
    --data-urlencode "Body=Hello World"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages

POST https://api.somleng.org/2010-04-01/Accounts/7ab7b3a0-fb2f-461c-b06d-7caf7f424c2f/Messages

Parameters

{
  "To": "+855716788123",
  "From": "+855716788999",
  "Body": "Hello World"
}
Name Description
AccountSid Path Parameter: The SID of the Account creating the Message resource.
From Request Body Parameter: A phone number in E.164 format. Required if MessagingServiceSid is not passed
MessagingServiceSid Request Body Parameter: The SID of the Messaging Service you want to associate with the Message. Set this parameter to use the Messaging Service Settings you have configured and leave the From parameter empty. When only this parameter is set, we will select the From phone number for delivery.
Body required Request Body Parameter: The text of the message you want to send. Can be up to 1,600 characters in length.
To required Request Body Parameter: The destination phone number in E.164 format
StatusCallback Request Body Parameter: The URL we should call to send status information to your application. If specified, we POST these message status changes to the URL: queued, failed, sent, delivered, or undelivered. Somleng will POST its standard request parameters as well as some additional parameters including MessageSid, MessageStatus, and ErrorCode. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when calling the status_callback URL. Can be: GET or POST and the default is POST.
ValidityPeriod Request Body Parameter: How long in seconds the message can remain in our outgoing message queue. After this period elapses, the message fails and we call your status callback. Can be between 1 and the default value of 14,400 seconds. After a message has been accepted by a carrier, however, we cannot guarantee that the message will not be queued after this period. We recommend that this value be at least 5 seconds.
SmartEncoded Request Body Parameter: Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.
ScheduleType Request Body Parameter: Indicates your intent to schedule a message. Pass the value fixed to schedule a message at a fixed time.
SendAt Request Body Parameter: The time that we will send the message. Must be in ISO 8601 format.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "b702fe5a-bc97-4f18-bd87-04340f6db83f",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "7ab7b3a0-fb2f-461c-b06d-7caf7f424c2f",
  "body": "Hello World",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "+855716788999",
  "messaging_service_sid": null,
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "queued",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+855716788123",
  "uri": "/2010-04-01/Accounts/7ab7b3a0-fb2f-461c-b06d-7caf7f424c2f/Messages/b702fe5a-bc97-4f18-bd87-04340f6db83f"
}

2. Send a message with a Messaging Service

When sending a message with a Messaging Service, you must provide a recipient via the To parameter and content via the Body parameter. In addition, you must provide the MessagingServiceSid.

If you provide a MessagingServiceSid and no From parameter, the optimal From value wil be determined from your Sender Pool. In this case, the Message resource's initial Status value is accepted.

Optionally, you can provide aMessagingServiceSid and a From parameter. The From parameter must be a sender from your Messaging Service's Sender Pool. In this case, the Message resource's initial Status value is queued.

With Messaging Services, you can also schedule messages to be sent in the future.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/a996feda-2632-4d9a-996e-425a23b035c8/Messages" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u a996feda-2632-4d9a-996e-425a23b035c8:AuthToken \
    --data-urlencode "To=+855716788123" \
    --data-urlencode "MessagingServiceSid=a9348e25-e7e9-4be7-a397-8d457c31c032" \
    --data-urlencode "Body=Hello World"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages

POST https://api.somleng.org/2010-04-01/Accounts/a996feda-2632-4d9a-996e-425a23b035c8/Messages

Parameters

{
  "To": "+855716788123",
  "MessagingServiceSid": "a9348e25-e7e9-4be7-a397-8d457c31c032",
  "Body": "Hello World"
}
Name Description
AccountSid Path Parameter: The SID of the Account creating the Message resource.
From Request Body Parameter: A phone number in E.164 format. Required if MessagingServiceSid is not passed
MessagingServiceSid Request Body Parameter: The SID of the Messaging Service you want to associate with the Message. Set this parameter to use the Messaging Service Settings you have configured and leave the From parameter empty. When only this parameter is set, we will select the From phone number for delivery.
Body required Request Body Parameter: The text of the message you want to send. Can be up to 1,600 characters in length.
To required Request Body Parameter: The destination phone number in E.164 format
StatusCallback Request Body Parameter: The URL we should call to send status information to your application. If specified, we POST these message status changes to the URL: queued, failed, sent, delivered, or undelivered. Somleng will POST its standard request parameters as well as some additional parameters including MessageSid, MessageStatus, and ErrorCode. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when calling the status_callback URL. Can be: GET or POST and the default is POST.
ValidityPeriod Request Body Parameter: How long in seconds the message can remain in our outgoing message queue. After this period elapses, the message fails and we call your status callback. Can be between 1 and the default value of 14,400 seconds. After a message has been accepted by a carrier, however, we cannot guarantee that the message will not be queued after this period. We recommend that this value be at least 5 seconds.
SmartEncoded Request Body Parameter: Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.
ScheduleType Request Body Parameter: Indicates your intent to schedule a message. Pass the value fixed to schedule a message at a fixed time.
SendAt Request Body Parameter: The time that we will send the message. Must be in ISO 8601 format.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "4075aa8f-755c-41ab-9691-08a6a0e90f83",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "a996feda-2632-4d9a-996e-425a23b035c8",
  "body": "Hello World",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": null,
  "messaging_service_sid": "a9348e25-e7e9-4be7-a397-8d457c31c032",
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "accepted",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+855716788123",
  "uri": "/2010-04-01/Accounts/a996feda-2632-4d9a-996e-425a23b035c8/Messages/4075aa8f-755c-41ab-9691-08a6a0e90f83"
}

3. Schedule a Message

The example below shows how to schedule a Message to be sent in the future.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/a41f4970-5f92-42bd-bfdf-7d96e0e56eb9/Messages" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u a41f4970-5f92-42bd-bfdf-7d96e0e56eb9:AuthToken \
    --data-urlencode "To=+855716788123" \
    --data-urlencode "Body=Hello World" \
    --data-urlencode "SendAt=2024-05-18T11:23:51Z" \
    --data-urlencode "ScheduleType=fixed" \
    --data-urlencode "MessagingServiceSid=22c1ba04-af25-4cba-b1ac-7aaafe6d23bb"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages

POST https://api.somleng.org/2010-04-01/Accounts/a41f4970-5f92-42bd-bfdf-7d96e0e56eb9/Messages

Parameters

{
  "To": "+855716788123",
  "Body": "Hello World",
  "SendAt": "2024-05-18T11:23:51Z",
  "ScheduleType": "fixed",
  "MessagingServiceSid": "22c1ba04-af25-4cba-b1ac-7aaafe6d23bb"
}
Name Description
AccountSid Path Parameter: The SID of the Account creating the Message resource.
From Request Body Parameter: A phone number in E.164 format. Required if MessagingServiceSid is not passed
MessagingServiceSid Request Body Parameter: The SID of the Messaging Service you want to associate with the Message. Set this parameter to use the Messaging Service Settings you have configured and leave the From parameter empty. When only this parameter is set, we will select the From phone number for delivery.
Body required Request Body Parameter: The text of the message you want to send. Can be up to 1,600 characters in length.
To required Request Body Parameter: The destination phone number in E.164 format
StatusCallback Request Body Parameter: The URL we should call to send status information to your application. If specified, we POST these message status changes to the URL: queued, failed, sent, delivered, or undelivered. Somleng will POST its standard request parameters as well as some additional parameters including MessageSid, MessageStatus, and ErrorCode. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when calling the status_callback URL. Can be: GET or POST and the default is POST.
ValidityPeriod Request Body Parameter: How long in seconds the message can remain in our outgoing message queue. After this period elapses, the message fails and we call your status callback. Can be between 1 and the default value of 14,400 seconds. After a message has been accepted by a carrier, however, we cannot guarantee that the message will not be queued after this period. We recommend that this value be at least 5 seconds.
SmartEncoded Request Body Parameter: Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.
ScheduleType Request Body Parameter: Indicates your intent to schedule a message. Pass the value fixed to schedule a message at a fixed time.
SendAt Request Body Parameter: The time that we will send the message. Must be in ISO 8601 format.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "82ff76e5-ca2f-4f31-b4e9-55181434ae74",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "a41f4970-5f92-42bd-bfdf-7d96e0e56eb9",
  "body": "Hello World",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": null,
  "messaging_service_sid": "22c1ba04-af25-4cba-b1ac-7aaafe6d23bb",
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "scheduled",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+855716788123",
  "uri": "/2010-04-01/Accounts/a41f4970-5f92-42bd-bfdf-7d96e0e56eb9/Messages/82ff76e5-ca2f-4f31-b4e9-55181434ae74"
}

4. Fetch a Message

Returns a single Message resource specified by the provided Message SID.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/b2bd86c9-3115-42cd-ac67-eb7e89e0b69d/Messages/28d35956-d84a-44d7-b6ac-a49af9dd9331" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u b2bd86c9-3115-42cd-ac67-eb7e89e0b69d:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid

GET https://api.somleng.org/2010-04-01/Accounts/b2bd86c9-3115-42cd-ac67-eb7e89e0b69d/Messages/28d35956-d84a-44d7-b6ac-a49af9dd9331

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account associated with the Message resource.
Sid Path Parameter: The SID of the Message resource to be fetched.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "28d35956-d84a-44d7-b6ac-a49af9dd9331",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "b2bd86c9-3115-42cd-ac67-eb7e89e0b69d",
  "body": "Hello World",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "2442",
  "messaging_service_sid": null,
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "accepted",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+85512334667",
  "uri": "/2010-04-01/Accounts/b2bd86c9-3115-42cd-ac67-eb7e89e0b69d/Messages/28d35956-d84a-44d7-b6ac-a49af9dd9331"
}

5. List all messages

Returns a list of all Message resources associated with your Account

Request

curl "https://api.somleng.org/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 31d87e6f-229e-4696-9ab7-c85eab8ebee8:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages

GET https://api.somleng.org/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account associated with the Message resources.

Response


200 OK

{
  "messages": [
    {
      "api_version": "2010-04-01",
      "sid": "eed93f0c-3e9a-427f-b867-dedeac00ca34",
      "date_created": "Mon, 13 May 2024 11:23:51 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
      "account_sid": "31d87e6f-229e-4696-9ab7-c85eab8ebee8",
      "body": "Hello World",
      "date_sent": null,
      "direction": "outbound-api",
      "error_code": null,
      "error_message": null,
      "from": "2442",
      "messaging_service_sid": null,
      "num_media": "0",
      "num_segments": "1",
      "price": null,
      "price_unit": null,
      "status": "accepted",
      "subresource_uris": {
      },
      "tags": {
      },
      "to": "+85512334667",
      "uri": "/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages/eed93f0c-3e9a-427f-b867-dedeac00ca34"
    }
  ],
  "uri": "/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/31d87e6f-229e-4696-9ab7-c85eab8ebee8/Messages?Page=0&PageToken=PBeed93f0c-3e9a-427f-b867-dedeac00ca34",
  "next_page_uri": null
}

6. Redact a message

This action can be used to redact messages: to do so, POST to the above URI and set the Body parameter as an empty string: "". This will allow you to effectively redact the text of a message while keeping the other message resource properties intact.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/1032c99b-813b-4c9c-be73-9d3744c109f2/Messages/932cb41f-c609-42b9-889c-ff090bdc6e53" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 1032c99b-813b-4c9c-be73-9d3744c109f2:AuthToken \
    --data-urlencode "Body="

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/1032c99b-813b-4c9c-be73-9d3744c109f2/Messages/932cb41f-c609-42b9-889c-ff090bdc6e53

Parameters

{
  "Body": ""
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Message resources to update.
Sid Path Parameter: The SID of the Message resource to be updated.
Body Request Body Parameter: The new body of the Message resource. To redact the text content of a Message, this parameter's value must be an empty string
Status Request Body Parameter: Set as canceled to prevent a not-yet-sent Message from being sent. Can be used to cancel sending a scheduled Message.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "932cb41f-c609-42b9-889c-ff090bdc6e53",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "1032c99b-813b-4c9c-be73-9d3744c109f2",
  "body": "",
  "date_sent": "Mon, 13 May 2024 11:23:51 -0000",
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "2442",
  "messaging_service_sid": null,
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "sent",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+85512334667",
  "uri": "/2010-04-01/Accounts/1032c99b-813b-4c9c-be73-9d3744c109f2/Messages/932cb41f-c609-42b9-889c-ff090bdc6e53"
}

7. Cancel a scheduled message

Before you use this functionality:

  1. Ensure the status value of canceled is spelled with one "l", (canceled) and not two (cancelled).
  2. Ensure that you store the MessageSid of the messages you schedule. You need to reference the MessageSid for each message cancelation request.
  3. There is no bulk cancelation. If you'd like to cancel multiple messages, you must send in a cancelation request for each message and reference the MessageSid.
  4. There is a new status callback event for Canceled. You can continue to receive existing callback events by including the optional StatusCallBack parameter in the message request.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/fe8ebbbd-b3b5-4585-93a5-7890db48db12/Messages/5b52e323-1367-46f5-b2fa-3697dbfbdc68" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u fe8ebbbd-b3b5-4585-93a5-7890db48db12:AuthToken \
    --data-urlencode "Status=canceled"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/fe8ebbbd-b3b5-4585-93a5-7890db48db12/Messages/5b52e323-1367-46f5-b2fa-3697dbfbdc68

Parameters

{
  "Status": "canceled"
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Message resources to update.
Sid Path Parameter: The SID of the Message resource to be updated.
Body Request Body Parameter: The new body of the Message resource. To redact the text content of a Message, this parameter's value must be an empty string
Status Request Body Parameter: Set as canceled to prevent a not-yet-sent Message from being sent. Can be used to cancel sending a scheduled Message.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "5b52e323-1367-46f5-b2fa-3697dbfbdc68",
  "date_created": "Mon, 13 May 2024 11:23:51 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:51 -0000",
  "account_sid": "fe8ebbbd-b3b5-4585-93a5-7890db48db12",
  "body": "Hello World",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": null,
  "messaging_service_sid": "0f7582e3-7d2b-436c-9e0c-400d2f29c70e",
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "status": "canceled",
  "subresource_uris": {
  },
  "tags": {
  },
  "to": "+85512334667",
  "uri": "/2010-04-01/Accounts/fe8ebbbd-b3b5-4585-93a5-7890db48db12/Messages/5b52e323-1367-46f5-b2fa-3697dbfbdc68"
}

8. Delete a Message

To delete a Message resource, send a DELETE request to the Message resource's URI.

If the DELETE request is successful, the response status code is HTTP 204 (No Content).

A deleted Message resource no longer appears in your Account's Messaging logs. Deleted messages cannot be recovered.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/4684cf4c-a4b3-4959-974f-7ab1df484c76/Messages/31e13a27-dddf-43a1-b5de-ffbdf8d1947f" -d '' -X DELETE \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 4684cf4c-a4b3-4959-974f-7ab1df484c76:AuthToken

Endpoint

DELETE https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid

DELETE https://api.somleng.org/2010-04-01/Accounts/4684cf4c-a4b3-4959-974f-7ab1df484c76/Messages/31e13a27-dddf-43a1-b5de-ffbdf8d1947f

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account associated with the Message resource.
Sid Path Parameter: The SID of the Message resource you wish to delete.

Response


204 No Content

Pagination

When fetching multiple pages of API results, use the provided next_page_uri parameter to retrieve the next page of results.

1. List Resources

Some resources are lists of other resources. For example, the Calls list resource returns a list of calls. There are several important things to know about using and manipulating these lists.

Pagination Information

Property Description
uri The URI of the current page.
first_page_uri The URI for the first page of this list.
next_page_uri The URI for the next page of this list.
previous_page_uri The URI for the previous page of this list.
page The current page number. Zero-indexed, so the first page is 0.
page_size How many items are in each page

** Paging Through API Resources **

When fetching multiple pages of API results, use the provided next_page_uri parameter to retrieve the next page of results.

You can control the size of pages with the PageSize parameter.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?PageSize=2" \
    -u c2686403-59b5-40ee-a404-e7dda32ac53c:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls

GET https://api.somleng.org/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?PageSize=2

Parameters

PageSize: 2
Name Description
PageSize How many resources to return in each list page. The default is 50, and the maximum is 100.

Response


200 OK

{
  "calls": [
    {
      "api_version": "2010-04-01",
      "sid": "97ad4313-5442-4332-b3ae-8259f578f1bc",
      "date_created": "Mon, 13 May 2024 11:23:07 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:07 -0000",
      "account_sid": "c2686403-59b5-40ee-a404-e7dda32ac53c",
      "annotation": null,
      "answered_by": null,
      "caller_name": null,
      "direction": "outbound-api",
      "duration": null,
      "end_time": null,
      "forwarded_from": null,
      "from": "2442",
      "from_formatted": "2442",
      "group_sid": null,
      "parent_call_sid": null,
      "phone_number_sid": null,
      "price": null,
      "price_unit": null,
      "start_time": null,
      "status": "queued",
      "subresource_uris": {
      },
      "to": "+85512334667",
      "to_formatted": "+855 12 334 667",
      "uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls/97ad4313-5442-4332-b3ae-8259f578f1bc"
    },
    {
      "api_version": "2010-04-01",
      "sid": "d586f689-373e-41ad-86a1-408d1fef634a",
      "date_created": "Mon, 13 May 2024 11:23:07 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:07 -0000",
      "account_sid": "c2686403-59b5-40ee-a404-e7dda32ac53c",
      "annotation": null,
      "answered_by": null,
      "caller_name": null,
      "direction": "outbound-api",
      "duration": null,
      "end_time": null,
      "forwarded_from": null,
      "from": "2442",
      "from_formatted": "2442",
      "group_sid": null,
      "parent_call_sid": null,
      "phone_number_sid": null,
      "price": null,
      "price_unit": null,
      "start_time": null,
      "status": "queued",
      "subresource_uris": {
      },
      "to": "+85512334667",
      "to_formatted": "+855 12 334 667",
      "uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls/d586f689-373e-41ad-86a1-408d1fef634a"
    }
  ],
  "uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?PageSize=2",
  "page": 0,
  "page_size": 2,
  "first_page_uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?Page=0&PageSize=2",
  "previous_page_uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?Page=0&PageSize=2&PageToken=PB97ad4313-5442-4332-b3ae-8259f578f1bc",
  "next_page_uri": "/2010-04-01/Accounts/c2686403-59b5-40ee-a404-e7dda32ac53c/Calls?Page=1&PageSize=2&PageToken=PAd586f689-373e-41ad-86a1-408d1fef634a"
}

Phone Calls

1. Create a call

Calls can be made via the REST API to phone numbers. To place a new outbound call, make an HTTP POST request to your account's Call resource.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/54f75661-1f60-4c37-a56d-1d0a5d2bcd61/Calls" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 54f75661-1f60-4c37-a56d-1d0a5d2bcd61:AuthToken \
    --data-urlencode "To=+299221234" \
    --data-urlencode "From=+12513095500" \
    --data-urlencode "Url=https://demo.twilio.com/docs/voice.xml"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls

POST https://api.somleng.org/2010-04-01/Accounts/54f75661-1f60-4c37-a56d-1d0a5d2bcd61/Calls

Parameters

{
  "To": "+299221234",
  "From": "+12513095500",
  "Url": "https://demo.twilio.com/docs/voice.xml"
}
Name Description
AccountSid Path Parameter: The SID of the Account that will create the resource.
To required Request Body Parameter: The phone number to call.
From required Request Body Parameter: The phone number to use as the caller id.
Url Request Body Parameter: The absolute URL that returns the TwiML instructions for the call. We will call this URL using the method when the call connects.
Method The HTTP method we should use when calling the url parameter's value. Can be: GET or POST and the default is POST.
Twiml Request Body Parameter: TwiML instructions for the call to be used without fetching TwiML from Url parameter. If both Twiml and Url are provided then Twiml parameter will be ignored.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when calling the status_callback URL. Can be: GET or POST and the default is POST.

Response


201 Created

{
  "api_version": "2010-04-01",
  "sid": "5ce2eff5-eecc-42b6-aac8-21bc3f9a4db2",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "54f75661-1f60-4c37-a56d-1d0a5d2bcd61",
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "direction": "outbound-api",
  "duration": null,
  "end_time": null,
  "forwarded_from": null,
  "from": "+12513095500",
  "from_formatted": "+1 (251) 309-5500",
  "group_sid": null,
  "parent_call_sid": null,
  "phone_number_sid": "e1f8dbfb-9fc2-4d16-8636-5d17a1cd64a5",
  "price": null,
  "price_unit": null,
  "start_time": null,
  "status": "queued",
  "subresource_uris": {
  },
  "to": "+299221234",
  "to_formatted": "+299 22 1234",
  "uri": "/2010-04-01/Accounts/54f75661-1f60-4c37-a56d-1d0a5d2bcd61/Calls/5ce2eff5-eecc-42b6-aac8-21bc3f9a4db2"
}

2. Fetch a call

This API call returns the Call resource of an individual call, identified by its Sid.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/130195b7-8f01-4ae3-a6c6-1a432f0af14c/Calls/0d670d41-c896-4b11-8149-13e2aad03e8f" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 130195b7-8f01-4ae3-a6c6-1a432f0af14c:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:Sid

GET https://api.somleng.org/2010-04-01/Accounts/130195b7-8f01-4ae3-a6c6-1a432f0af14c/Calls/0d670d41-c896-4b11-8149-13e2aad03e8f

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Call resource(s) to fetch.
Sid Path Parameter: The SID of the Call resource to fetch.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "0d670d41-c896-4b11-8149-13e2aad03e8f",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "130195b7-8f01-4ae3-a6c6-1a432f0af14c",
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "direction": "outbound-api",
  "duration": null,
  "end_time": null,
  "forwarded_from": null,
  "from": "2442",
  "from_formatted": "2442",
  "group_sid": null,
  "parent_call_sid": null,
  "phone_number_sid": null,
  "price": null,
  "price_unit": null,
  "start_time": null,
  "status": "queued",
  "subresource_uris": {
  },
  "to": "+85512334667",
  "to_formatted": "+855 12 334 667",
  "uri": "/2010-04-01/Accounts/130195b7-8f01-4ae3-a6c6-1a432f0af14c/Calls/0d670d41-c896-4b11-8149-13e2aad03e8f"
}

3. List phone calls

Return a list of phone calls made to and from an account, identified by its AccountSid.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u c89756db-a9eb-42ea-b8a6-2237ef7a50c1:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls

GET https://api.somleng.org/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls

Parameters

{
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Call resource(s) to read.

Response


200 OK

{
  "calls": [
    {
      "api_version": "2010-04-01",
      "sid": "fcccae13-e046-412b-a038-aac398d8a51e",
      "date_created": "Mon, 13 May 2024 11:23:59 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
      "account_sid": "c89756db-a9eb-42ea-b8a6-2237ef7a50c1",
      "annotation": null,
      "answered_by": null,
      "caller_name": null,
      "direction": "outbound-api",
      "duration": null,
      "end_time": null,
      "forwarded_from": null,
      "from": "2442",
      "from_formatted": "2442",
      "group_sid": null,
      "parent_call_sid": null,
      "phone_number_sid": null,
      "price": null,
      "price_unit": null,
      "start_time": null,
      "status": "queued",
      "subresource_uris": {
      },
      "to": "+85512334667",
      "to_formatted": "+855 12 334 667",
      "uri": "/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls/fcccae13-e046-412b-a038-aac398d8a51e"
    }
  ],
  "uri": "/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/c89756db-a9eb-42ea-b8a6-2237ef7a50c1/Calls?Page=0&PageToken=PBfcccae13-e046-412b-a038-aac398d8a51e",
  "next_page_uri": null
}

4. Update a Call in progress with TwiML

Updating a Call resource allows you to modify an active call.

Real-time call modification allows you to interrupt an in-progress call and terminate it or have it begin processing TwiML from either a new URL or from the TwiML provided with modification. Call modification is useful for any application where you want to change the behavior of a running call asynchronously, e.g., hold music, call queues, transferring calls, or forcing a hangup.

By sending an HTTP POST request to a specific Call instance, you can redirect a call that is in progress or you can terminate a call.

This example interrupts an in-progress call and begins processing TwiML from a the TwiML provided.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/64211b93-dfe0-48c8-8d5b-a5ce2534fead/Calls/7435f8b4-f3c2-47de-852a-cffb57d9089e" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 64211b93-dfe0-48c8-8d5b-a5ce2534fead:AuthToken \
    --data-urlencode "Twiml=<Response><Say>Ahoy there</Say></Response>"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/64211b93-dfe0-48c8-8d5b-a5ce2534fead/Calls/7435f8b4-f3c2-47de-852a-cffb57d9089e

Parameters

{
  "Twiml": "<Response><Say>Ahoy there</Say></Response>"
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Call resource(s) to update.
Sid Path Parameter: The ID that uniquely identifies the Call resource to update.
Url Request Body Parameter: The absolute URL that returns the TwiML instructions for the call. We will call this URL using the method when the call connects.
Method Request Body Parameter: The HTTP method we should use when calling the url. Can be: GET or POST and the default is POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when requesting the status_callback URL. Can be: GET or POST and the default is POST.
Twiml Request Body Parameter: TwiML instructions for the call to be used without fetching Twiml from url. Twiml and Url parameters are mutually exclusive.
Status Request Body Parameter: The new status of the resource. Can be: canceled or completed. Specifying canceled will attempt to hang up calls that are queued or ringing; however, it will not affect calls already in progress. Specifying completed will attempt to hang up a call even if it's already in progress.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "7435f8b4-f3c2-47de-852a-cffb57d9089e",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "64211b93-dfe0-48c8-8d5b-a5ce2534fead",
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "direction": "outbound-api",
  "duration": null,
  "end_time": null,
  "forwarded_from": null,
  "from": "2442",
  "from_formatted": "2442",
  "group_sid": null,
  "parent_call_sid": null,
  "phone_number_sid": null,
  "price": null,
  "price_unit": null,
  "start_time": null,
  "status": "in-progress",
  "subresource_uris": {
  },
  "to": "+85512334667",
  "to_formatted": "+855 12 334 667",
  "uri": "/2010-04-01/Accounts/64211b93-dfe0-48c8-8d5b-a5ce2534fead/Calls/7435f8b4-f3c2-47de-852a-cffb57d9089e"
}

5. Update a Call in progress with URL

This example interrupts an in-progress call and begins processing TwiML from a new URL.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/5b2b99e3-f9be-459a-b95d-b36bba49b129/Calls/1b5b669d-f1af-4bb6-a96b-1aaf2523ea76" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 5b2b99e3-f9be-459a-b95d-b36bba49b129:AuthToken \
    --data-urlencode "Url=https://demo.twilio.com/docs/voice.xml" \
    --data-urlencode "Method=POST"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/5b2b99e3-f9be-459a-b95d-b36bba49b129/Calls/1b5b669d-f1af-4bb6-a96b-1aaf2523ea76

Parameters

{
  "Url": "https://demo.twilio.com/docs/voice.xml",
  "Method": "POST"
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Call resource(s) to update.
Sid Path Parameter: The ID that uniquely identifies the Call resource to update.
Url Request Body Parameter: The absolute URL that returns the TwiML instructions for the call. We will call this URL using the method when the call connects.
Method Request Body Parameter: The HTTP method we should use when calling the url. Can be: GET or POST and the default is POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when requesting the status_callback URL. Can be: GET or POST and the default is POST.
Twiml Request Body Parameter: TwiML instructions for the call to be used without fetching Twiml from url. Twiml and Url parameters are mutually exclusive.
Status Request Body Parameter: The new status of the resource. Can be: canceled or completed. Specifying canceled will attempt to hang up calls that are queued or ringing; however, it will not affect calls already in progress. Specifying completed will attempt to hang up a call even if it's already in progress.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "1b5b669d-f1af-4bb6-a96b-1aaf2523ea76",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "5b2b99e3-f9be-459a-b95d-b36bba49b129",
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "direction": "outbound-api",
  "duration": null,
  "end_time": null,
  "forwarded_from": null,
  "from": "2442",
  "from_formatted": "2442",
  "group_sid": null,
  "parent_call_sid": null,
  "phone_number_sid": null,
  "price": null,
  "price_unit": null,
  "start_time": null,
  "status": "in-progress",
  "subresource_uris": {
  },
  "to": "+85512334667",
  "to_formatted": "+855 12 334 667",
  "uri": "/2010-04-01/Accounts/5b2b99e3-f9be-459a-b95d-b36bba49b129/Calls/1b5b669d-f1af-4bb6-a96b-1aaf2523ea76"
}

6. End a call

This example interrupts an in-progress call and terminates it.

Request

curl -X POST "https://api.somleng.org/2010-04-01/Accounts/00ec3a79-02b7-415b-86f8-8e4a106e102a/Calls/0f8d1cd8-4490-44ec-b3df-1fe2d0b88f9e" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u 00ec3a79-02b7-415b-86f8-8e4a106e102a:AuthToken \
    --data-urlencode "Status=completed"

Endpoint

POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:Sid

POST https://api.somleng.org/2010-04-01/Accounts/00ec3a79-02b7-415b-86f8-8e4a106e102a/Calls/0f8d1cd8-4490-44ec-b3df-1fe2d0b88f9e

Parameters

{
  "Status": "completed"
}
Name Description
AccountSid Path Parameter: The SID of the Account that created the Call resource(s) to update.
Sid Path Parameter: The ID that uniquely identifies the Call resource to update.
Url Request Body Parameter: The absolute URL that returns the TwiML instructions for the call. We will call this URL using the method when the call connects.
Method Request Body Parameter: The HTTP method we should use when calling the url. Can be: GET or POST and the default is POST.
StatusCallback Request Body Parameter: The URL we should call using the status_callback_method to send status information to your application. URLs must contain a valid hostname (underscores are not permitted).
StatusCallbackMethod Request Body Parameter: The HTTP method we should use when requesting the status_callback URL. Can be: GET or POST and the default is POST.
Twiml Request Body Parameter: TwiML instructions for the call to be used without fetching Twiml from url. Twiml and Url parameters are mutually exclusive.
Status Request Body Parameter: The new status of the resource. Can be: canceled or completed. Specifying canceled will attempt to hang up calls that are queued or ringing; however, it will not affect calls already in progress. Specifying completed will attempt to hang up a call even if it's already in progress.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "0f8d1cd8-4490-44ec-b3df-1fe2d0b88f9e",
  "date_created": "Mon, 13 May 2024 11:23:59 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:59 -0000",
  "account_sid": "00ec3a79-02b7-415b-86f8-8e4a106e102a",
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "direction": "outbound-api",
  "duration": null,
  "end_time": null,
  "forwarded_from": null,
  "from": "2442",
  "from_formatted": "2442",
  "group_sid": null,
  "parent_call_sid": null,
  "phone_number_sid": null,
  "price": null,
  "price_unit": null,
  "start_time": null,
  "status": "in-progress",
  "subresource_uris": {
  },
  "to": "+85512334667",
  "to_formatted": "+855 12 334 667",
  "uri": "/2010-04-01/Accounts/00ec3a79-02b7-415b-86f8-8e4a106e102a/Calls/0f8d1cd8-4490-44ec-b3df-1fe2d0b88f9e"
}

Recordings

1. Fetch a Recording's media file

You can fetch a Recording's media file by appending .wav or .mp3 to the Recording Resource's URI.

It's only possible to fetch a Recording's media file when the Recording's status is completed.

If the media associated with a Recording Resource is not available, the request returns 404 Not Found.

Without an extension, or with a .wav, a binary WAV audio file is returned with mime-type audio/x-wav.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/79c402ac-079c-4306-a577-85bb578be352/Recordings/43c728ef-8879-4b36-8128-152cdbf2df97"

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid

GET https://api.somleng.org/2010-04-01/Accounts/79c402ac-079c-4306-a577-85bb578be352/Recordings/43c728ef-8879-4b36-8128-152cdbf2df97

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the Recording resource to fetch.
Sid Path Parameter: The SID of the Recording resource to fetch.

Response


302 Found

2. Fetch a Recording as mp3

You can fetch a Recording's media file as mp3 by appending .mp3 to the Recording Resource's URI.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/11bef1a2-c5b4-412a-8ec7-612bc7192d70/Recordings/f25b5c94-cc54-4a4b-bfa0-2e95fa6a4dd2.mp3"

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid.mp3

GET https://api.somleng.org/2010-04-01/Accounts/11bef1a2-c5b4-412a-8ec7-612bc7192d70/Recordings/f25b5c94-cc54-4a4b-bfa0-2e95fa6a4dd2.mp3

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the Recording resource to fetch.
Sid Path Parameter: The SID of the Recording resource to fetch.

Response


302 Found

3. Fetch a Recording's metadata

A Recording's metadata can be returned in JSON format. Append .json to the Recording Resource's URI.

Request

curl "https://api.somleng.org/2010-04-01/Accounts/00d129d7-3cd1-429e-9534-9c1d6f1b41e6/Recordings/dd680fac-d8f7-4d0e-8283-1306289cadb4.json"

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid.json

GET https://api.somleng.org/2010-04-01/Accounts/00d129d7-3cd1-429e-9534-9c1d6f1b41e6/Recordings/dd680fac-d8f7-4d0e-8283-1306289cadb4.json

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the Recording resource to fetch.
Sid Path Parameter: The SID of the Recording resource to fetch.

Response


200 OK

{
  "api_version": "2010-04-01",
  "sid": "dd680fac-d8f7-4d0e-8283-1306289cadb4",
  "date_created": "Mon, 13 May 2024 11:23:25 -0000",
  "date_updated": "Mon, 13 May 2024 11:23:25 -0000",
  "account_sid": "00d129d7-3cd1-429e-9534-9c1d6f1b41e6",
  "call_sid": "5821e13a-3070-4523-ac18-c8d27e68b308",
  "conference_sid": null,
  "channels": 1,
  "start_time": "2024-05-13T11:23:25.735Z",
  "duration": null,
  "price": null,
  "price_unit": null,
  "source": "RecordVerb",
  "status": "processing",
  "error_code": null,
  "encryption_details": null,
  "track": "both",
  "uri": "/2010-04-01/Accounts/00d129d7-3cd1-429e-9534-9c1d6f1b41e6/Calls/5821e13a-3070-4523-ac18-c8d27e68b308/Recordings/dd680fac-d8f7-4d0e-8283-1306289cadb4.json"
}

4. Get all recordings for a given call

Request

curl "https://api.somleng.org/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings" \
    -u 9ebf24f1-f35c-4b4b-9cc5-389713c2b854:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:CallSid/Recordings

GET https://api.somleng.org/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the Recording resource to read.
CallSid Path Parameter: The Call SID of the Recording resources to read.

Response


200 OK

{
  "recordings": [
    {
      "api_version": "2010-04-01",
      "sid": "40a5c6b3-5634-4955-9532-16dfbbd1c731",
      "date_created": "Mon, 13 May 2024 11:23:25 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:25 -0000",
      "account_sid": "9ebf24f1-f35c-4b4b-9cc5-389713c2b854",
      "call_sid": "c2a5ed8c-f72e-4e7c-942d-d96af58d82a7",
      "conference_sid": null,
      "channels": 1,
      "start_time": "2024-05-13T11:23:25.661Z",
      "duration": "0",
      "price": null,
      "price_unit": null,
      "source": "RecordVerb",
      "status": "completed",
      "error_code": null,
      "encryption_details": null,
      "track": "both",
      "uri": "/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings/40a5c6b3-5634-4955-9532-16dfbbd1c731.json"
    }
  ],
  "uri": "/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/9ebf24f1-f35c-4b4b-9cc5-389713c2b854/Calls/c2a5ed8c-f72e-4e7c-942d-d96af58d82a7/Recordings?Page=0&PageToken=PB40a5c6b3-5634-4955-9532-16dfbbd1c731",
  "next_page_uri": null
}

5. List recordings by account

Request

curl "https://api.somleng.org/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Recordings" \
    -u 5c731ce9-e92d-4d56-9ea0-7a1362189c82:AuthToken

Endpoint

GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings

GET https://api.somleng.org/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Recordings

Parameters

Name Description
AccountSid Path Parameter: The SID of the Account that created the Recording resource to read.

Response


200 OK

{
  "recordings": [
    {
      "api_version": "2010-04-01",
      "sid": "5259fa16-2100-4f96-94ea-4b952e477f81",
      "date_created": "Mon, 13 May 2024 11:23:25 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:25 -0000",
      "account_sid": "5c731ce9-e92d-4d56-9ea0-7a1362189c82",
      "call_sid": "02f15b42-e4f2-47e0-a58f-6ed3b9a08417",
      "conference_sid": null,
      "channels": 1,
      "start_time": "2024-05-13T11:23:25.591Z",
      "duration": null,
      "price": null,
      "price_unit": null,
      "source": "RecordVerb",
      "status": "processing",
      "error_code": null,
      "encryption_details": null,
      "track": "both",
      "uri": "/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Calls/02f15b42-e4f2-47e0-a58f-6ed3b9a08417/Recordings/5259fa16-2100-4f96-94ea-4b952e477f81.json"
    },
    {
      "api_version": "2010-04-01",
      "sid": "007f37c8-210e-4372-a543-92f6768a569b",
      "date_created": "Mon, 13 May 2024 11:23:25 -0000",
      "date_updated": "Mon, 13 May 2024 11:23:25 -0000",
      "account_sid": "5c731ce9-e92d-4d56-9ea0-7a1362189c82",
      "call_sid": "dc8060b1-6e21-410e-8608-d208f7165527",
      "conference_sid": null,
      "channels": 1,
      "start_time": "2024-05-13T11:23:25.572Z",
      "duration": null,
      "price": null,
      "price_unit": null,
      "source": "RecordVerb",
      "status": "processing",
      "error_code": null,
      "encryption_details": null,
      "track": "both",
      "uri": "/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Calls/dc8060b1-6e21-410e-8608-d208f7165527/Recordings/007f37c8-210e-4372-a543-92f6768a569b.json"
    }
  ],
  "uri": "/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Recordings",
  "page": 0,
  "page_size": 50,
  "first_page_uri": "/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Recordings?Page=0",
  "previous_page_uri": "/2010-04-01/Accounts/5c731ce9-e92d-4d56-9ea0-7a1362189c82/Recordings?Page=0&PageToken=PB5259fa16-2100-4f96-94ea-4b952e477f81",
  "next_page_uri": null
}

Verification Services

1. Create a Verification Service

A Verification Service is the set of common configurations used to create and check verifications. You can create a service with the API or in the Console.

Request

curl -X POST "https://verify.somleng.org/v2/Services" \
    -u d9d8ed96-0255-4989-a63c-c80a68c2b9ba:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "FriendlyName=My Verification Service"

Endpoint

POST https://verify.somleng.org/v2/Services

POST https://verify.somleng.org/v2/Services

Parameters

{
  "FriendlyName": "My Verification Service"
}
Name Description
FriendlyName required Request Body Parameter: A descriptive string that you create to describe the verification service. It can be up to 32 characters long.
CodeLength Request Body Parameter: The length of the verification code to generate. Must be an integer value between 4 and 10, inclusive.

Response


201 Created

{
  "sid": "46f77c43-63a0-449d-ab11-bd60542ffa8d",
  "account_sid": "d9d8ed96-0255-4989-a63c-c80a68c2b9ba",
  "date_created": "2024-05-13T11:24:17Z",
  "date_updated": "2024-05-13T11:24:17Z",
  "friendly_name": "My Verification Service",
  "url": "http://verify.lvh.me/v2/Services/46f77c43-63a0-449d-ab11-bd60542ffa8d",
  "code_length": 6
}

2. Fetch a Service

Request

curl "https://verify.somleng.org/v2/Services/1da5abb0-7800-4256-8e3e-a455fc69dd36" \
    -u ca79c839-1fc7-40ee-978c-5861bd1aa42d:AuthToken

Endpoint

GET https://verify.somleng.org/v2/Services/:Sid

GET https://verify.somleng.org/v2/Services/1da5abb0-7800-4256-8e3e-a455fc69dd36

Parameters

Name Description
Sid Path Parameter: The SID of the Verification Service to fetch.

Response


200 OK

{
  "sid": "1da5abb0-7800-4256-8e3e-a455fc69dd36",
  "account_sid": "ca79c839-1fc7-40ee-978c-5861bd1aa42d",
  "date_created": "2024-05-13T11:24:17Z",
  "date_updated": "2024-05-13T11:24:17Z",
  "friendly_name": "My Verification Service",
  "url": "http://verify.lvh.me/v2/Services/1da5abb0-7800-4256-8e3e-a455fc69dd36",
  "code_length": 4
}

3. List all Services

Request

curl "https://verify.somleng.org/v2/Services" \
    -u fd9496c8-e509-4329-a3f1-9132a7a4422e:AuthToken

Endpoint

GET https://verify.somleng.org/v2/Services

GET https://verify.somleng.org/v2/Services

Parameters

None known.

Response


200 OK

{
  "services": [
    {
      "sid": "6d061442-d63e-448d-a4b4-476ef6018dab",
      "account_sid": "fd9496c8-e509-4329-a3f1-9132a7a4422e",
      "date_created": "2024-05-13T11:24:17Z",
      "date_updated": "2024-05-13T11:24:17Z",
      "friendly_name": "My Verification Service",
      "url": "http://verify.lvh.me/v2/Services/6d061442-d63e-448d-a4b4-476ef6018dab",
      "code_length": 4
    }
  ],
  "meta": {
    "url": "https://verify.somleng.org/v2/Services",
    "page": 0,
    "page_size": 50,
    "first_page_url": "https://verify.somleng.org/v2/Services?Page=0",
    "previous_page_url": "https://verify.somleng.org/v2/Services?Page=0&PageToken=PB6d061442-d63e-448d-a4b4-476ef6018dab",
    "next_page_url": null,
    "key": "services"
  }
}

4. Update a Service

This example updates the FriendlyName and CodeLength of a Verification Service.

Request

curl -X POST "https://verify.somleng.org/v2/Services/2ec17465-5687-4d5c-943a-e3d7e7540d66" \
    -u 24addb74-2f49-4dd1-b141-3344d4085a6a:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "FriendlyName=Rocket Ride Service" \
    --data-urlencode "CodeLength=6"

Endpoint

POST https://verify.somleng.org/v2/Services/:sid

POST https://verify.somleng.org/v2/Services/2ec17465-5687-4d5c-943a-e3d7e7540d66

Parameters

{
  "FriendlyName": "Rocket Ride Service",
  "CodeLength": "6"
}
Name Description
Sid required Path Parameter: The SID of the Verification Service to update.
FriendlyName required Request Body Parameter: A descriptive string that you create to describe the Verification Service. It can be up to 32 characters long.
Request Body Parameter: CodeLength The length of the verification code to generate. Must be an integer value between 4 and 10, inclusive.

Response


200 OK

{
  "sid": "2ec17465-5687-4d5c-943a-e3d7e7540d66",
  "account_sid": "24addb74-2f49-4dd1-b141-3344d4085a6a",
  "date_created": "2024-05-13T11:24:17Z",
  "date_updated": "2024-05-13T11:24:17Z",
  "friendly_name": "Rocket Ride Service",
  "url": "http://verify.lvh.me/v2/Services/2ec17465-5687-4d5c-943a-e3d7e7540d66",
  "code_length": 6
}

5. Delete a Service

Request

curl "https://verify.somleng.org/v2/Services/eb06f12c-6304-4011-83ec-11dc384fb76f" -d '' -X DELETE \
    -u 214d7eeb-f960-42a3-9690-086868391f38:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded"

Endpoint

DELETE https://verify.somleng.org/v2/Services/:Sid

DELETE https://verify.somleng.org/v2/Services/eb06f12c-6304-4011-83ec-11dc384fb76f

Parameters

{
}
Name Description
Sid Path Parameter: The SID of the Verification Service to delete.

Response


204 No Content

Verifications

1. Start a Verification with SMS

To verify a user's phone number, start by requesting to send a verification code to their device. Phone numbers must be in E.164 format.

Request

curl -X POST "https://verify.somleng.org/v2/Services/4ea59c2b-231b-43e7-8d02-bd4c95fde345/Verifications" \
    -u bed70d85-0bfd-43d2-bb54-1288ae89b438:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "To=+85512334667" \
    --data-urlencode "Channel=sms"

Endpoint

POST https://verify.somleng.org/v2/Services/:ServiceSid/Verifications

POST https://verify.somleng.org/v2/Services/4ea59c2b-231b-43e7-8d02-bd4c95fde345/Verifications

Parameters

{
  "To": "+85512334667",
  "Channel": "sms"
}
Name Description
ServiceSid Path Parameter: The SID of the verification Service to create the resource under.
To required Request Body Parameter: The phone number or email to verify. Phone numbers must be in E.164 format.
Channel required Request Body Parameter: The verification method to use. One of: sms or call
Locale Request Body Parameter: Locale will automatically resolve based on phone number country code of the recipient for SMS and call channel verifications. It will fallback to English if the selected translation is not available. This parameter will override the automatic locale resolution. The following locales are supported: en, fr, ja, nl, ar, ca, da, de, es, fi, id, it, ko, pl, pt, ru, sv, tr, uk, vi, af, cs, el, hi, hr, hu, km, kn, lt, mr, ms, nb, pt-br, ro, sk, te, th, tl, zh-cn, zh-hk, zh.

Response


200 OK

{
  "sid": "41f9c7a3-ae7c-48c0-ae61-837cfb2599c4",
  "account_sid": "bed70d85-0bfd-43d2-bb54-1288ae89b438",
  "date_created": "2024-05-13T11:23:31Z",
  "date_updated": "2024-05-13T11:23:31Z",
  "service_sid": "4ea59c2b-231b-43e7-8d02-bd4c95fde345",
  "to": "+85512334667",
  "channel": "sms",
  "status": "pending",
  "url": "http://verify.lvh.me/v2/Services/4ea59c2b-231b-43e7-8d02-bd4c95fde345/Verifications/41f9c7a3-ae7c-48c0-ae61-837cfb2599c4",
  "send_code_attempts": [
    {
      "attempt_sid": "215955ad-9bca-4833-bed8-89a9db8886cc",
      "channel": "sms",
      "time": "2024-05-13T11:23:31Z"
    }
  ]
}

2. Start a Verification with Voice

Request

curl -X POST "https://verify.somleng.org/v2/Services/0ecdc727-0bf7-41a1-b219-7d43d14c531b/Verifications" \
    -u f3252ca3-d7d0-40f5-afeb-fc942b675307:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "To=+85512334667" \
    --data-urlencode "Channel=call"

Endpoint

POST https://verify.somleng.org/v2/Services/:ServiceSid/Verifications

POST https://verify.somleng.org/v2/Services/0ecdc727-0bf7-41a1-b219-7d43d14c531b/Verifications

Parameters

{
  "To": "+85512334667",
  "Channel": "call"
}
Name Description
ServiceSid Path Parameter: The SID of the verification Service to create the resource under.
To required Request Body Parameter: The phone number or email to verify. Phone numbers must be in E.164 format.
Channel required Request Body Parameter: The verification method to use. One of: sms or call
Locale Request Body Parameter: Locale will automatically resolve based on phone number country code of the recipient for SMS and call channel verifications. It will fallback to English if the selected translation is not available. This parameter will override the automatic locale resolution. The following locales are supported: en, fr, ja, nl, ar, ca, da, de, es, fi, id, it, ko, pl, pt, ru, sv, tr, uk, vi, af, cs, el, hi, hr, hu, km, kn, lt, mr, ms, nb, pt-br, ro, sk, te, th, tl, zh-cn, zh-hk, zh.

Response


200 OK

{
  "sid": "1f396e14-90d0-4b7b-80aa-9e5876e9ec60",
  "account_sid": "f3252ca3-d7d0-40f5-afeb-fc942b675307",
  "date_created": "2024-05-13T11:23:31Z",
  "date_updated": "2024-05-13T11:23:31Z",
  "service_sid": "0ecdc727-0bf7-41a1-b219-7d43d14c531b",
  "to": "+85512334667",
  "channel": "call",
  "status": "pending",
  "url": "http://verify.lvh.me/v2/Services/0ecdc727-0bf7-41a1-b219-7d43d14c531b/Verifications/1f396e14-90d0-4b7b-80aa-9e5876e9ec60",
  "send_code_attempts": [
    {
      "attempt_sid": "498107b5-e987-419d-9ce2-b52fbb402a2c",
      "channel": "call",
      "time": "2024-05-13T11:23:31Z"
    }
  ]
}

3. Check a Verification with a Phone Number

This API will check whether the user-provided verification code is correct.

⚠️ The verification SID is automatically deleted once it's:

If any of these occur, verification checks will return a 404 Not Found error. If you'd like to double check what happened with a given verification - please use the Dashboard Verify Logs.

Request

curl -X POST "https://verify.somleng.org/v2/Services/c0668ac8-2a70-4ddb-aa28-07bb5cc71460/VerificationCheck" \
    -u 433243e1-59f1-4f8b-80e8-add46092e17c:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "To=+85512334667" \
    --data-urlencode "Code=1234"

Endpoint

POST https://verify.somleng.org/v2/Services/:ServiceSid/VerificationCheck

POST https://verify.somleng.org/v2/Services/c0668ac8-2a70-4ddb-aa28-07bb5cc71460/VerificationCheck

Parameters

{
  "To": "+85512334667",
  "Code": "1234"
}
Name Description
ServiceSid Path Parameter: The SID of the verification Service to create the resource under.
Code required Request Body Parameter: The 4-10 character string being verified.
To Request Body Parameter: The phone number to verify. Either this parameter or the verification_sid` must be specified. Phone numbers must be in E.164 format.
VerificationSid Request Body Parameter: A SID that uniquely identifies the Verification. Either this parameter or the To phone number must be specified.

Response


200 OK

{
  "sid": "51b3524b-4d43-448f-95c3-a559db491c79",
  "account_sid": "433243e1-59f1-4f8b-80e8-add46092e17c",
  "date_created": "2024-05-13T11:23:30Z",
  "date_updated": "2024-05-13T11:23:30Z",
  "service_sid": "c0668ac8-2a70-4ddb-aa28-07bb5cc71460",
  "to": "+85512334667",
  "channel": "sms",
  "status": "approved"
}

4. Check a Verification with a SID

Request

curl -X POST "https://verify.somleng.org/v2/Services/1b15efd6-c8e5-48f7-adfe-74bec6926802/VerificationCheck" \
    -u 171a6b7c-3d6b-4697-89b1-f1a4b9469844:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "VerificationSid=16b6d94d-aebe-4bc7-be8c-b7a4633bea55" \
    --data-urlencode "Code=1234"

Endpoint

POST https://verify.somleng.org/v2/Services/:ServiceSid/VerificationCheck

POST https://verify.somleng.org/v2/Services/1b15efd6-c8e5-48f7-adfe-74bec6926802/VerificationCheck

Parameters

{
  "VerificationSid": "16b6d94d-aebe-4bc7-be8c-b7a4633bea55",
  "Code": "1234"
}
Name Description
ServiceSid Path Parameter: The SID of the verification Service to create the resource under.
Code required Request Body Parameter: The 4-10 character string being verified.
To Request Body Parameter: The phone number to verify. Either this parameter or the verification_sid` must be specified. Phone numbers must be in E.164 format.
VerificationSid Request Body Parameter: A SID that uniquely identifies the Verification. Either this parameter or the To phone number must be specified.

Response


200 OK

{
  "sid": "16b6d94d-aebe-4bc7-be8c-b7a4633bea55",
  "account_sid": "171a6b7c-3d6b-4697-89b1-f1a4b9469844",
  "date_created": "2024-05-13T11:23:30Z",
  "date_updated": "2024-05-13T11:23:30Z",
  "service_sid": "1b15efd6-c8e5-48f7-adfe-74bec6926802",
  "to": "+85512334667",
  "channel": "sms",
  "status": "approved"
}

5. Fetch a Verification

Request

curl "https://verify.somleng.org/v2/Services/9937e75b-0d91-4758-97ec-81dd9670683b/Verifications/992b1c32-29b9-4d74-bccf-d712b9b6d884" \
    -u f4281bdf-6c96-4aee-84d5-d5fc4b94a8e6:AuthToken

Endpoint

GET https://verify.somleng.org/v2/Services/:ServiceSid/Verifications/:Sid

GET https://verify.somleng.org/v2/Services/9937e75b-0d91-4758-97ec-81dd9670683b/Verifications/992b1c32-29b9-4d74-bccf-d712b9b6d884

Parameters

Name Description
ServiceSid Path Parameter: The SID of the Verification Service to fetch the Verification from.
Sid Path Parameter: The SID of the Verification.

Response


200 OK

{
  "sid": "992b1c32-29b9-4d74-bccf-d712b9b6d884",
  "account_sid": "f4281bdf-6c96-4aee-84d5-d5fc4b94a8e6",
  "date_created": "2024-05-13T11:23:31Z",
  "date_updated": "2024-05-13T11:23:31Z",
  "service_sid": "9937e75b-0d91-4758-97ec-81dd9670683b",
  "to": "+85512334667",
  "channel": "sms",
  "status": "pending",
  "url": "http://verify.lvh.me/v2/Services/9937e75b-0d91-4758-97ec-81dd9670683b/Verifications/992b1c32-29b9-4d74-bccf-d712b9b6d884",
  "send_code_attempts": [

  ]
}

6. Update a Verification Status

Manually mark the verification as approved after your application had validated the verification code or mark the verification as canceled to start a new verification session with a different code before the previous code expires (10 minutes). Only recommended during testing or if you're using custom verification codes.

For most other use cases, Verify is able to manage the complete lifecycle of a verification with the Verification Check Resource.

Request

curl -X POST "https://verify.somleng.org/v2/Services/99bb7330-49d5-40ab-9cf3-7a43ce1f333f/Verifications/1845da18-da3d-4372-a013-9a7db616c69a" \
    -u 75002f8d-843a-4b07-83fe-f124a6421aba:AuthToken \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "Status=approved"

Endpoint

POST https://verify.somleng.org/v2/Services/:ServiceSid/Verifications/:Sid

POST https://verify.somleng.org/v2/Services/99bb7330-49d5-40ab-9cf3-7a43ce1f333f/Verifications/1845da18-da3d-4372-a013-9a7db616c69a

Parameters

{
  "Status": "approved"
}
Name Description
ServiceSid Path Parameter: The SID of the Verification Service to update the resource from.
Sid The SID of the Verification resource to update.
To required The phone number or email to verify. Phone numbers must be in E.164 format.
Status required The new status of the resource. Can be: canceled or approved.

Response


200 OK

{
  "sid": "1845da18-da3d-4372-a013-9a7db616c69a",
  "account_sid": "75002f8d-843a-4b07-83fe-f124a6421aba",
  "date_created": "2024-05-13T11:23:31Z",
  "date_updated": "2024-05-13T11:23:31Z",
  "service_sid": "99bb7330-49d5-40ab-9cf3-7a43ce1f333f",
  "to": "+85512334667",
  "channel": "sms",
  "status": "approved",
  "url": "http://verify.lvh.me/v2/Services/99bb7330-49d5-40ab-9cf3-7a43ce1f333f/Verifications/1845da18-da3d-4372-a013-9a7db616c69a",
  "send_code_attempts": [

  ]
}
cURL