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/c71814e2-2271-477d-9bda-77457bd454df" \
-u c71814e2-2271-477d-9bda-77457bd454df:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:Sid
GET https://api.somleng.org/2010-04-01/Accounts/c71814e2-2271-477d-9bda-77457bd454df
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": "c71814e2-2271-477d-9bda-77457bd454df",
"date_created": "Tue, 01 Oct 2024 06:10:13 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:13 -0000",
"auth_token": "N-1J001jkOnV01N5B6s3lHiCanz7UBcUo7SDmMqzWAo",
"friendly_name": "Rocket Rides",
"owner_account_sid": "c71814e2-2271-477d-9bda-77457bd454df",
"status": "active",
"type": "Full",
"uri": "/2010-04-01/Accounts/c71814e2-2271-477d-9bda-77457bd454df",
"subresource_uris": {
"calls": "/2010-04-01/Accounts/c71814e2-2271-477d-9bda-77457bd454df/Calls",
"messages": "/2010-04-01/Accounts/c71814e2-2271-477d-9bda-77457bd454df/Messages",
"recordings": "/2010-04-01/Accounts/c71814e2-2271-477d-9bda-77457bd454df/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/b2cd644f-b5b1-41ac-a925-dd650e607c3a/AvailablePhoneNumbers/CA/Local" \
-u b2cd644f-b5b1-41ac-a925-dd650e607c3a:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/b2cd644f-b5b1-41ac-a925-dd650e607c3a/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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
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/b2cd644f-b5b1-41ac-a925-dd650e607c3a/AvailablePhoneNumbers/CA/Local",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/b2cd644f-b5b1-41ac-a925-dd650e607c3a/AvailablePhoneNumbers/CA/Local?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/b2cd644f-b5b1-41ac-a925-dd650e607c3a/AvailablePhoneNumbers/CA/Local?Page=0&PageToken=PB0ac11824-1d5d-4dd0-a3de-43adae6cddf8",
"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/5029b569-857b-4242-9beb-316e10da9ed2/AvailablePhoneNumbers/CA/Local?AreaCode=201" \
-u 5029b569-857b-4242-9beb-316e10da9ed2:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/5029b569-857b-4242-9beb-316e10da9ed2/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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
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/5029b569-857b-4242-9beb-316e10da9ed2/AvailablePhoneNumbers/CA/Local?AreaCode=201",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/5029b569-857b-4242-9beb-316e10da9ed2/AvailablePhoneNumbers/CA/Local?AreaCode=201&Page=0",
"previous_page_uri": "/2010-04-01/Accounts/5029b569-857b-4242-9beb-316e10da9ed2/AvailablePhoneNumbers/CA/Local?AreaCode=201&Page=0&PageToken=PB64c2ce41-e56f-4bac-afd3-8319e30e9603",
"next_page_uri": null
}
3. Find available local phone numbers by region
Find available Local
phone numbers in Ontario
.
Request
curl "https://api.somleng.org/2010-04-01/Accounts/c2e0f89c-44d1-4697-a78c-29fc3c76870b/AvailablePhoneNumbers/CA/Local?InRegion=ON" \
-u c2e0f89c-44d1-4697-a78c-29fc3c76870b:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/c2e0f89c-44d1-4697-a78c-29fc3c76870b/AvailablePhoneNumbers/CA/Local?InRegion=ON
Parameters
{
"InRegion": "ON"
}
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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
Response
200 OK
{
"available_phone_numbers": [
{
"friendly_name": "+1 (647) 309-5500",
"phone_number": "+16473095500",
"lata": null,
"rate_center": null,
"latitude": null,
"longitude": null,
"locality": null,
"region": "ON",
"postal_code": null,
"iso_country": "CA",
"address_requirements": "none",
"beta": false,
"capabilities": {
"voice": true,
"SMS": true,
"MMS": false
}
}
],
"uri": "/2010-04-01/Accounts/c2e0f89c-44d1-4697-a78c-29fc3c76870b/AvailablePhoneNumbers/CA/Local?InRegion=ON",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/c2e0f89c-44d1-4697-a78c-29fc3c76870b/AvailablePhoneNumbers/CA/Local?InRegion=ON&Page=0",
"previous_page_uri": "/2010-04-01/Accounts/c2e0f89c-44d1-4697-a78c-29fc3c76870b/AvailablePhoneNumbers/CA/Local?InRegion=ON&Page=0&PageToken=PB325a6c79-1fb9-4d69-a51c-afbb3eec4c25",
"next_page_uri": null
}
4. Find available local phone numbers by locality
Find available Local
phone numbers in Toronto
.
Request
curl "https://api.somleng.org/2010-04-01/Accounts/45f5c3b0-19f2-45a5-9434-404ec89d9010/AvailablePhoneNumbers/CA/Local?InLocality=Toronto" \
-u 45f5c3b0-19f2-45a5-9434-404ec89d9010:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/45f5c3b0-19f2-45a5-9434-404ec89d9010/AvailablePhoneNumbers/CA/Local?InLocality=Toronto
Parameters
{
"InLocality": "Toronto"
}
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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
Response
200 OK
{
"available_phone_numbers": [
{
"friendly_name": "+1 (647) 309-5500",
"phone_number": "+16473095500",
"lata": null,
"rate_center": null,
"latitude": null,
"longitude": null,
"locality": "Toronto",
"region": "ON",
"postal_code": null,
"iso_country": "CA",
"address_requirements": "none",
"beta": false,
"capabilities": {
"voice": true,
"SMS": true,
"MMS": false
}
}
],
"uri": "/2010-04-01/Accounts/45f5c3b0-19f2-45a5-9434-404ec89d9010/AvailablePhoneNumbers/CA/Local?InLocality=Toronto",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/45f5c3b0-19f2-45a5-9434-404ec89d9010/AvailablePhoneNumbers/CA/Local?InLocality=Toronto&Page=0",
"previous_page_uri": "/2010-04-01/Accounts/45f5c3b0-19f2-45a5-9434-404ec89d9010/AvailablePhoneNumbers/CA/Local?InLocality=Toronto&Page=0&PageToken=PBa6f620db-de1d-43f4-a994-e030473475a5",
"next_page_uri": null
}
5. 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/898f35a4-c04d-4893-9549-00324af3b1d3/AvailablePhoneNumbers/CA/Mobile" \
-u 898f35a4-c04d-4893-9549-00324af3b1d3:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/898f35a4-c04d-4893-9549-00324af3b1d3/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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
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/898f35a4-c04d-4893-9549-00324af3b1d3/AvailablePhoneNumbers/CA/Mobile",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/898f35a4-c04d-4893-9549-00324af3b1d3/AvailablePhoneNumbers/CA/Mobile?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/898f35a4-c04d-4893-9549-00324af3b1d3/AvailablePhoneNumbers/CA/Mobile?Page=0&PageToken=PB2c6dbc4b-bd16-4182-b834-b19c5c3b71c6",
"next_page_uri": null
}
6. 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/496ed9b7-45db-47e6-ba04-bfb19ea4954c/AvailablePhoneNumbers/CA/TollFree" \
-u 496ed9b7-45db-47e6-ba04-bfb19ea4954c:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/496ed9b7-45db-47e6-ba04-bfb19ea4954c/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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
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/496ed9b7-45db-47e6-ba04-bfb19ea4954c/AvailablePhoneNumbers/CA/TollFree",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/496ed9b7-45db-47e6-ba04-bfb19ea4954c/AvailablePhoneNumbers/CA/TollFree?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/496ed9b7-45db-47e6-ba04-bfb19ea4954c/AvailablePhoneNumbers/CA/TollFree?Page=0&PageToken=PB5ad045fd-1c3e-4d5b-8432-ac7ff8f17d97",
"next_page_uri": null
}
7. 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/4f422437-3102-41ad-a6f7-b22bbbf770e4/AvailablePhoneNumbers/CA/ShortCode" \
-u 4f422437-3102-41ad-a6f7-b22bbbf770e4:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode/:Type
GET https://api.somleng.org/2010-04-01/Accounts/4f422437-3102-41ad-a6f7-b22bbbf770e4/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. |
InRegion | Query Parameter: Limit results to a particular region, state, or province. |
InLocality | Query Parameter: Limit results to a particular locality or city. |
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/4f422437-3102-41ad-a6f7-b22bbbf770e4/AvailablePhoneNumbers/CA/ShortCode",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/4f422437-3102-41ad-a6f7-b22bbbf770e4/AvailablePhoneNumbers/CA/ShortCode?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/4f422437-3102-41ad-a6f7-b22bbbf770e4/AvailablePhoneNumbers/CA/ShortCode?Page=0&PageToken=PBb9445769-5772-496e-aab3-7ce22a14269c",
"next_page_uri": null
}
8. 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/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers" \
-u 751a8bf3-36f5-41dd-97cc-b1dfad1e3252:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers
GET https://api.somleng.org/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/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/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/CA",
"beta": false,
"subresource_uris": {
"short_code": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/CA/ShortCode",
"local": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/CA/Local",
"mobile": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/CA/Mobile",
"toll_free": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/CA/TollFree"
}
},
{
"country_code": "KH",
"country": "Cambodia",
"uri": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/KH",
"beta": false,
"subresource_uris": {
"short_code": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/KH/ShortCode",
"local": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/KH/Local",
"mobile": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/KH/Mobile",
"toll_free": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers/KH/TollFree"
}
}
],
"uri": "/2010-04-01/Accounts/751a8bf3-36f5-41dd-97cc-b1dfad1e3252/AvailablePhoneNumbers"
}
9. 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/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/AvailablePhoneNumbers/CA" \
-u 59d3e6af-98d9-46ee-9551-f2cc9f9bf768:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/AvailablePhoneNumbers/:CountryCode
GET https://api.somleng.org/2010-04-01/Accounts/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/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/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/AvailablePhoneNumbers/CA",
"beta": false,
"subresource_uris": {
"short_code": "/2010-04-01/Accounts/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/AvailablePhoneNumbers/CA/ShortCode",
"local": "/2010-04-01/Accounts/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/AvailablePhoneNumbers/CA/Local",
"mobile": "/2010-04-01/Accounts/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/AvailablePhoneNumbers/CA/Mobile",
"toll_free": "/2010-04-01/Accounts/59d3e6af-98d9-46ee-9551-f2cc9f9bf768/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/527ac622-9d60-42a7-b6a0-92d19f81870f/IncomingPhoneNumbers" \
-u 527ac622-9d60-42a7-b6a0-92d19f81870f: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/527ac622-9d60-42a7-b6a0-92d19f81870f/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": "9d8891b8-6f79-449b-b443-64a8e4b4e1e9",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "527ac622-9d60-42a7-b6a0-92d19f81870f",
"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/527ac622-9d60-42a7-b6a0-92d19f81870f/IncomingPhoneNumbers/9d8891b8-6f79-449b-b443-64a8e4b4e1e9",
"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/35559f7b-a8c8-4061-9acb-36c06ee6b2a7/IncomingPhoneNumbers" \
-u 35559f7b-a8c8-4061-9acb-36c06ee6b2a7: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/35559f7b-a8c8-4061-9acb-36c06ee6b2a7/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": "2da27dc3-0a74-409d-bbb5-6c0fd0279b9d",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "35559f7b-a8c8-4061-9acb-36c06ee6b2a7",
"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/35559f7b-a8c8-4061-9acb-36c06ee6b2a7/IncomingPhoneNumbers/2da27dc3-0a74-409d-bbb5-6c0fd0279b9d",
"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/9f515ae0-2f82-4b71-814d-cfe2a9baec12/IncomingPhoneNumbers" \
-u 9f515ae0-2f82-4b71-814d-cfe2a9baec12: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/9f515ae0-2f82-4b71-814d-cfe2a9baec12/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": "921945fd-b034-4d45-9d71-fa9952f59065",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "9f515ae0-2f82-4b71-814d-cfe2a9baec12",
"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/9f515ae0-2f82-4b71-814d-cfe2a9baec12/IncomingPhoneNumbers/921945fd-b034-4d45-9d71-fa9952f59065",
"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/0dba0bd8-c179-4100-9653-7609ae98b9d6/IncomingPhoneNumbers/4fb14952-5729-43a3-a681-0c2f6bed271a" \
-u 0dba0bd8-c179-4100-9653-7609ae98b9d6:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers/:Sid
GET https://api.somleng.org/2010-04-01/Accounts/0dba0bd8-c179-4100-9653-7609ae98b9d6/IncomingPhoneNumbers/4fb14952-5729-43a3-a681-0c2f6bed271a
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": "4fb14952-5729-43a3-a681-0c2f6bed271a",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "0dba0bd8-c179-4100-9653-7609ae98b9d6",
"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/0dba0bd8-c179-4100-9653-7609ae98b9d6/IncomingPhoneNumbers/4fb14952-5729-43a3-a681-0c2f6bed271a",
"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/9db56925-f1a2-401e-9ffe-bca081925ac6/IncomingPhoneNumbers?PhoneNumber=%2B12513095500" \
-u 9db56925-f1a2-401e-9ffe-bca081925ac6:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers
GET https://api.somleng.org/2010-04-01/Accounts/9db56925-f1a2-401e-9ffe-bca081925ac6/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": "43b63884-aa70-4c09-bfd1-ed1a5e3fa825",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "9db56925-f1a2-401e-9ffe-bca081925ac6",
"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/9db56925-f1a2-401e-9ffe-bca081925ac6/IncomingPhoneNumbers/43b63884-aa70-4c09-bfd1-ed1a5e3fa825",
"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/9db56925-f1a2-401e-9ffe-bca081925ac6/IncomingPhoneNumbers?PhoneNumber=%2B12513095500",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/9db56925-f1a2-401e-9ffe-bca081925ac6/IncomingPhoneNumbers?Page=0&PhoneNumber=%2B12513095500",
"previous_page_uri": "/2010-04-01/Accounts/9db56925-f1a2-401e-9ffe-bca081925ac6/IncomingPhoneNumbers?Page=0&PageToken=PB43b63884-aa70-4c09-bfd1-ed1a5e3fa825&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/4dab9319-d9d8-40fd-b7fc-140d63d270f4/IncomingPhoneNumbers/09a705cc-3c2f-4b64-a75d-3ef010cfe95d" \
-u 4dab9319-d9d8-40fd-b7fc-140d63d270f4: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/4dab9319-d9d8-40fd-b7fc-140d63d270f4/IncomingPhoneNumbers/09a705cc-3c2f-4b64-a75d-3ef010cfe95d
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": "09a705cc-3c2f-4b64-a75d-3ef010cfe95d",
"date_created": "Tue, 01 Oct 2024 06:10:15 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:15 -0000",
"account_sid": "4dab9319-d9d8-40fd-b7fc-140d63d270f4",
"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 5726",
"identity_sid": null,
"origin": "hosted",
"phone_number": "+855972345726",
"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/4dab9319-d9d8-40fd-b7fc-140d63d270f4/IncomingPhoneNumbers/09a705cc-3c2f-4b64-a75d-3ef010cfe95d",
"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/c5c9fab9-64a8-4f27-820e-ca824614746f/IncomingPhoneNumbers/6e305a9d-2859-48e5-a632-3d1d7ed9e97b" -d '' -X DELETE \
-u c5c9fab9-64a8-4f27-820e-ca824614746f: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/c5c9fab9-64a8-4f27-820e-ca824614746f/IncomingPhoneNumbers/6e305a9d-2859-48e5-a632-3d1d7ed9e97b
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
Deletes a message record from your account. Once the record is deleted, it will no longer appear in the API and Account Portal logs.
If successful, returns HTTP 204
(No Content) with no body.
Attempting to delete an in-progress message record will result in an error.
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/cd9adda8-6387-4b40-b1d0-ec38da70322f/Messages" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u cd9adda8-6387-4b40-b1d0-ec38da70322f: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/cd9adda8-6387-4b40-b1d0-ec38da70322f/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": "affd8cc7-f6c7-432a-8565-3fa8bd0ecffd",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "cd9adda8-6387-4b40-b1d0-ec38da70322f",
"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/cd9adda8-6387-4b40-b1d0-ec38da70322f/Messages/affd8cc7-f6c7-432a-8565-3fa8bd0ecffd"
}
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/99823790-3e31-44a7-80bf-dd8af9aba237/Messages" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 99823790-3e31-44a7-80bf-dd8af9aba237:AuthToken \
--data-urlencode "To=+855716788123" \
--data-urlencode "MessagingServiceSid=ef36a3e9-94b7-4005-bbf8-409d1cf44d6a" \
--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/99823790-3e31-44a7-80bf-dd8af9aba237/Messages
Parameters
{
"To": "+855716788123",
"MessagingServiceSid": "ef36a3e9-94b7-4005-bbf8-409d1cf44d6a",
"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": "e4dfec8f-6de7-433f-9669-154866a6d24c",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "99823790-3e31-44a7-80bf-dd8af9aba237",
"body": "Hello World",
"date_sent": null,
"direction": "outbound-api",
"error_code": null,
"error_message": null,
"from": null,
"messaging_service_sid": "ef36a3e9-94b7-4005-bbf8-409d1cf44d6a",
"num_media": "0",
"num_segments": "1",
"price": null,
"price_unit": null,
"status": "accepted",
"subresource_uris": {
},
"tags": {
},
"to": "+855716788123",
"uri": "/2010-04-01/Accounts/99823790-3e31-44a7-80bf-dd8af9aba237/Messages/e4dfec8f-6de7-433f-9669-154866a6d24c"
}
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/5c928443-884c-4055-bde5-fb417a913693/Messages" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 5c928443-884c-4055-bde5-fb417a913693:AuthToken \
--data-urlencode "To=+855716788123" \
--data-urlencode "Body=Hello World" \
--data-urlencode "SendAt=2024-10-06T06:10:23Z" \
--data-urlencode "ScheduleType=fixed" \
--data-urlencode "MessagingServiceSid=0fad9d75-87a2-4a95-ae4d-36c50acc51e6"
Endpoint
POST https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages
POST https://api.somleng.org/2010-04-01/Accounts/5c928443-884c-4055-bde5-fb417a913693/Messages
Parameters
{
"To": "+855716788123",
"Body": "Hello World",
"SendAt": "2024-10-06T06:10:23Z",
"ScheduleType": "fixed",
"MessagingServiceSid": "0fad9d75-87a2-4a95-ae4d-36c50acc51e6"
}
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": "eda60ba0-c442-40e2-8ea2-d69429359896",
"date_created": "Tue, 01 Oct 2024 06:10:23 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:23 -0000",
"account_sid": "5c928443-884c-4055-bde5-fb417a913693",
"body": "Hello World",
"date_sent": null,
"direction": "outbound-api",
"error_code": null,
"error_message": null,
"from": null,
"messaging_service_sid": "0fad9d75-87a2-4a95-ae4d-36c50acc51e6",
"num_media": "0",
"num_segments": "1",
"price": null,
"price_unit": null,
"status": "scheduled",
"subresource_uris": {
},
"tags": {
},
"to": "+855716788123",
"uri": "/2010-04-01/Accounts/5c928443-884c-4055-bde5-fb417a913693/Messages/eda60ba0-c442-40e2-8ea2-d69429359896"
}
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/683658e7-d700-4002-bcaa-a327d9a87453/Messages/7f05eca1-ad2e-40a4-aa60-2fcc101b0055" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 683658e7-d700-4002-bcaa-a327d9a87453:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid
GET https://api.somleng.org/2010-04-01/Accounts/683658e7-d700-4002-bcaa-a327d9a87453/Messages/7f05eca1-ad2e-40a4-aa60-2fcc101b0055
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": "7f05eca1-ad2e-40a4-aa60-2fcc101b0055",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "683658e7-d700-4002-bcaa-a327d9a87453",
"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/683658e7-d700-4002-bcaa-a327d9a87453/Messages/7f05eca1-ad2e-40a4-aa60-2fcc101b0055"
}
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/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/Messages" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages
GET https://api.somleng.org/2010-04-01/Accounts/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/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": "f319b45e-ce38-468c-a356-90f6b2ddc97b",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df",
"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/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/Messages/f319b45e-ce38-468c-a356-90f6b2ddc97b"
}
],
"uri": "/2010-04-01/Accounts/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/Messages",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/Messages?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/27d8e0e1-bf2c-4f11-b0a0-904b14e2f9df/Messages?Page=0&PageToken=PBf319b45e-ce38-468c-a356-90f6b2ddc97b",
"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/44f76508-59e5-45ab-9ff2-228658b66795/Messages/9a7fe8ec-1910-4da6-a8b0-8acb3e27b9c4" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 44f76508-59e5-45ab-9ff2-228658b66795: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/44f76508-59e5-45ab-9ff2-228658b66795/Messages/9a7fe8ec-1910-4da6-a8b0-8acb3e27b9c4
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": "9a7fe8ec-1910-4da6-a8b0-8acb3e27b9c4",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "44f76508-59e5-45ab-9ff2-228658b66795",
"body": "",
"date_sent": "Tue, 01 Oct 2024 06:10:24 -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/44f76508-59e5-45ab-9ff2-228658b66795/Messages/9a7fe8ec-1910-4da6-a8b0-8acb3e27b9c4"
}
7. Cancel a scheduled message
Before you use this functionality:
- Ensure the status value of canceled is spelled with one "l", (canceled) and not two (cancelled).
- Ensure that you store the
MessageSid
of the messages you schedule. You need to reference theMessageSid
for each message cancelation request. - 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
. - There is a new status callback event for
Canceled
. You can continue to receive existing callback events by including the optionalStatusCallBack
parameter in the message request.
Request
curl -X POST "https://api.somleng.org/2010-04-01/Accounts/5978ed65-a42b-4046-a130-e7d7a6c5a828/Messages/29994c91-4b32-4c81-b11d-c43b930dd17e" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 5978ed65-a42b-4046-a130-e7d7a6c5a828: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/5978ed65-a42b-4046-a130-e7d7a6c5a828/Messages/29994c91-4b32-4c81-b11d-c43b930dd17e
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": "29994c91-4b32-4c81-b11d-c43b930dd17e",
"date_created": "Tue, 01 Oct 2024 06:10:24 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:24 -0000",
"account_sid": "5978ed65-a42b-4046-a130-e7d7a6c5a828",
"body": "Hello World",
"date_sent": null,
"direction": "outbound-api",
"error_code": null,
"error_message": null,
"from": null,
"messaging_service_sid": "ed3c5c52-5d44-454a-9543-c08586712e68",
"num_media": "0",
"num_segments": "1",
"price": null,
"price_unit": null,
"status": "canceled",
"subresource_uris": {
},
"tags": {
},
"to": "+85512334667",
"uri": "/2010-04-01/Accounts/5978ed65-a42b-4046-a130-e7d7a6c5a828/Messages/29994c91-4b32-4c81-b11d-c43b930dd17e"
}
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/3f215608-d5d0-4c44-8768-cb90ac7b63b9/Messages/d34b2e27-f605-428b-92ca-75fc6eab7605" -d '' -X DELETE \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 3f215608-d5d0-4c44-8768-cb90ac7b63b9:AuthToken
Endpoint
DELETE https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Messages/:Sid
DELETE https://api.somleng.org/2010-04-01/Accounts/3f215608-d5d0-4c44-8768-cb90ac7b63b9/Messages/d34b2e27-f605-428b-92ca-75fc6eab7605
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/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls?PageSize=2" \
-u a510f527-b79a-4b56-bb18-f2f3876f978b:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls
GET https://api.somleng.org/2010-04-01/Accounts/a510f527-b79a-4b56-bb18-f2f3876f978b/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": "e20c4812-9827-4ad9-a6a6-488bd8351628",
"date_created": "Tue, 01 Oct 2024 06:10:30 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:30 -0000",
"account_sid": "a510f527-b79a-4b56-bb18-f2f3876f978b",
"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/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls/e20c4812-9827-4ad9-a6a6-488bd8351628"
},
{
"api_version": "2010-04-01",
"sid": "b6a35353-b9c1-4d86-b8c7-f0ce28f6fceb",
"date_created": "Tue, 01 Oct 2024 06:10:30 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:30 -0000",
"account_sid": "a510f527-b79a-4b56-bb18-f2f3876f978b",
"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/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls/b6a35353-b9c1-4d86-b8c7-f0ce28f6fceb"
}
],
"uri": "/2010-04-01/Accounts/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls?PageSize=2",
"page": 0,
"page_size": 2,
"first_page_uri": "/2010-04-01/Accounts/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls?Page=0&PageSize=2",
"previous_page_uri": "/2010-04-01/Accounts/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls?Page=0&PageSize=2&PageToken=PBe20c4812-9827-4ad9-a6a6-488bd8351628",
"next_page_uri": "/2010-04-01/Accounts/a510f527-b79a-4b56-bb18-f2f3876f978b/Calls?Page=1&PageSize=2&PageToken=PAb6a35353-b9c1-4d86-b8c7-f0ce28f6fceb"
}
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/d932e254-cf83-4c9f-a4bb-c7dcbfc90cbf/Calls" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u d932e254-cf83-4c9f-a4bb-c7dcbfc90cbf: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/d932e254-cf83-4c9f-a4bb-c7dcbfc90cbf/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": "c547012c-55b5-4c71-8009-9091657d5394",
"date_created": "Tue, 01 Oct 2024 06:10:51 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:51 -0000",
"account_sid": "d932e254-cf83-4c9f-a4bb-c7dcbfc90cbf",
"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": "59bd92b0-eaab-416d-8baf-624b046e4815",
"price": null,
"price_unit": null,
"start_time": null,
"status": "queued",
"subresource_uris": {
},
"to": "+299221234",
"to_formatted": "+299 22 1234",
"uri": "/2010-04-01/Accounts/d932e254-cf83-4c9f-a4bb-c7dcbfc90cbf/Calls/c547012c-55b5-4c71-8009-9091657d5394"
}
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/ba04567d-36fd-400c-a73e-19a1d5f335c4/Calls/0c170dcd-4749-4e53-95ff-6f9a23ba514f" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u ba04567d-36fd-400c-a73e-19a1d5f335c4:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:Sid
GET https://api.somleng.org/2010-04-01/Accounts/ba04567d-36fd-400c-a73e-19a1d5f335c4/Calls/0c170dcd-4749-4e53-95ff-6f9a23ba514f
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": "0c170dcd-4749-4e53-95ff-6f9a23ba514f",
"date_created": "Tue, 01 Oct 2024 06:10:50 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:50 -0000",
"account_sid": "ba04567d-36fd-400c-a73e-19a1d5f335c4",
"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/ba04567d-36fd-400c-a73e-19a1d5f335c4/Calls/0c170dcd-4749-4e53-95ff-6f9a23ba514f"
}
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/1643369d-116d-4026-9c57-c9beb5d0fa8e/Calls" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 1643369d-116d-4026-9c57-c9beb5d0fa8e:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls
GET https://api.somleng.org/2010-04-01/Accounts/1643369d-116d-4026-9c57-c9beb5d0fa8e/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": "d8faf298-778c-4405-950e-b04a1cb4cfda",
"date_created": "Tue, 01 Oct 2024 06:10:51 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:51 -0000",
"account_sid": "1643369d-116d-4026-9c57-c9beb5d0fa8e",
"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/1643369d-116d-4026-9c57-c9beb5d0fa8e/Calls/d8faf298-778c-4405-950e-b04a1cb4cfda"
}
],
"uri": "/2010-04-01/Accounts/1643369d-116d-4026-9c57-c9beb5d0fa8e/Calls",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/1643369d-116d-4026-9c57-c9beb5d0fa8e/Calls?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/1643369d-116d-4026-9c57-c9beb5d0fa8e/Calls?Page=0&PageToken=PBd8faf298-778c-4405-950e-b04a1cb4cfda",
"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/cba006cb-9cd0-421b-a6e9-52b9b92724ec/Calls/a0837af4-666f-4d05-8f30-181fe19c89aa" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u cba006cb-9cd0-421b-a6e9-52b9b92724ec: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/cba006cb-9cd0-421b-a6e9-52b9b92724ec/Calls/a0837af4-666f-4d05-8f30-181fe19c89aa
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": "a0837af4-666f-4d05-8f30-181fe19c89aa",
"date_created": "Tue, 01 Oct 2024 06:10:50 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:50 -0000",
"account_sid": "cba006cb-9cd0-421b-a6e9-52b9b92724ec",
"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/cba006cb-9cd0-421b-a6e9-52b9b92724ec/Calls/a0837af4-666f-4d05-8f30-181fe19c89aa"
}
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/f7c4c22b-34a1-459a-baba-a5fcfbc2f0fa/Calls/a63f64f0-1a99-49b6-837d-66ca63812baa" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u f7c4c22b-34a1-459a-baba-a5fcfbc2f0fa: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/f7c4c22b-34a1-459a-baba-a5fcfbc2f0fa/Calls/a63f64f0-1a99-49b6-837d-66ca63812baa
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": "a63f64f0-1a99-49b6-837d-66ca63812baa",
"date_created": "Tue, 01 Oct 2024 06:10:51 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:51 -0000",
"account_sid": "f7c4c22b-34a1-459a-baba-a5fcfbc2f0fa",
"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/f7c4c22b-34a1-459a-baba-a5fcfbc2f0fa/Calls/a63f64f0-1a99-49b6-837d-66ca63812baa"
}
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/92a63675-8b93-43cc-8f18-81a499f13b5a/Calls/b3c0af0c-fd04-4553-858e-ab6759e53bf1" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u 92a63675-8b93-43cc-8f18-81a499f13b5a: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/92a63675-8b93-43cc-8f18-81a499f13b5a/Calls/b3c0af0c-fd04-4553-858e-ab6759e53bf1
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": "b3c0af0c-fd04-4553-858e-ab6759e53bf1",
"date_created": "Tue, 01 Oct 2024 06:10:50 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:50 -0000",
"account_sid": "92a63675-8b93-43cc-8f18-81a499f13b5a",
"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/92a63675-8b93-43cc-8f18-81a499f13b5a/Calls/b3c0af0c-fd04-4553-858e-ab6759e53bf1"
}
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/d755e7fa-9b74-491a-80ae-842d58771d46/Recordings/bfca2bec-2d59-49a2-bbf5-2837a471f191"
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid
GET https://api.somleng.org/2010-04-01/Accounts/d755e7fa-9b74-491a-80ae-842d58771d46/Recordings/bfca2bec-2d59-49a2-bbf5-2837a471f191
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/6a7e216f-ea14-419c-a0d2-b805ae7d5bd0/Recordings/0b9eded7-9cd1-42da-9a39-6f88a7df1a61.mp3"
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid.mp3
GET https://api.somleng.org/2010-04-01/Accounts/6a7e216f-ea14-419c-a0d2-b805ae7d5bd0/Recordings/0b9eded7-9cd1-42da-9a39-6f88a7df1a61.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/c223d652-3089-4b89-b990-33f47a2d8791/Recordings/14b1816a-d13d-4c48-b13f-161ef33553c5.json"
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings/:Sid.json
GET https://api.somleng.org/2010-04-01/Accounts/c223d652-3089-4b89-b990-33f47a2d8791/Recordings/14b1816a-d13d-4c48-b13f-161ef33553c5.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": "14b1816a-d13d-4c48-b13f-161ef33553c5",
"date_created": "Tue, 01 Oct 2024 06:10:58 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:58 -0000",
"account_sid": "c223d652-3089-4b89-b990-33f47a2d8791",
"call_sid": "dc09bf54-2c7c-40d5-9dc2-d62f8421dece",
"conference_sid": null,
"channels": 1,
"start_time": "2024-10-01T06:10:58.432Z",
"duration": null,
"price": null,
"price_unit": null,
"source": "RecordVerb",
"status": "processing",
"error_code": null,
"encryption_details": null,
"track": "both",
"uri": "/2010-04-01/Accounts/c223d652-3089-4b89-b990-33f47a2d8791/Calls/dc09bf54-2c7c-40d5-9dc2-d62f8421dece/Recordings/14b1816a-d13d-4c48-b13f-161ef33553c5.json"
}
4. Get all recordings for a given call
Request
curl "https://api.somleng.org/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/Recordings" \
-u 007f3bc9-b797-451e-a822-00b958631774:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Calls/:CallSid/Recordings
GET https://api.somleng.org/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/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": "bc0b36c7-96e7-4aff-9393-aeaf0d0525ab",
"date_created": "Tue, 01 Oct 2024 06:10:58 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:58 -0000",
"account_sid": "007f3bc9-b797-451e-a822-00b958631774",
"call_sid": "3a422834-e216-4d0b-9608-56b55fe7c479",
"conference_sid": null,
"channels": 1,
"start_time": "2024-10-01T06:10:58.473Z",
"duration": "0",
"price": null,
"price_unit": null,
"source": "RecordVerb",
"status": "completed",
"error_code": null,
"encryption_details": null,
"track": "both",
"uri": "/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/Recordings/bc0b36c7-96e7-4aff-9393-aeaf0d0525ab.json"
}
],
"uri": "/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/Recordings",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/Recordings?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/007f3bc9-b797-451e-a822-00b958631774/Calls/3a422834-e216-4d0b-9608-56b55fe7c479/Recordings?Page=0&PageToken=PBbc0b36c7-96e7-4aff-9393-aeaf0d0525ab",
"next_page_uri": null
}
5. List recordings by account
Request
curl "https://api.somleng.org/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Recordings" \
-u 8f630e2c-ca2e-4b54-9746-9b94323c3b55:AuthToken
Endpoint
GET https://api.somleng.org/2010-04-01/Accounts/:AccountSid/Recordings
GET https://api.somleng.org/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/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": "19280d85-3c91-464f-bfea-6ea3eaa1a395",
"date_created": "Tue, 01 Oct 2024 06:10:57 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:57 -0000",
"account_sid": "8f630e2c-ca2e-4b54-9746-9b94323c3b55",
"call_sid": "b5777360-0d18-4b8f-a98b-3ed91095818a",
"conference_sid": null,
"channels": 1,
"start_time": "2024-10-01T06:10:57.369Z",
"duration": null,
"price": null,
"price_unit": null,
"source": "RecordVerb",
"status": "processing",
"error_code": null,
"encryption_details": null,
"track": "both",
"uri": "/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Calls/b5777360-0d18-4b8f-a98b-3ed91095818a/Recordings/19280d85-3c91-464f-bfea-6ea3eaa1a395.json"
},
{
"api_version": "2010-04-01",
"sid": "73e2fddc-436b-4f0e-8cd1-077158d170bd",
"date_created": "Tue, 01 Oct 2024 06:10:57 -0000",
"date_updated": "Tue, 01 Oct 2024 06:10:57 -0000",
"account_sid": "8f630e2c-ca2e-4b54-9746-9b94323c3b55",
"call_sid": "3b5f4043-0593-4f43-9ccd-29073d064e69",
"conference_sid": null,
"channels": 1,
"start_time": "2024-10-01T06:10:57.346Z",
"duration": null,
"price": null,
"price_unit": null,
"source": "RecordVerb",
"status": "processing",
"error_code": null,
"encryption_details": null,
"track": "both",
"uri": "/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Calls/3b5f4043-0593-4f43-9ccd-29073d064e69/Recordings/73e2fddc-436b-4f0e-8cd1-077158d170bd.json"
}
],
"uri": "/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Recordings",
"page": 0,
"page_size": 50,
"first_page_uri": "/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Recordings?Page=0",
"previous_page_uri": "/2010-04-01/Accounts/8f630e2c-ca2e-4b54-9746-9b94323c3b55/Recordings?Page=0&PageToken=PB19280d85-3c91-464f-bfea-6ea3eaa1a395",
"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 b59a150f-f0bd-4c44-8915-9b35074f08f3: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": "32d69c8e-9143-4bcd-b37b-82ce7e146daf",
"account_sid": "b59a150f-f0bd-4c44-8915-9b35074f08f3",
"date_created": "2024-10-01T06:10:06Z",
"date_updated": "2024-10-01T06:10:06Z",
"friendly_name": "My Verification Service",
"url": "http://verify.lvh.me/v2/Services/32d69c8e-9143-4bcd-b37b-82ce7e146daf",
"code_length": 6
}
2. Fetch a Service
Request
curl "https://verify.somleng.org/v2/Services/a80ffd0f-dae2-4381-9609-43a2745f762f" \
-u d09f5325-fd8d-423b-ad33-ab79211f9788:AuthToken
Endpoint
GET https://verify.somleng.org/v2/Services/:Sid
GET https://verify.somleng.org/v2/Services/a80ffd0f-dae2-4381-9609-43a2745f762f
Parameters
Name | Description |
---|---|
Sid | Path Parameter: The SID of the Verification Service to fetch. |
Response
200 OK
{
"sid": "a80ffd0f-dae2-4381-9609-43a2745f762f",
"account_sid": "d09f5325-fd8d-423b-ad33-ab79211f9788",
"date_created": "2024-10-01T06:10:05Z",
"date_updated": "2024-10-01T06:10:05Z",
"friendly_name": "My Verification Service",
"url": "http://verify.lvh.me/v2/Services/a80ffd0f-dae2-4381-9609-43a2745f762f",
"code_length": 4
}
3. List all Services
Request
curl "https://verify.somleng.org/v2/Services" \
-u d2944c24-d6a3-42be-9c39-fb1b10fb57a0:AuthToken
Endpoint
GET https://verify.somleng.org/v2/Services
GET https://verify.somleng.org/v2/Services
Parameters
None known.
Response
200 OK
{
"services": [
{
"sid": "2525a0b8-a501-430a-a2c0-22cd6f63ab1c",
"account_sid": "d2944c24-d6a3-42be-9c39-fb1b10fb57a0",
"date_created": "2024-10-01T06:10:06Z",
"date_updated": "2024-10-01T06:10:06Z",
"friendly_name": "My Verification Service",
"url": "http://verify.lvh.me/v2/Services/2525a0b8-a501-430a-a2c0-22cd6f63ab1c",
"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=PB2525a0b8-a501-430a-a2c0-22cd6f63ab1c",
"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/d8523028-f6c4-4714-b057-dd61652682e8" \
-u fa514bdb-457f-4629-b844-775878affdb0: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/d8523028-f6c4-4714-b057-dd61652682e8
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": "d8523028-f6c4-4714-b057-dd61652682e8",
"account_sid": "fa514bdb-457f-4629-b844-775878affdb0",
"date_created": "2024-10-01T06:10:05Z",
"date_updated": "2024-10-01T06:10:05Z",
"friendly_name": "Rocket Ride Service",
"url": "http://verify.lvh.me/v2/Services/d8523028-f6c4-4714-b057-dd61652682e8",
"code_length": 6
}
5. Delete a Service
Request
curl "https://verify.somleng.org/v2/Services/7fe7c501-916b-4ac2-b6e0-dd435e7d6801" -d '' -X DELETE \
-u 7af595f4-f893-4e30-8cfd-5b0ed239992a: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/7fe7c501-916b-4ac2-b6e0-dd435e7d6801
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/3cc78c51-23a4-4fc9-86eb-80a99be18994/Verifications" \
-u 689c80c8-4565-4260-adeb-97558dfed194: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/3cc78c51-23a4-4fc9-86eb-80a99be18994/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 , de , es , fr , it , ja , nl , pt , ar , ca , da , fi , id , ko , pl , 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": "328b1485-428d-4b9b-a66c-ebcd3b025c43",
"account_sid": "689c80c8-4565-4260-adeb-97558dfed194",
"date_created": "2024-10-01T06:10:04Z",
"date_updated": "2024-10-01T06:10:04Z",
"service_sid": "3cc78c51-23a4-4fc9-86eb-80a99be18994",
"to": "+85512334667",
"channel": "sms",
"status": "pending",
"url": "http://verify.lvh.me/v2/Services/3cc78c51-23a4-4fc9-86eb-80a99be18994/Verifications/328b1485-428d-4b9b-a66c-ebcd3b025c43",
"send_code_attempts": [
{
"attempt_sid": "30eb66f6-e4e4-419e-a851-53e0e8b01bc1",
"channel": "sms",
"time": "2024-10-01T06:10:04Z"
}
]
}
2. Start a Verification with Voice
Request
curl -X POST "https://verify.somleng.org/v2/Services/bbb4becc-c9b0-4ad8-811b-689999d95b39/Verifications" \
-u d6ed5990-a16e-4b20-b6bf-31ec3d7611b1: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/bbb4becc-c9b0-4ad8-811b-689999d95b39/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 , de , es , fr , it , ja , nl , pt , ar , ca , da , fi , id , ko , pl , 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": "56e854a7-cc5f-4415-adc0-f90b961de636",
"account_sid": "d6ed5990-a16e-4b20-b6bf-31ec3d7611b1",
"date_created": "2024-10-01T06:10:04Z",
"date_updated": "2024-10-01T06:10:04Z",
"service_sid": "bbb4becc-c9b0-4ad8-811b-689999d95b39",
"to": "+85512334667",
"channel": "call",
"status": "pending",
"url": "http://verify.lvh.me/v2/Services/bbb4becc-c9b0-4ad8-811b-689999d95b39/Verifications/56e854a7-cc5f-4415-adc0-f90b961de636",
"send_code_attempts": [
{
"attempt_sid": "ef69863d-e054-4d6a-8c97-a3d7c5ead3a7",
"channel": "call",
"time": "2024-10-01T06:10:04Z"
}
]
}
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:
- expired (10 minutes)
- approved or canceled
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/fb3d7472-a476-446d-b02a-5ed08a06d3e6/VerificationCheck" \
-u 61d47010-d29a-4e77-a8b0-23de73b2c864: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/fb3d7472-a476-446d-b02a-5ed08a06d3e6/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": "397daa09-5998-4dfe-b1ea-80ae9a5f08cd",
"account_sid": "61d47010-d29a-4e77-a8b0-23de73b2c864",
"date_created": "2024-10-01T06:10:05Z",
"date_updated": "2024-10-01T06:10:05Z",
"service_sid": "fb3d7472-a476-446d-b02a-5ed08a06d3e6",
"to": "+85512334667",
"channel": "sms",
"status": "approved"
}
4. Check a Verification with a SID
Request
curl -X POST "https://verify.somleng.org/v2/Services/a798dfaf-c868-4231-9758-afabac0826e8/VerificationCheck" \
-u 3a0233ef-c902-4d1e-afb6-a58b1f7b8d7c:AuthToken \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "VerificationSid=4bf9455f-3e6c-4674-8652-fa3b09004340" \
--data-urlencode "Code=1234"
Endpoint
POST https://verify.somleng.org/v2/Services/:ServiceSid/VerificationCheck
POST https://verify.somleng.org/v2/Services/a798dfaf-c868-4231-9758-afabac0826e8/VerificationCheck
Parameters
{
"VerificationSid": "4bf9455f-3e6c-4674-8652-fa3b09004340",
"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": "4bf9455f-3e6c-4674-8652-fa3b09004340",
"account_sid": "3a0233ef-c902-4d1e-afb6-a58b1f7b8d7c",
"date_created": "2024-10-01T06:10:05Z",
"date_updated": "2024-10-01T06:10:05Z",
"service_sid": "a798dfaf-c868-4231-9758-afabac0826e8",
"to": "+85512334667",
"channel": "sms",
"status": "approved"
}
5. Fetch a Verification
Request
curl "https://verify.somleng.org/v2/Services/df390103-0f9e-411d-a149-61f570849420/Verifications/b62a035a-46f5-4370-be11-64d4815a126c" \
-u 738fdd23-5924-4602-b072-0399c62acc6e:AuthToken
Endpoint
GET https://verify.somleng.org/v2/Services/:ServiceSid/Verifications/:Sid
GET https://verify.somleng.org/v2/Services/df390103-0f9e-411d-a149-61f570849420/Verifications/b62a035a-46f5-4370-be11-64d4815a126c
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": "b62a035a-46f5-4370-be11-64d4815a126c",
"account_sid": "738fdd23-5924-4602-b072-0399c62acc6e",
"date_created": "2024-10-01T06:10:04Z",
"date_updated": "2024-10-01T06:10:04Z",
"service_sid": "df390103-0f9e-411d-a149-61f570849420",
"to": "+85512334667",
"channel": "sms",
"status": "pending",
"url": "http://verify.lvh.me/v2/Services/df390103-0f9e-411d-a149-61f570849420/Verifications/b62a035a-46f5-4370-be11-64d4815a126c",
"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/2900db49-5b0a-433b-b7d8-790d3ba932c1/Verifications/27209928-bf83-49fc-9414-6608f31351f1" \
-u f5df422d-538c-4159-b471-ee42df319c9d: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/2900db49-5b0a-433b-b7d8-790d3ba932c1/Verifications/27209928-bf83-49fc-9414-6608f31351f1
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": "27209928-bf83-49fc-9414-6608f31351f1",
"account_sid": "f5df422d-538c-4159-b471-ee42df319c9d",
"date_created": "2024-10-01T06:10:04Z",
"date_updated": "2024-10-01T06:10:04Z",
"service_sid": "2900db49-5b0a-433b-b7d8-790d3ba932c1",
"to": "+85512334667",
"channel": "sms",
"status": "approved",
"url": "http://verify.lvh.me/v2/Services/2900db49-5b0a-433b-b7d8-790d3ba932c1/Verifications/27209928-bf83-49fc-9414-6608f31351f1",
"send_code_attempts": [
]
}