# Welcome API Documentation Documentation is broken down into different sections based on use. ### WEB REST REQUESTS Web requests are offered using HTTP GET, HTTP POST, or HTTP Json POST, at your preference. To use Json POST, set your header to: Content-Type: application/json ```php curl https://v1.api19.com/dids/ratecenters/list \ -u 'API-Token' OR curl https://v1.api19.com/dids/ratecenters/list?key=apitoken OR curl https://v1.api19.com/dids/ratecenters/list \ -d '{key:"mykey", npa:"720"}' \ -H 'Content-Type: application/json' ``` For instance, the above request would list any areas our phone number pool covers. You can send the API token as a username/password, as a GET variable (token), or as a POST variable. ### NUMBERS / ORDERING This section gives information on listing states / ratecenters, and ordering numbers. ### MY INVENTORY Your numbers, listing them and ability to remove them, or reroute them. ### SMS / MMS Send and receive SMS / MMS message via our API. ### CALL APIS This section is dedicated to the Call API which allows you to make and receive calls via web REST API calls. ### LOOKUPS Get information about numbers via web REST calls. ### NUMBER PORTABILITY Submit port requests and review port information. ### FAXING Send and receive faxes via the API # List Areas List all Ratecenter/Cities and States ## GET Request {% hint style="info" %} {% endhint %} To retrieve rate center information, submit a GET or POST request using your API key. The API key may be provided either as a URL parameter (`key`) or via HTTP Basic Authentication. The API response includes both the city name and rate center information, allowing you to work with human-readable location data. For example, the rate center code `LSAN DA 01` corresponds to Los Angeles, CA. To obtain a list of rate centers for a specific state, send a GET or POST request to the endpoint above and include the following parameter: `state=[state_abbreviation]` Example:\ `state=CA` The API will return all available rate centers associated with the specified state. {% tabs %} {% tab title="Curl POST" %} ```php curl -X POST https://v1.api19.com/dids/ratecenters/list \ -d 'key=your-api-key' ``` {% endtab %} {% tab title="Curl GET" %} ``` curl "https://v1.api19.com/dids/ratecenters/list?key=yourkey" ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": [ { "ratecenter": "DENVER", "city": "Denver", "state": "CO" }, { "ratecenter": "DALLAS", "city": "Dallas", "state": "TX" } ] } ``` {% endtab %} {% tab title="Error Responses" %} ```json [ 'status' => 'error', 'error' => 'System error', 'code' => 'system_error' ] [ 'status' => 'error', 'error' => 'Invalid state. State must be a 2-character abbreviation.' 'code' => 'invalid_state' ] ``` {% endtab %} {% endtabs %} # List Numbers List all numbers available for specific ratecenter / state ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET/POST request with your key (in the URI as key or as http password) **Ratecenter / State search**\ You can send ratecenter=\[ratecenter] and state=\[state] **Area Code Search**\ If you would rather get by area code, you can send npa=\[areacode] **Toll Free Search**\ To request toll free, send state=tf in your request We give you the City and Ratecenter so you can get human readable data (for instance ratecenter LSAN DA 01 is actually Los Angeles: 01 as the City.
ArgumentRequiredType
stateyesstring
ratecenternostring
quantitynoint
npanoint
nxxnoint
relatednoyes
set to yes if you only want the specific area code requested and nothing else
randomnoyes
randomize numbers in response
keyyesyour API key
{% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/available/list \ -d 'ratecenter=AUSTIN' \ -d 'state=TX' \ -d 'quantity=2' \ -d 'key=your-api-key' or area code based curl -X POST https://v1.api19.com/dids/available/list \ -d 'npa=303' \ -d 'quantity=2' \ -d 'key=your-api-key' or toll free request curl -X POST https://v1.api19.com/dids/available/list \ -d 'state=tf' \ -d 'key=your-api-key' ``` {% endtab %} {% tab title="Curl Get" %} ```php curl https://v1.api19.com/dids/available/list?ratecenter=AUSTIN&state=TX&key=api_token or area code based curl https://v1.api19.com/dids/available/list?npa=720&key=api_token or a toll free request curl https://v1.api19.com/dids/available/list?state=tf&key=api_token ``` {% endtab %} {% tab title="JSON Success" %} ```json { "status": "ok", "numbers": { "17202224017": { "did": "17202224017", "number": "(720) 222-4017", "tier": 1, "price_monthly": "1.5", "price_setup": "1.5", "price_minute": "0.0075", "ratecenter": "DENVER", "state": "CO" }, "17209922019": { "did": "17209922019", "number": "(720) 992-2019", "tier": 1, "price_monthly": "1.5", "price_setup": "1.5", "price_minute": "0.0075", "ratecenter": "DENVER", "state": "CO" } }, "count": 2 } ``` {% endtab %} {% tab title="JSON Error Response" %} ```json { "status": "error", "error": "no numbers available for search", "verbose": "none" } { 'status' => 'error', 'code' => 'invalid_npa', 'message' => 'Npa is not valid' } { 'status' => 'error', 'code' => 'invalid_state', 'message' => 'State must be a valid 2-character abbreviation.' } ``` {% endtab %} {% endtabs %} # Order Numbers - No Cart Order a list of numbers ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the numbers (in the URI as key or as http password) This will immediately attempt to order numbers. You can send the dids field as either a comma list of the numbers OR a json object of the numbers
ArgumentRequiredType
didsyesint
callflownoint
faxflownoint
notesnoyour did note
keyyesapi key
{% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/order/list \ -d 'dids=3038821111,3038883333' \ -d 'callflow=444' \ -d 'notes=my+personal+numbers' \ -d 'key=your-api-key' OR curl -X POST https://v1.api19.com/dids/order/list \ -d 'dids=[3038821111,3038883333]' \ -d 'callflow=444' \ -d 'key=your-api-key' ``` {% endtab %} {% endtabs %} Responses Your cart\_order number has debugging information, if you have any issues, you can open a ticket with this number. {% tabs %} {% tab title="Success" %} ```javascript { "status": "ok", "errors": { "2133581111": "already owned", "7203791111": "already owned" }, "success": { "7203791112": "yes" }, "cart_order": "232851" } ``` {% endtab %} {% tab title="Invalid" %} ```php {'status': 'error', 'error':'system error'} { 'status' => 'error', 'code' => 'no_numbers', 'error' => 'No numbers found in dids' } { 'status' => 'error', 'code' => 'no_dids', 'message' => 'Dids are required' } { 'status' => 'error', 'code' => 'invalid_json', 'message' => 'Json in dids is invalid' } ``` {% endtab %} {% endtabs %} # Delete Numbers Delete a specific number from your account GET or POST Request ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the number (in the URI as key or as http password) This deletes your number from your account. | Argument | Required | Type | | -------- | -------- | ---- | | number | yes | int | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/delete \ -d 'number=3038821111' \ -d 'key=your-key' ``` {% endtab %} {% tab title="JSON Response Success" %} ```php { "status": "ok" } ``` {% endtab %} {% tab title="JSON Response Error" %} ```json { 'status' => 'error', 'error' => 'DID is required', 'code' => 'missing_did' } { 'status' => 'error', 'error' => 'Invalid DID', 'code' => 'invalid_did' } { 'status' => 'error', 'error' => 'Cannot find did', 'code' => 'mssing_data' } { 'status' => 'error', 'error' => 'DID does not exist', 'code' => 'missing_db' } { 'status' => 'error', 'error' => 'Number not available', 'code' => 'no_availability' } { 'status' => 'error', 'error' => 'Number not available {did}', 'code' => 'did_not_available' } ``` {% endtab %} {% endtabs %} # Change Call Forward Change call forward parameter ## GET or POST Request {% hint style="info" %} {% endhint %} This changes the call forward for a specific number.
ArgumentRequiredType
didyesyour phone number
call_forwardyesforward number
keyyesyour API key
Set your call\_forward number to 0 to disable call forwarding. Call forwarding only supported to USA destinations. {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/change/call_forward \ -d 'did=3038821111' \ -d 'call_forward=3038842222' \ -d 'key=your-key' ``` {% endtab %} {% tab title="JSON Response Success" %} ```json {"status": "ok"} ``` {% endtab %} {% tab title="JSON Response Error" %} ```json { 'status' => 'error', 'error' => '{call_forward} is not a 10digit number', 'code' => 'not_valid' } { 'status' => 'error', 'error' => 'No did found {did}', 'code' => 'no_did' } { 'status' => 'error', 'error' => 'no ownership found {did}', 'code' => 'no_owner' } { 'status' => 'error', 'error' => '{did} is a fax number. Convert to normal number first.', 'code' => 'did_fax' } { 'status' => 'error', 'error' => 'You can't forward a number to itself', 'code' => 'same_did' } ``` {% endtab %} {% endtabs %} # Vanity Tollfree - Search Search the toll free database for specific vanity numbers ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET/POST request with your key (in the URI as key or as http password) {% hint style="info" %} Set your timeout for this request higher than normal, the SMS800 database can take 60 seconds to respond {% endhint %} **Search**\ Send us search= with your request **Vanity Requests Allowed** Here are some example searches, use any area code or combination: 844\*\*\*\*\*\*\* — all 844 numbers available\ 84433\*\*\*\*\* — all 844 numbers starting with 33\ 844\*\*\*\*\*22 — all 844 numbers \ 833\*\*\*\*&&& — all 833 numbers where the last 3 numbers are repeaters\ 844\*\*\*help — all 844 numbers ending in help
ArgumentRequiredType
searchyesstring
qtyno1 - 10
{% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/tfvanity/search \ -d 'key=mykey' \ -d 'search=844*******' \ -d 'qty=10' ``` {% endtab %} {% tab title="JSON Success" %} ```json { "status": "ok", "data": { "numList": [ "8447530304", "8447530305", "8447530306", "8447530311", "8447530313", "8447530315", "8447530316", "8447530317", "8447530318", "8447530319" ] } } ``` {% endtab %} {% tab title="JSON Error Response" %} ```javascript { "status": "error", "error": "no numbers available for search", "verbose": "none" } { 'status' => 'error', 'error' => 'no search request found', 'code' => 'no_search' } { 'status' => 'error', 'error' => 'Somos {error}', 'code' => 'somos_error' } { 'status' => 'error', 'error' => 'no valid data received', 'code' => 'invalid_data' } ``` {% endtab %} {% endtabs %} # Vanity Toll Free - Order Place a vanity toll free number order ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the numbers (in the URI as key or as http password) This will immediately attempt to order numbers. You can send the dids field as either a comma list of the numbers OR a json object of the numbers | Argument | Required | Type | | -------- | -------- | ---- | | dids | yes | int | | callflow | no | int | | faxflow | no | int | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/tfvanity/order \ -d 'dids=3038821111,3038883333' \ -d 'callflow=444' \ -d 'key=your-api-key' OR curl -X POST https://v1.api19.com/dids/tfvanity/order \ -d 'dids=[3038821111,3038883333]' \ -d 'callflow=444' \ -d 'key=your-api-key' ``` {% endtab %} {% endtabs %} Responses Your cart\_order number has debugging information, if you have any issues, you can open a ticket with this number. {% tabs %} {% tab title="Success" %} ```javascript { "status": "ok", "errors": { "2133581111": "already owned", "7203791111": "already owned" }, "success": { "7203791112": "yes" }, "cart_order": "232851" } ``` {% endtab %} {% tab title="Invalid" %} ```php { "status": "error", "error": "no dids set", "verbose": "none", "code": "no_dids" } { "status": "error", "error": "no dids set", "verbose": "none", "code": "no_dids" } { 'status' => 'error', 'code' => 'no_numbers', 'error' => 'No numbers found in dids' } { 'status' => 'error', 'code' => 'no_dids', 'message' => 'Dids are required' } { 'status' => 'error', 'code' => 'invalid_json', 'message' => 'Json in dids is invalid' } ``` {% endtab %} {% endtabs %} # Toll Free Offnet Place a toll free offnet order if you have your own RespOrg ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the numbers (in the URI as key or as http password) This will immediately attempt to order numbers. You can send the dids field as either a comma list of the numbers OR a json object of the numbers | Argument | Required | Type | | -------- | -------- | -------- | | dids | yes | int | | callflow | no | int | | faxflow | no | int | | key | yes | api\_key | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/tfoffnet/order \ -d 'dids=3038821111,3038883333' \ -d 'callflow=444' \ -d 'key=your-api-key' OR curl -X POST https://v1.api19.com/dids/tfoffnet/order \ -d 'dids=[3038821111,3038883333]' \ -d 'callflow=444' \ -d 'key=your-api-key' ``` {% endtab %} {% endtabs %} Responses {% tabs %} {% tab title="Success" %} ```javascript { "status": "ok", "success": { "8003332222": "yes" }, "errors": { "8883332222": "8883332222 is already in your orders", "3334443333": "3334443333 is not a tollfree number" } } ``` {% endtab %} {% tab title="Invalid" %} ```php {'status': 'error', 'error':'system error'} { 'status' => 'error', 'code' => 'no_numbers', 'error' => 'No numbers found in dids' } { 'status' => 'error', 'code' => 'no_dids', 'message' => 'Dids are required' } { 'status' => 'error', 'code' => 'invalid_json', 'message' => 'Json in dids is invalid' } ``` {% endtab %} {% endtabs %} # Add Number to Cart Add a specific number to your cart ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the number (in the URI as key or as http password) This adds the number to your shopping cart, then you can close our your cart. | Argument | Required | Type | | -------- | -------- | ---- | | did | yes | int | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/cart/add \ -d 'did=3038821111' \ -d 'key=your-api-key' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/cart/add?did=3039921111&key=apitoken ``` {% endtab %} {% tab title="JSON Response" %} ```php {"status":"ok"} OR {"status":"error", "error":"number in cart"} ``` {% endtab %} {% endtabs %} # List Numbers in Cart List all numbers in your cart ## GET Request {% hint style="info" %} {% endhint %} Send us a GET request with your key. {% tabs %} {% tab title="Curl Post" %} ```php curl -X GET https://v1.api19.com/dids/cart/list \ -d 'key=your-api-key' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/cart/list&key=apitoken ``` {% endtab %} {% tab title="JSON Response" %} ```json {"status":"ok", "numbers": {"number":3038822211, "ratecenter":"DENVER", "STATE":"CO"} } ``` {% endtab %} {% endtabs %} # Delete Number from Cart Delete a specific number from your cart ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the number (in the URI as key or as http password) This deletes the number from your shopping cart. | Argument | Required | Type | | -------- | -------- | ---- | | number | yes | int | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/cart/delete \ -d 'number=3038821111' \ -d 'key=your-key' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/cart/delete?number=3039921111&key=apitoken ``` {% endtab %} {% tab title="JSON Response" %} ```php {"status":"ok"} OR {"status":"error", "error":"number not in cart"} ``` {% endtab %} {% endtabs %} # Complete Order Cart Order all numbers in your cart ## GET or POST Request {% hint style="info" %} {% endhint %} This will close out your cart and return success/fails. The call flow and fax flow options are not required, if you omit it, the system will use your default call flow. | Argument | Required | Type | | -------------- | -------- | -------- | | call\_flow\_id | no | int | | fax\_flow\_id | no | int | | key | yes | api\_key | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/cart/complete \ -d 'call_flow_id=call_flow_id' \ -d 'key=api_key' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/cart/complete&callflow=callflowid&key=apitoken ``` {% endtab %} {% tab title="JSON Response" %} ```php { "status": "ok", "data": { "success": [ 7208017777 ], "errors": [ 7209998888 ], "verbose_errors": [ "7209998888 - failed p data check" ] } } ``` {% endtab %} {% endtabs %} # List My Numbers List all of the numbers on your account or lookup a single number ## List All Numbers ## GET or POST Request {% hint style="info" %} {% endhint %} Get a list of all of your numbers on your account {% tabs %} {% tab title="Curl Post" %} ``` curl https://v1.api19.com/dids/my/list \ -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/my/list?key=apikey ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "dids": [ { "did": "7207742222", "call_flow": "0", "fax_flow": "1", "user_id": "177", "price_tag": "inbound_usa_fax", "number_location": "usa", "offnet_carrier": "none", "ratecenter": "DENVER", "state": "CO", "country": "US", "e911": "0", "voicemail": "0", "notes": "none", "call_forward": "0" }, { "did": "7207921111", "call_flow": "3", "fax_flow": "0", "user_id": "177", "price_tag": "inbound_usa", "number_location": "usa", "offnet_carrier": "none", "ratecenter": "DENVER", "state": "CO", "country": "US", "e911": "0", "voicemail": "2", "notes": "none", "call_forward": "0" } ] } ``` {% endtab %} {% endtabs %} ## Single Number Lookup ## GET or POST Request {% hint style="info" %} {% endhint %} {% tabs %} {% tab title="Curl Post" %} ``` curl https://v1.api19.com/dids/my/single \ -d 'key=api_token' \ -d 'did=3033033333' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/my/single?key=apikey&did=3033033333 ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": [ { "did": "7207742222", "call_flow": "0", "fax_flow": "1", "user_id": "177", "price_tag": "inbound_usa_fax", "number_location": "usa", "offnet_carrier": "none", "ratecenter": "DENVER", "state": "CO", "country": "US", "e911": "0", "voicemail": "0", "notes": "none", "call_forward": "0" } ] } OR { "status": "error", "error": "did not found" } ``` {% endtab %} {% endtabs %} # List Call Flows List all call and fax flows on account. Call and fax flows allow you to set routing decisions for your numbers and are required to attach a number to. ## GET Request {% hint style="info" %} {% endhint %} Send us a GET request with your key. {% tabs %} {% tab title="Curl Post" %} ``` curl -X GET https://v1.api19.com/dids/callflows/list \ -u 'api_token:api_token' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/callflows/list&key=apitoken \ ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "fax_flows": [ { "id": "1", "name": "FaxNums 1", "emails_json": null, "emails_allowed_in": "[\"josh@gmail.com\"]" } ] "call_flows": [ { "id": "1", "name": "Main Route", "user_id": "1", "json": "{\"dnis\":\"3424\",\"route1\":\"1.1.1.1\",\"sip_port1\":5060,\"route1_wait\":30,\"wait\":30,\"route2\":\"2.2.2.2\",\"sip_port2\":5060,\"route2_wait\":30}", "e164": "no" }, { "id": "3", "name": "LA Servers", "user_id": "1", "json": "{\"route1\":\"device:694\",\"route1_wait\":13,\"sip_port1\":5060,\"wait\":13,\"dnis\":\"\",\"route2\":\"5.5.5.5\",\"sip_port2\":5060,\"route2_wait\":13,\"route1_simul\":\"device:1\"}", "e164": "no" } ] } ``` {% endtab %} {% endtabs %} # Update Call Flow Change the routing features of a call flow. ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the numbers (in the URI as key or as http password) This will immediately attempt to order numbers. You can send the dids field as either a comma list of the numbers OR a json object of the numbers
ArgumentRequiredType
call_flow_idyesint
e164yesyes or no
voicemail_boxnovoicemail box id
ip_address_1yesip you want to route calls to
ip_address_2nosecond ip address to load balance to
ip_address_3nothird ip to load balance to
ip_address_4nofourth ip to load balance to
sip_portnoalternative SIP UDP port
make_defaultnoyes or no
make this the default for the account
wait_timenoseconds to wait until call connects
{% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/callflow/update \ -d 'call_flow_id=444' \ -d 'e164=yes' \ -d 'voicemail_box=12345' \ -d 'ip_address_1=207.181.189.120' \ -d 'ip_address_2=192.168.1.100' \ -d 'ip_address_3=192.168.1.101' \ -d 'ip_address_4=192.168.1.102' \ -d 'sip_port=5060' \ -d 'make_default=no' \ -d 'key=your-api-key' ``` {% endtab %} {% endtabs %} Responses {% tabs %} {% tab title="Success" %} ```javascript { "status": "ok", } ``` {% endtab %} {% tab title="Invalid" %} ```php {'status': 'error', 'error':'ip address 1 is invalid'} ``` {% endtab %} {% endtabs %} # Create Call Flow Create a new call flow ## GET or POST Request {% hint style="info" %} {% endhint %} Send us a GET or POST request with your key and the numbers (in the URI as key or as http password) Create a call flow with a specific call flow name. | Argument | Required | Type | | -------------- | -------- | -------- | | callflow\_name | no | int | | key | yes | api\_key | {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/dids/callflow/create\ -d 'callflow_name=my+call_flow' \ -d 'key=your-api-key' ``` {% endtab %} {% endtabs %} Responses {% tabs %} {% tab title="Success" %} ```javascript {"status":"ok","call_flow_id":"31888"} Message is your newly created callflow ID ``` {% endtab %} {% tab title="Invalid" %} ```php {'status': 'error', 'error':'callflow name exists'} ``` {% endtab %} {% endtabs %} # Change Call Flow Change call flow for a specific number ## GET or POST Request {% hint style="info" %} {% endhint %} | Argument | Required | Type | | -------------- | -------- | ---- | | did | yes | int | | call\_flow\_id | yes | int | | fax\_flow\_id | no | int | Send us a POST or GET with the number and either the fax flow id or the call flow id. {% tabs %} {% tab title="Curl Post" %} ```javascript curl -X POST https://v1.api19.com/dids/callflow/change \ -d 'did=3038821111' \ -d 'call_flow_id=10' \ -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/callflow/change?number=3039921111&call_flow_id=10&key=apitoken \ ``` {% endtab %} {% tab title="JSON Response" %} ```json {"status":"ok"} OR {"status":"error", "error":"invalid callflow"} ``` {% endtab %} {% endtabs %} # Add CNAM ## GET or POST Request {% hint style="info" %} {% endhint %} Add a CNAM (Caller ID Name) request for one of your DIDs {% tabs %} {% tab title="Curl Post" %} ``` curl https://v1.api19.com/dids/cnam/add \ -d 'key=api_token' \ -d 'did=7207921111' \ -d 'cnam=COMPANY NAME' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/dids/cnam/add?key=apikey&did=7207921111&cnam=COMPANY%20NAME ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": "CNAM request added" } OR { "status": "error", "error": "Invalid DID" } OR { "status": "error", "error": "CNAM must be 15 characters or less" } ``` {% endtab %} {% endtabs %} # CDR Records Get all of the CDRs on your account ## GET or POST Request {% hint style="info" %} {% endhint %} Get a list of all of your numbers on your account You can either send the startdate and enddate or send progressive=yes to give you all of the new records since the last one you downloaded. | Argument | Required | Type | | ------------ | ---------------------- | ------------------------------------------------------------------------ | | startdate | yes unless progressive | 04/04/2024 | | enddate | yes unless progressive | 04/06/2024 | | record\_type | calls / sms | Send sms to get sms record | | add\_data | no | add\_data=yes will add additional data | | progressive | no |

progressive=yes
makes it so you don't need startdate / enddate

| | limit | no | set a limit of how many records to reply with for progressive | | key | yes | your token/key | {% tabs %} {% tab title="Curl Post" %} ```javascript curl https://v1.api19.com/cdrs/download/csv \ -d 'startdate=04/04/2024' \ -d 'enddate=04/06/2024' \ -d 'record_type=calls' \ -d 'add_data=yes' \ -d 'key=api_token' May also use record_type=sms for sms records ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/cdrs/download/csv?key=apikey&startdate=04/04/2024&enddate=04/05/2024 ``` {% endtab %} {% tab title="Calls Response" %} ``` date,your_cost,your_permin,submaster_id,user_id,submaster_cost,user_cost,submaster_permin,user_permin,billsec,src,dst,did,call_type with add_data=yes: date,your_cost,your_permin,submaster_id,user_id,submaster_cost,user_cost,submaster_permin,user_permin,billsec,src,dst,did,call_type,sip_code,sip_reason,call_sid ``` {% endtab %} {% tab title="SMS Response" %} ``` date,your_cost,surcharge,src,dst,message,direction,alpha,msg_type,uuid ``` {% endtab %} {% endtabs %} # Mass update CNAM Updates the outbound Caller ID Name (CNAM) for multiple phone numbers in a single request. The submitted phone numbers must belong to the authenticated account or to one of its associated subaccount. ``` https://v1.api19.com/dids/callflows/mass-update-cnam ``` ### Request Body | Parameter | Required | Description | | --------- | -------- | -------------------------------------------------- | | `key` | Yes | Your API token. | | `numbers` | Yes | One or more DIDs separated by commas or new lines. | | `cnam` | Yes | The Caller ID Name to apply to all valid DIDs. | #### Phone number formatting Phone numbers may be submitted using common formatting characters. The API removes non-numeric characters before validation. Accepted examples: ``` 3035550100 13035550100 (303) 555-0100 303-555-0100 ``` The API removes a leading US country code `1`, when present, and validates the remaining number as a 10-digit NANP phone number. #### CNAM formatting The `cnam` value may contain: * Uppercase letters * Lowercase letters * Numbers * Spaces Special characters are removed before the value is processed.
### JSON Request Example ``` { "numbers": "3035550100, 3035550101, 3035550102", "cnam": "CNAM" } ``` You may also separate numbers using new lines: ``` { "numbers": "3035550100\n3035550101\n3035550102", "cnam": "CNAM" } ``` ### cURL Example ``` curl https://v1.api19.com/dids/callflows/mass-update-cnam \ -d 'key=api_token' \ --data-urlencode 'numbers=3035550100 3035550101 3035550102' \ -d 'cnam=COMPANY NAME' ``` ### Successful Response The endpoint returns one result for every submitted phone number. ``` { "status": "ok", "data": [ { "number": "3035550100", "status": "ok", "message": "CNAM updated successfully" }, { "number": "3035550101", "status": "ok", "message": "CNAM updated successfully" }, { "number": "3035550102", "status": "ok", "message": "CNAM updated successfully" } ] } ``` #### Response Fields | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------- | | `status` | string | Overall request status. A successfully processed request returns `ok`. | | `data` | array | Individual results for each submitted phone number. | | `data[].number` | string | Normalized 10-digit phone number. | | `data[].status` | string | Processing result for the individual phone number. | | `data[].message` | string | Description of the result. | *** ### Partial Success Response A request may contain both successful and unsuccessful phone numbers. The overall response may still return `status: ok`, while individual numbers contain an error. ``` { "status": "ok", "data": [ { "number": "3035550100", "status": "ok", "message": "CNAM updated successfully" }, { "number": "123", "status": "error", "message": "Invalid number format" }, { "number": "3035550199", "status": "error", "message": "Number not found in your DIDs" } ] } ``` \ Always inspect the `status` field of every item in the `data` array. An overall `status` of `ok` does not mean that every submitted number was accepted.
*** ### Error Responses #### Missing required parameter Returned when `numbers` or `cnam` is not included in the request. ``` { "status": "error", "error": "Missing required parameter" } ``` The exact missing-parameter message may depend on the standard API validation response. *** #### No valid numbers ``` HTTP/1.1 400 Bad Request ``` ``` { "status": "error", "error": "No valid numbers provided" } ``` *** #### Invalid CNAM Returned when the CNAM is empty after unsupported characters are removed. ``` HTTP/1.1 400 Bad Request ``` ``` { "status": "error", "error": "Invalid CNAM" } ``` *** #### Unexpected server error ``` HTTP/1.1 500 Internal Server Error ``` ``` { "status": "error", "error": "Unexpected error" } ``` *** ### Number-Level Errors Individual phone numbers may return one of the following errors: | Message | Description | | ------------------------------- | ------------------------------------------------------------------------------------------ | | `Invalid number format` | The normalized phone number is not 10 digits long. | | `Number not found in your DIDs` | The phone number does not belong to the authenticated account or an associated subaccount. | *** ### Processing Behaviour For every valid phone number, the API creates a CNAM request containing: | Field | Value | | -------------- | -------------------------------- | | Account | Authenticated account | | DID | Normalized 10-digit phone number | | Caller ID Name | Submitted CNAM value | | Initial status | `pending` | A successful API response confirms that the CNAM request was accepted for processing. It does not necessarily confirm that the downstream carrier has already completed the CNAM update. # Send SMS Send an SMS Message ## GET or POST Request {% hint style="info" %} {% endhint %} | Argument | Required | Type | | ----------- | -------- | ------ | | source | yes | int | | destination | yes | int | | message | yes | string | | key | yes | string | Send a GET or POST request with source, destination, message and key to us and we will deliver it to the recipient. {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/sms/send \ -d 'source=3038821111' \ -d 'destination=6038821111' \ -d 'message=yo' \ -d 'key=your_api_key' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/sms/send?key=yourapikey&source=3038821111&destination=6038821111&message=yo ``` {% endtab %} {% tab title="JSON Response" %} ```php {"status":"ok", "uuid":"j932jf-hh8w32-djfh2f"} OR {"status":"error", "error":"invalid source number"} ``` {% endtab %} {% endtabs %} # Send MMS Send an MMS Message ## GET or POST Request {% hint style="info" %} {% endhint %} | Argument | Required | Type | | ----------- | -------- | ------------------ | | source | yes | int | | destination | yes | int | | message | no | string | | url | yes | | | key | yes | string | Send a GET or POST request with source, destination, message and key to us and we will deliver it to the recipient. Message is so that you have the ability to send a picture and add a text message with it for no extra charge. {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/mms/send \ -d 'source=3038821111' -d 'destination=6038821111' -d 'message=yo' -d 'url=http://mypics.com/image33.png' -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ``` curl https://v1.api19.com/mms/send?key=yourapikey&url=http://picurl.com/img.png&source=3038821111&destination=6038821111&message=yo ``` {% endtab %} {% tab title="JSON Response" %} ```php {"status":"ok"} OR {"status":"error", "error":"invalid source number"} ``` {% endtab %} {% endtabs %} # Receive SMS/MMS Receive an SMS / MMS message to your system ## Portal Settings Inside the portal, in your user settings (at the top right of the screen drop down), you can set the incoming URL. When you receive an MMS or SMS, you will receive the following as POST variables: | Argument | Value | Type | | ----------- | ------------------ | ---------- | | source | yes | int | | destination | yes | int | | message | no | string | | attachments | json array of urls | json | | type | yes | sms or mms | | cost | cost of message | int | Here's an example: {% tabs %} {% tab title="Received Post SMS" %} ```php HTTP Post Variables OR JSON Post ( [source] => 3038882222 [destination] => 7206321111 [message] => hello [type] => sms [cost] => 0 ) ``` {% endtab %} {% tab title="Received Post MMS" %} ```php HTTP Post Variables OR JSON Post ( [source] => 3038882222 [destination] => 7206321111 [message] => [attachments] => ["https:\/\/mmsdata.net\/3a95-ea85-4978-b723-4f29b73f96dc.png"] [type] => mms [cost] => 0 ) ``` {% endtab %} {% endtabs %} # Receive Delivery Receipts Receive a SMS message to your system ## Portal Settings Under User Settings, on the top right of the portal drop down, you can edit your ***Receive SMS/MMS Delivery Messages*** urls. Here is a list of possible errors we will send you in the error field:\ The following data will be posted:
ArgumentValueType
sourcesource numberint
destinationdestination numberint
send_statuscarrier_sent / rejected / deliveredstring
statusREJECTED / DELIVRDstring
error000 / 600int
Here's an example: {% tabs %} {% tab title="Delivered" %} ```php HTTP Post Variables OR JSON posted ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => carrier_sent [status] => sent [error] => 000 ) ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => delivered [status] => DELIVRD [error] => 000 ) ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => delivered [status] => DELIVERED [error] => 000 ) ``` {% endtab %} {% tab title="Rejected" %} ```php HTTP Post Variables OR JSON posted ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => carrier_sent [status] => sent [error] => 000 ) ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => rejected [status] => REJECTED [error] => 600 ) ( [uuid] => s-1c3b-946b-306a-a068-489a8b9ce6f6-02252024 [source] => 3038882222 [destination] => 7206321111 [send_status] => error [status] => error [error] => Carrier specific error ) ``` {% endtab %} {% endtabs %} # Lookup SMS Message ## GET or POST Request {% hint style="info" %} {% endhint %} Lookup message details by message UUID {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/sms/lookup \ -d 'key=api_token' \ -d 'uuid=550e8400-e29b-41d4-a716-446655440000' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/sms/lookup?key=apikey&uuid=550e8400-e29b-41d4-a716-446655440000 ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": { "insert_date": "string", "user_id": "string", "cost": "string", "surcharge": "string", "src": "string", "dst": "string", "message": "string", "direction": "string", "msg_type": "string", "service_type": "string" } } OR { "status": "error", "error": "not found" } ``` {% endtab %} {% endtabs %} ## Parameters * `uuid` (required) - Message UUID # Get Verticals ## GET or POST Request {% hint style="info" %} {% endhint %} Get the possible verticals for campaigns / brands {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/verticals \ -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/campaigns/verticals?key=apikey ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": { "PROFESSIONAL": { "industryId": "professional-services", "displayName": "Professional Services", "description": "Professional services." }, "REAL_ESTATE": { "industryId": "real-estate", "displayName": "Real Estate", "description": "Buying and Selling of residential and commercial properties." }, "HEALTHCARE": { "industryId": "healthcare-and-lifesciences", "displayName": "Healthcare and Life Sciences", "description": "Healthcare services, including hospital, health insurances." }, "HUMAN_RESOURCES": { "industryId": "human-resources-staffing-recruitment", "displayName": "HR, Staffing or Recruitment", "description": "Human resources, staffing, or recruitment." }, "ENERGY": { "industryId": "energy-and-utilities", "displayName": "Energy and Utilities", "description": "Energy and Utilities." }, "ENTERTAINMENT": { "industryId": "entertainment", "displayName": "Entertainment", "description": "Entertainment, including gaming and dating services." }, "RETAIL": { "industryId": "retail-and-consumer-products", "displayName": "Retail and Consumer Products", "description": "Consumer products and services, including Retails and eTails." }, "TRANSPORTATION": { "industryId": "transportation-logistics", "displayName": "Transportation or Logistics", "description": "Transportation or logistics services." }, "AGRICULTURE": { "industryId": "agriculture", "displayName": "Agriculture", "description": "Agriculture businesses and services." }, "INSURANCE": { "industryId": "insurance", "displayName": "Insurance", "description": "Insurance products and services" }, "POSTAL": { "industryId": "postal-delivery", "displayName": "Postal and Delivery", "description": "Postal and delivery services." }, "EDUCATION": { "industryId": "education", "displayName": "Education", "description": "Educational institutions providing education to students in educational settings." }, "HOSPITALITY": { "industryId": "hospitality", "displayName": "Hospitality and Travel", "description": "Travel, hospitality and transportation." }, "FINANCIAL": { "industryId": "financial-services", "displayName": "Financial Services", "description": "Banking and financial institution." }, "POLITICAL": { "industryId": "political", "displayName": "Political", "description": "Political campaigns and services." }, "GAMBLING": { "industryId": "gambling-and-lottery", "displayName": "Gambling and Lottery", "description": "Gambling and Lotteries." }, "LEGAL": { "industryId": "legal", "displayName": "Legal", "description": "Legal services and law firms." }, "CONSTRUCTION": { "industryId": "construction-and-materials", "displayName": "Construction, Materials, and Trade Services", "description": "Construction, materials, and trade services." }, "NGO": { "industryId": "non-profit-organization", "displayName": "Non-profit Organization", "description": "Non-profit organization with valid tax-exempted status." }, "MANUFACTURING": { "industryId": "manufacturing", "displayName": "Manufacturing", "description": "Goods producing industries." }, "GOVERNMENT": { "industryId": "public-sector", "displayName": "Government Services and Agencies", "description": "Local, state or federal agencies, utilities." }, "TECHNOLOGY": { "industryId": "information-technology-services", "displayName": "Information Technology Services", "description": "Information technology and information services." }, "COMMUNICATION": { "industryId": "mass-media-and-communication", "displayName": "Media and Communication", "description": "Communication and mass media." } } } ``` {% endtab %} {% endtabs %} # Submit TollFree Campaign SMS Enable a toll free number by submitting a campaign request for it ## GET or POST Request {% hint style="info" %} {% endhint %}
ArgumentRequiredType
didyesthe number you're activating SMS on
businessnameyesstring
firstnameyesstring
lastnameyesstring
contactemailyesstring
contactphoneyesstring
websiteyesstring
address1yesstring
address2nostring
cityyesstring
stateyesstring
zipyesstring
usecaseyesSummarize the Use Case
optininfoyesHow will handsets be opting-in to SMS program?
(Please provide proof of opt-in. You may provide a screenshot if opt-in is not visible from URL provided. Images may be uploaded at the bottom of the page. NOTE: consent from end user to receive SMS must be explicit.)
messagecontentyesPlease provide sample message content for this campaign
wherepublishedyesTell us where the number will be published (website link, billboard)
urls_messagecontentyesList any urls that will be in the message content
numbers_messagecontentyesList any phone numbers that will be in the message content
enable_canadano

Allow Canadian traffic

yes / no

advertisingnoThis number will have Marketing/Advertising in messages
yes / no
fortune500noThis company is a fortune 100 or fortune 500 company
yes / no
donationsnoThis number will be asking for Donations / Collections
yes / no
donations_datanoif donations is yes:
Please provide the Tax-ID, and non-profit website
All other information on this form must match this non-profit
msgvolumeyesDaily Message Volume
file1_urlnohttp url - if you want to attach an image to the campaign
file2_urlnohttp url - if you want to attach an image to the campaign
keyyesyour api key
Send a POST with all of the information required from above {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/campaigns/tollfree/submit \ -d "key=2h9fh23f23f2" \ -d "did=8883038888" \ -d "businessname=Acme Corporation" \ -d "firstname=John" \ -d "lastname=Doe" \ -d "contactemail=john.doe@example.com" \ -d "contactphone=1234567890" \ -d "website=https://www.acme-corp.com" \ -d "address1=123 Main Street" \ -d "address2=Apt 4B" \ -d "city=Metropolis" \ -d "state=NY" \ -d "zip=10001" \ -d "usecase=Marketing Campaign" \ -d "optininfo=customer opt in by calling our 800 number, and ...." \ -d "messagecontent=Hello, this is a test message for our campaign!" \ -d "wherepublished=Social Media" \ -d "urls_messagecontent=https://www.example.com/test-message" \ -d "numbers_messagecontent=5551234" \ -d "enable_canada=true" \ -d "advertising=yes" \ -d "fortune500=no" \ -d "donations=yes" \ -d "donations_data=Charity Drive 2023, TIN 87-1771212" \ -d "msgvolume=500000" \ -d "file1_url=http://mypic.com/screenshot.jpg" \ -d "file2_url=http://mypic.com/screenshot2.jpg" ``` {% endtab %} {% tab title="JSON Response" %} ```php {"status":"ok"} OR {"status":"error","error":"Missing required fields: lastname"} OR {"status":"error", "error":"you do not own this number"} ``` {% endtab %} {% endtabs %} # Campaign Assign Number Assign a phone number to a campaign ## GET or POST Request {% hint style="info" %} {% endhint %} Set the Campaign ID for a specific phone number.
ArgumentRequiredType
didyesyour phone number
campaign_idyescampaign ID OR canada
keyyesyour API key
Set the campaign on your phone number to a campaign ID or enable for Canada only. {% tabs %} {% tab title="Curl Post" %} ```php curl -X POST https://v1.api19.com/campaigns/assign/did \ -d 'did=3038821111' \ -d 'campaign_id=CXMR32R' \ -d 'key=your-key' ``` {% endtab %} {% tab title="JSON Response" %} ```json {"status": "ok"} OR {"status": "error", "error":"You do not own 3035551212"} OR {"status": "error", "error":"You do not own this campaign_id"} ``` {% endtab %} {% endtabs %} # Get 10DLC Brand ## GET or POST Request {% hint style="info" %} {% endhint %} Get details of a specific 10DLC brand {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/brand/get \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/campaigns/brand/get?key=apikey&brand_id=B1A2C3D4E5 ``` {% endtab %} {% tab title="JSON Response" %} ```json { "System_Status": "string", "Registry_Status": "string", "Brand_ID": "string", "Company_Type": "string", "TIN_or_EIN": "string", "Alt_Company_ID": "string", "Alt_Company_Value": "string", "Company_Name": "string", "Doing_Business_As": "string", "First_Name": "string", "Last_Name": "string", "Address": "string", "Address_2": "string", "City": "string", "State": "string", "Zip": "string", "Country": "string", "Email_Address": "string", "Website": "string", "Phone_Number": "string", "Mobile_Phone": "string", "Date_Created": "string", "Brand_Relationship": "string", "status": "string", "campaigns": [ { "id": "string", "crid": "string", "local_campaign_id": "string" }, { "id": "string", "crid": "string", "local_campaign_id": "string" } ] } ``` {% endtab %} {% endtabs %} ## Parameters * `brand_id` (required) - Brand ID # List 10DLC Brands ## GET or POST Request {% hint style="info" %} {% endhint %} Get a list of all 10DLC brands on your account {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/brand/list \ -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/campaigns/brand/list?key=apikey ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "brands": [ { "brand_id": "string", "network": "string", "company_name": "string", "identity_status": "string", "status": "string" } ] } ``` {% endtab %} {% endtabs %} # Create 10DLC Brand ## POST Request {% hint style="info" %} {% endhint %} Create a new 10DLC brand registration {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/brand/create \ -d 'key=api_token' \ -d 'companyType=PRIVATE_PROFIT' \ -d 'ein=123456789' \ -d 'inputCountry=US' \ -d 'vertical=PROFESSIONAL' \ -d 'businessname1=Company Name' \ -d 'FirstName=John' \ -d 'LastName=Doe' \ -d 'Address1=123 Main St' \ -d 'City=Denver' \ -d 'inputState=CO' \ -d 'Zip=80202' \ -d 'Email=contact@example.com' \ -d 'Website=https://example.com' \ -d 'phonenumber=3035551234' ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok" } ``` {% endtab %} {% endtabs %} ## Parameters | Parameter | Required | Description | | ------------------ | :---------: | --------------------------------------------------------------- | | companyType | yes | Type of company | | ein | contitional | Employer Identification Number. Required if not sole proprietor | | inputCountry | yes | Country code | | alt\_company\_info | no | Alternative company information | | alt\_company\_data | no | Alternative company data | | vertical | yes | Business vertical/industry | | businessname1 | conditional | Primary business name, if not sole proprietor | | businessname2 | no | Secondary business name | | FirstName | yes | First name of contact | | LastName | yes | Last name of contact | | Address1 | yes | Primary address | | Address2 | no | Secondary address | | City | yes | City | | inputState | yes | State | | Zip | yes | Postal code | | Email | yes | Contact email | | Website | yes | Company website | | phonenumber | yes | Contact phone number | | mobilenumber | conditional | Mobile phone number, if sole proprietor | | stockSymbol | no | Stock symbol | | stockExchange | no | Stock exchange | # Update 10DLC Brand ## POST Request {% hint style="info" %} {% endhint %} Update an existing 10DLC brand {% tabs %} {% tab title="Curl Post" %} {% code title="curl" %} ```bash curl https://v1.api19.com/campaigns/brand/update \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' \ -d 'companyName=Updated Company Name' \ -d 'website=https://newsite.com' \ -d 'email=newemail@example.com' ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="response.json" %} ```json { "status": "ok", "data": "Brand updated successfully" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `brand_id` (required) - Brand ID * `companyName` (optional) - Company name * `ein` (optional) - Employer Identification Number * `entityType` (optional) - Entity type * `firstname` (optional) - First name of contact * `lastname` (optional) - Last name of contact * `dba` (optional) - Doing Business As name * `website` (optional) - Company website * `address1` (optional) - Primary address * `address2` (optional) - Secondary address * `city` (optional) - City * `state` (optional) - State * `zip` (optional) - Postal code * `country` (optional) - Country code * `email` (optional) - Contact email * `phone` (optional) - Contact phone number * `vertical` (optional) - Business vertical/industry * `stockSymbol` (optional) - Stock symbol * `stockExchange` (optional) - Stock exchange * `altBusinessId` (optional) - Alternative business ID * `altBusinessIdType` (optional) - Alternative business ID type # Remove 10DLC Brand ## POST Request {% hint style="info" %} {% endhint %} Delete a 10DLC brand from your account {% tabs %} {% tab title="cURL" %} {% code title="curl" %} ```bash curl https://v1.api19.com/campaigns/brands/remove \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="success.json" %} ```json { "status": "ok", "message": "Brand removed successfully" } ``` {% endcode %} {% code title="error.json" %} ```json { "status": "error", "error": "Brand not found" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `brand_id` (required) - Brand ID # List 10DLC Brand Vetting Providers ## GET or POST Request {% hint style="info" %} {% endhint %} Get a list of available external vetting providers for 10DLC brands {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/brand/vetting/providers \ -d 'key=api_token' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/campaigns/brand/vetting/providers?key=apikey ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "providers": [ { "evpId": "AEGIS", "displayName": "Aegis Mobile", "tcrBillable": true, "vettingClasses": [ "STANDARD", "POLITICAL", "ENHANCED", "RCS", "AUTHPLUS" ], "vettingInstruction": "{\r\n \"importVet\" : {\r\n \"supported\" : true,\r\n \"parameters\" : {\r\n \"vettingId\" : {\r\n \"label\" : \"Vetting ID\",\r\n \"show\" : true\r\n },\r\n \"vettingToken\" : {\r\n \"label\" : \"Vetting Token\",\r\n \"show\" : false\r\n }\r\n },\r\n \"info\" : \"Vetting partner Aegis\"\r\n },\r\n \"newVet\" : {\r\n \"supported\" : true,\r\n \"price\" : {\r\n \"STANDARD\" : 40\r\n },\r\n \"waitTime\" : \"30 seconds\",\r\n \"info\" : \"Vetting partner Aegis\"\r\n }\r\n}" }, ... ] } ``` {% endtab %} {% endtabs %} # Get 10DLC Brand Vetting Status ## GET or POST Request {% hint style="info" %} {% endhint %} Get the vetting status for a 10DLC brand {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/brand/vetting/status \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' ``` {% endtab %} {% tab title="Curl Get" %} ```bash curl https://v1.api19.com/campaigns/brand/vetting/status?key=apikey&brand_id=B1A2C3D4E5 ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": [ { "evpId": "AEGIS", "vettingId": "###", "vettingToken": "###", "vettingScore": 80, "vettingClass": "STANDARD", "vettingStatus": "ACTIVE", "reasons": [ "Company size as reported by government or business sources resulted in a score deduction: size range 6-10." ], "vettingDetails": {}, "vettedDate": "2024-11-05T16:35:36.000Z", "createDate": "2024-11-05T16:35:36.000Z", "validUntil": "2025-11-05T16:35:36.000Z", "expirationDate": "2025-11-05T16:35:36.000Z" } ] } ``` {% endtab %} {% endtabs %} ## Parameters * `brand_id` (required) - Brand ID # Create 10DLC Brand Vetting Submit a 10DLC brand for external vetting. {% hint style="info" %} {% endhint %} {% tabs %} {% tab title="Curl Post" %} {% code title="curl" %} ```bash curl https://v1.api19.com/campaigns/brand/vetting/create \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' \ -d 'evpId=EVP001' \ -d 'vettingClass=STANDARD' ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="response.json" %} ```json { "status": "ok", "data": { "evpId": "AEGIS", "vettingId": "###", "vettingToken": "###", "vettingScore": null, "vettingClass": "STANDARD", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2025-02-07T17:26:11.539Z" "validUntil": null, "expirationDate": null } } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `brand_id` (required) - Brand ID * `evpId` (required) - External vetting provider ID * `vettingClass` (required) - Vetting class type * `additionalRequestPayload` (optional) - Additional data required by the vetting provider ## Developer Guide ### External Vets for SOLE\_PROPRIETORS and PUBLIC\_PROFITS Some brand entity types have restrictions that can prohibit an external vetting request, or require that the brand have a specific identity status before the request is processed. * **SOLE\_PROPRIETOR**: A brand with this entity type cannot request external vetting. * **PUBLIC\_PROFIT**: A Public Profit brand must have a `VERIFIED` or `VETTED_VERIFIED` identity status in order to qualify for a new external vet or to import an external vet. *** ### Vetting Providers and Supported Vetting Classes Some vetting providers only accept requests for specific types of vets (referred to as a vetting class). Additionally, certain vets are limited to a brand's national origin and entity type. The following table provides information on external vetting providers and the types of vets they accept. #### Aegis Mobile | EVP ID | Vetting Class | Description | | ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AEGIS` | `STANDARD` |

Requests a standard external vet. Allowed for US and non-US brands.

Eligible Entity Types:
• PRIVATE\_PROFIT, PUBLIC\_PROFIT, NON\_PROFIT, GOVERNMENT

| | `AEGIS` | `POLITICAL` |

Requests a political external vet. Allowed for US brands only.

Eligible Entity Types:
• NON\_PROFIT

| | `AEGIS` | `ENHANCED` |

Requests an enhanced external vet. Allowed for US and non-US brands.

Eligible Entity Types:
• PRIVATE\_PROFIT, PUBLIC\_PROFIT, NON\_PROFIT, GOVERNMENT

| | `AEGIS` | `AUTHPLUS` |

Requests an Authentication+ verification. Allowed for US and non-US brands.

Eligible Entity Types:
• PUBLIC\_PROFIT

| | `AEGIS` | `RBM` |

Requests an RBM verification. Allowed for US and non-US brands. Completing an RBM vet automatically grants Auth+ compliance to a brand.

Eligible Entity Types:
• PRIVATE\_PROFIT, PUBLIC\_PROFIT, NON\_PROFIT, GOVERNMENT

| #### WMC Global | EVP ID | Vetting Class | Description | | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WMC` | `STANDARD` |

Requests a standard external vet. Allowed for US brands only.

Eligible Entity Types:
• PRIVATE\_PROFIT, PUBLIC\_PROFIT

| | `WMC` | `POLITICAL` | Not supported. | | `WMC` | `ENHANCED` | Not supported. | | `WMC` | `AUTHPLUS` | Not supported. | | `WMC` | `RBM` | Not supported. | ### Requesting an External Vet All vets are requested by using the `POST /campaigns/brand/vetting/create` endpoint. The JSON request body must contain a valid `evpId`, which is the identity of the external vetting provider (see table above), and a `vettingClass`. Supported vetting classes include `STANDARD`, `ENHANCED`, `POLITICAL`, `AUTHPLUS`, and `RBM`. *** ### Standard Vet Standard vets can be used to verify a brand or potentially gain access to better throughput levels with network carriers. A Standard vet is an automated review of compliance history, employee count, and other business metrics. Once complete, a score of 0-100 will be provided to determine the brand's throughput level for particular carriers. Scores grant different terms per carrier, and feedback reasons are provided. Standard vets can be requested through the API without the optional `additionalRequestPayload` parameter. #### Example Request ```bash curl -X 'POST' \ 'https://v1.api19.com/campaigns/brand/vetting/create' \ -d "evpId=AEGIS" \ -d "vettingClass=STANDARD" ``` #### Example Response ```json { "evpId": "AEGIS", "vettingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "vettingToken": null, "vettingScore": null, "vettingClass": "STANDARD", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2024-10-14T05:35:34.123Z", "validUntil": null, "expirationDate": null } ``` *** ### Enhanced Vet Enhanced vets are typically requested if a user is dissatisfied with their Standard vet score. If a CSP has already submitted a Standard vet appeal and believes a more thorough review would yield a higher score, they can order an Enhanced vet. Enhanced vets can be requested through the API without the optional `additionalRequestPayload` parameter. #### Example Request ```bash curl -X 'POST' \ 'https://v1.api19.com/campaigns/brand/vetting/create' \ -d "evpId=AEGIS" \ -d "vettingClass=ENHANCED" ``` #### Example Response ```json { "evpId": "AEGIS", "vettingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "vettingToken": null, "vettingScore": null, "vettingClass": "ENHANCED", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2024-10-14T05:36:30.129Z", "validUntil": null, "expirationDate": null } ``` *** ### Political Vet Political vets allow brands to use the Political special use case. NON\_PROFIT brands that have a 501(c)(3/4/5/6) Tax Exempt Status are already granted access to the Political use case and are not allowed to request or import a Political vet from any vendor. A request body parameter `additionalRequestPayload` is required when requesting Political vets. It's used to provide additional brand information that's required by vetting providers to successfully process the vetting request. Information on these fields can be found in Appendix A: Additional Payload Request Schema. #### Example Request ```bash curl -X 'POST' \ 'https://v1.api19.com/campaigns/brand/vetting/create' \ -d "evpId=AEGIS" \ -d "vettingClass=POLITICAL" \ -d 'additionalRequestPayload={"requestorFirstName":"John","requestorLastName":"Doe","locale":"Federal","fecCommitteeTypeCode":"E","committeeId":"12345","candidateType":"PAC","stateLocalCommitteeType":"FEDERAL","localCommitteeState":"NY","localCommitteeMunicipality":"Brooklyn","tribalLocation":"US","filingUrl":"www.filingurl.com","filingRecordUrlInstructions":"sample instructions","filingEmail":"contact@domain.com","electionDate":"2026-12-26","pinPreference":"Regular"}' ``` #### Example Response ```json { "evpId": "AEGIS", "vettingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "vettingToken": null, "vettingScore": null, "vettingClass": "POLITICAL", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2024-10-14T05:38:03.587Z", "validUntil": "2025-10-14T05:38:03.587Z", "expirationDate": "2025-10-14T05:38:03.587Z" } ``` *** ### Auth+ Vet Auth+ vets verify a brand's business contact through a Two-Factor Authentication (2FA) email process. They are only available for PUBLIC\_PROFIT brands and are required for those brands to create new campaigns. For more information, see the Authentication+ 2.0 Feature Overview. Auth+ vets can be requested through the API without the optional `additionalRequestPayload` parameter. #### Example Request ```bash curl -X 'POST' \ 'https://v1.api19.com/campaigns/brand/vetting/create' \ -d "evpId=AEGIS" \ -d "vettingClass=AUTHPLUS" ``` #### Example Response ```json { "evpId": "AEGIS", "vettingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "vettingToken": null, "vettingScore": null, "vettingClass": "AUTHPLUS", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2024-10-14T05:38:03.587Z", "validUntil": "2025-10-14T05:38:03.587Z", "expirationDate": "2025-10-14T05:38:03.587Z" } ``` *** ### RBM Vet RBM vets verify a brand's eligibility for RCS Business Messaging (RBM) as well as a business contact through a Two-Factor Authentication (2FA) email process. They are available for all entity types except SOLE\_PROPRIETOR and are not tied to a brand's identity status (i.e., a brand can be VERIFIED or UNVERIFIED). Successfully completing an RBM vet automatically grants Authentication+ compliance without completing an Auth+ vet. For more information, see the RBM Vetting Feature Overview. RBM vets can be requested through the API without the optional `additionalRequestPayload` parameter. #### Example Request ```bash curl -X 'POST' \ 'https://v1.api19.com/campaigns/brand/vetting/create' \ -d "evpId=AEGIS" \ -d "vettingClass=RBM" ``` #### Example Response ```json { "evpId": "AEGIS", "vettingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "vettingToken": null, "vettingScore": null, "vettingClass": "RBM", "vettingStatus": "PENDING", "reasons": null, "vettingDetails": {}, "vettedDate": null, "createDate": "2024-10-14T05:38:03.587Z", "validUntil": "2025-10-14T05:38:03.587Z", "expirationDate": "2025-10-14T05:38:03.587Z" } ``` *** ### Appendix A: Additional Payload Request Schema | Attribute | Data Type | Required | Description | | ----------------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requestorFirstName` | String | Yes |

First name of the committee person who initiated the verification request. Must be an exact match with what is filed with the election authority.
Max Length: 100

| | `requestorLastName` | String | Yes |

Last name of the committee person who initiated the verification request. Must be an exact match with what is filed with the election authority.
Max Length: 100

| | `locale` | String | Yes |

Accepted values: Federal, State, Local, Tribal
Max Length: 16

| | `fecCommitteeTypeCode` | String | See description |

Required if Federal. Refer to Appendix C: Committee Type Codes for a list of acceptable values.
Max Length: 1

| | `committeeId` | String | Yes |

The issued committee/campaign ID from the election authority. If the election authority does not require a committee/campaign ID for the specified locale, enter 00000.
Max Length: 32

| | `candidateType` | String | Yes |

Required for candidate campaigns. If the committee is not candidate-specific, enter PAC.
Max Length: 64

| | `stateLocalCommitteeType` | String | Yes |

Required for State, Local, and Tribal locales. If Federal, enter FEDERAL.
Max Length: 64

| | `localCommitteeState` | String | Yes |

If Federal Congress, enter the state to be represented. Refer to Appendix B: FEC Jurisdictions for acceptable values. If the election is for the US President, enter US.
Max Length: 32

| | `localCommitteeMunicipality` | String | Yes |

If Federal Congress, enter the district to be represented. If this is a presidential election, enter US.
Max Length: 64

| | `tribalLocation` | String | Yes |

If the locale is not Tribal, enter US.
Max Length: 64

| | `filingUrl` | String | Yes |

The election authority website URL. This website should contain filing information.
Max Length: 256

| | `filingRecordUrlInstructions` | String | No |

Additional instructions that provide information on how to locate the filing record.
Max Length: 256

| | `filingEmail` | String | No |

The email address filed with the election authority. Must be an exact match. If not supplied, the Political vet's PIN cannot be sent via email.
Max Length: 128

| | `electionDate` | Date | Yes |

The date of the election in the format yyyy-mm-dd. Must be a future date.
Max Length: 10

| | `pinPreference` | String | Yes |

Indicates how to deliver the Political vet's PIN. Accepted values are: Regular, Express, Email.
Max Length: 16

| ### Appendix B: FEC Jurisdictions | Jurisdiction | Abbreviation | | ------------------------ | ------------ | | Alabama | AL | | Alaska | AK | | Arizona | AZ | | Arkansas | AR | | California | CA | | Colorado | CO | | Connecticut | CT | | Delaware | DE | | Florida | FL | | Georgia | GA | | Hawaii | HI | | Idaho | ID | | Illinois | IL | | Indiana | IN | | Iowa | IA | | Kansas | KS | | Kentucky | KY | | Louisiana | LA | | Maine | ME | | Maryland | MD | | Massachusetts | MA | | Michigan | MI | | Minnesota | MN | | Mississippi | MS | | Missouri | MO | | Montana | MT | | Nebraska | NE | | Nevada | NV | | New Hampshire | NH | | New Jersey | NJ | | New Mexico | NM | | New York | NY | | North Carolina | NC | | North Dakota | ND | | Ohio | OH | | Oklahoma | OK | | Oregon | OR | | Pennsylvania | PA | | Rhode Island | RI | | South Carolina | SC | | South Dakota | SD | | Tennessee | TN | | Texas | TX | | Utah | UT | | Vermont | VT | | Virginia | VA | | Washington | WA | | West Virginia | WV | | Wisconsin | WI | | Wyoming | WY | | District of Columbia | DC | | American Samoa | AS | | Guam | GU | | Northern Mariana Islands | MP | | Puerto Rico | PR | | US Virgin Islands | VI | | United States | US | *** ### Appendix C: Committee Type Codes This information is reprinted from the Federal Election Commission website. | Code | Committee Type | Description | | ---- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | C | Communication cost | Organizations like corporations or unions may prepare communications for their employees or members that advocate the election of specific candidates and they must disclose them under certain circumstances. These are usually paid with direct corporate or union funds rather than from PACs. | | D | Delegate committee | Delegate committees are organized for the purpose of influencing the selection of delegates to Presidential nominating conventions. The term includes a group of delegates, a group of individuals seeking to become delegates, and a group of individuals supporting delegates. | | E | Electioneering communication | Groups (other than PACs) making electioneering communications. | | H | House | Campaign committees for candidates for the U.S. House of Representatives. | | I | Independent expenditor (person or group) | Individuals or groups (other than PACs) making independent expenditures over $250 in a year must disclose those expenditures. | | N | PAC - Nonqualified | PACs that have not yet been in existence for six months and received contributions from 50 people and made contributions to five federal candidates. These committees have lower limits for their contributions to candidates. | | O | Independent expenditure-only (Super PACs) | Political Committee that has filed a statement consistent with AO 2010-09 or AO 2010-11. | | P | Presidential | Campaign committee for candidate for U.S. President. | | Q | PAC - Qualified | PACs that have been in existence for six months and received contributions from 50 people and made contributions to five federal candidates. | | S | Senate | Campaign committee for candidate for Senate. | | U | Single-candidate independent expenditure | No description provided. | | V | Hybrid PAC (with Non-Contribution Account) - Nonqualified | Political committees with non-contribution accounts. | | W | Hybrid PAC with Non-Contribution Account - Qualified | Political committees with non-contribution accounts. | | X | Party - Nonqualified | Party committees that have not yet been in existence for six months and received contributions from 50 people, unless they are affiliated with another party committee that has met these requirements. | | Y | Party - Qualified | Party committees that have existed for at least six months and received contributions from 50 people or are affiliated with another party committee that meets these requirements. | | Z | National party non-federal account | National party non-federal accounts. Not permitted after enactment of Bipartisan Campaign Reform Act of 2002. | # Get 10DLC Campaign ## GET or POST Request {% hint style="info" %} {% endhint %} Get details of a specific 10DLC campaign {% tabs %} {% tab title="Curl Post" %} {% code title="Curl (POST)" %} ```bash curl https://v1.api19.com/campaigns/campaign/get \ -d 'key=api_token' \ -d 'id=12345' ``` {% endcode %} {% endtab %} {% tab title="Curl Get" %} {% code title="Curl (GET)" %} ```bash curl https://v1.api19.com/campaigns/campaign/get?key=apikey&id=12345 ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="Response (application/json)" %} ```json { "status": "ok", "data": { "id": "123", "name": null, "user_id": "321", "sms_daily_limit": null, "crid": "none", "mms_url": "", "campaign_description": "...", "call_to_action": "...", "sample_message_1": "...", "sample_message_2": "", "sample_message_3": "", "sample_message_4": "", "sample_message_5": "", "start_keywords": "START,YES", "opted_in_start": "...", "stop_keywords": "STOP", "opted_in_stop": "...", "help_keywords": "HELP", "opted_in_help": "...", "accepted_link": "", "accepted_phone_number": "", "accepted_loans": "no", "accepted_age_gated": "no", "accepted_number_pool": "no", "brand_id": "B12345", "use_case_type": "MIXED", "local_status": "new", "carrier_status": "new", "local_brand_id": "", "local_campaign_id": "...", "alt_use_cases": "[\"2FA\",\"ACCOUNT_NOTIFICATION\"]", "create_dt": "2026-05-08 10:00:46", "submitted": "no", "syniverse_status": "new", "reject_reason": null, "brand": { "id": "123", "user_id": "321", "company_type": "PRIVATE_PROFIT", "tin": "456", "alt_company": "NONE", "alt_company_data": "", "company_name": "...", "dba": "...", "brand_id": "B12345", "firstname": "", "lastname": "", "address1": "...", "address2": "", "city": "...", "state": "CO", "zip": "45678", "country": "US", "email": "...", "website": "...", "phone": "5555555555", "mobilephone": "0", "status": "registered", "error": null, "create_dt": "2025-05-27 11:36:43", "updated_dt": "2025-05-27 11:38:02", "brandRelationship": "MEDIUM_ACCOUNT", "referenceid": "...", "identity_status": "VERIFIED", "vertical": "PROFESSIONAL" } } } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `id` (required) - Campaign ID # Get 10DLC Campaign Numbers ## GET or POST Request {% hint style="info" %} {% endhint %} Get numbers associated with a specific 10DLC campaign {% tabs %} {% tab title="Curl Post" %} {% code title="Curl (POST)" %} ```bash curl https://v1.api19.com/campaigns/campaign/numbers \ -d 'key=api_token' \ -d 'id=12345' ``` {% endcode %} {% endtab %} {% tab title="Curl Get" %} {% code title="Curl (GET)" %} ```bash curl https://v1.api19.com/campaigns/campaign/numbers?key=apikey&id=12345 ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="Response (application/json)" %} ```json { "status": "ok", "data": { "registryId": [ '5555555555', '6666666666', '7777777777' ] } } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `id` (required) - Campaign ID # Create 10DLC Campaign {% hint style="info" %} {% endhint %} Create a new 10DLC campaign {% tabs %} {% tab title="Curl Post" %} {% code title="curl" %} ```bash curl https://v1.api19.com/campaigns/campaign/create \ -d 'key=api_token' \ -d 'brand_id=B1A2C3D4E5' \ -d 'campaign_description=Customer notifications and alerts' \ -d 'call_to_action=Reply YES to confirm' \ -d 'sample_message_1=Your order #12345 has shipped' \ -d 'opted_in_start=START' \ -d 'opted_in_stop=STOP' \ -d 'opted_in_help=HELP' \ -d 'use_case_type=2FA' ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="response.json" %} ```json { "status": "ok", "campaign_id": "string" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Required Parameters * `brand_id` (required) - 10DLC Brand ID * `campaign_description` (required) - Description of the campaign * `call_to_action` (required) - Call to action for subscribers * `sample_message_1` (required) - Sample message * `opted_in_start` (required) - Opt-in start message * `opted_in_stop` (required) - Opt-in stop message * `opted_in_help` (required) - Opt-in help message * `use_case_type` (required) - Campaign use case type * `mixed_use_cases` - (required when use\_case\_type is MIXED) Select up to 5 sub use cases. Comma separated string (e.g. "2FA, ACCOUNT\_NOTIFICATION, DELIVERY\_NOTIFICATION") ## Optional Parameters * `mms-upload` - MMS media URL * `sample_message_2` - Additional sample message * `sample_message_3` - Additional sample message * `sample_message_4` - Additional sample message * `sample_message_5` - Additional sample message * `keywords_start` - Keywords for start * `keywords_stop` - Keywords for stop * `keywords_help` - Keywords for help * `accept_links` - Whether campaign accepts links * `email_domain_name` - Email domain name * `accept_phone_numbers` - Whether campaign accepts phone numbers * `accept_loans` - Whether campaign involves loans * `accept_age_gated` - Whether campaign is age-gated Available Use Case Types: * MIXED * 2FA * ACCOUNT\_NOTIFICATION * AGENTS\_FRANCHISES * CARRIER\_EXEMPT * CHARITY * CUSTOMER\_CARE * DELIVERY\_NOTIFICATION * EMERGENCY * FRAUD\_ALERT * HIGHER\_EDUCATION * K12\_EDUCATION * LOW\_VOLUME * M2M * MARKETING * POLITICAL * POLLING\_VOTING * PROXY * PUBLIC\_SERVICE\_ANNOUNCEMENT * SECURITY\_ALERT * SOCIAL * SOLE\_PROPRIETOR * SWEEPSTAKE * UCAAS\_HIGH * UCAAS\_LOW # Update 10DLC Campaign ## POST Request {% hint style="info" %} {% endhint %} Update an existing 10DLC campaign {% tabs %} {% tab title="Curl Post" %} ```bash curl https://v1.api19.com/campaigns/campaign/update \ -d 'key=api_token' \ -d 'id=C12345' \ -d 'campaign_description=Updated campaign description' \ -d 'call_to_action=Reply YES to opt in' \ -d 'accepted_loans=false' \ -d 'accepted_age_gated=false' \ -d 'accepted_number_pool=true' ``` {% endtab %} {% tab title="JSON Response" %} ```json { "status": "ok", "data": "campaign updated" } ``` {% endtab %} {% endtabs %} ## Required Parameters * `id` (required) - Campaign ID * `mms_url` (required) - MMS media URL * `campaign_description` (required) - Campaign description * `call_to_action` (required) - Call to action * `accepted_loans` (required) - Whether campaign involves loans * `accepted_age_gated` (required) - Whether campaign is age-gated * `accepted_number_pool` (required) - Whether using number pool ## Optional Parameters {% hint style="warning" %} Warning: Optional fields will be set to default values if omitted. It is HIGHLY suggested to repost all data associated with a campaign. {% endhint %} * `sample_message_1` - Sample message * `sample_message_2` - Additional sample message * `sample_message_3` - Additional sample message * `sample_message_4` - Additional sample message * `sample_message_5` - Additional sample message * `start_keywords` - Start keywords * `opted_in_start` - Opt-in start message * `stop_keywords` - Stop keywords * `opted_in_stop` - Opt-in stop message * `help_keywords` - Help keywords * `opted_in_help` - Opt-in help message * `accepted_link` - Whether campaign accepts links * `accepted_phone_number` - Whether campaign accepts phone numbers * `use_case_type` - Campaign use case type * `resubmit` - Whether to resubmit the campaign # Remove 10DLC Campaign ## POST Request {% hint style="info" %} {% endhint %} Remove/Deactivate a 10DLC campaign from your account Note: This does not delete a campaign, but marks it as inactive (removes billing). It will still remain data retention purposes. {% tabs %} {% tab title="Curl Post" %} {% code title="curl" %} ```bash curl https://v1.api19.com/campaigns/campaign/remove \ -d 'key=api_token' \ -d 'id=C12345' ``` {% endcode %} {% endtab %} {% tab title="JSON Response" %} {% code title="Response (JSON)" %} ```json { "status": "ok", "message": "Campaign deactivated" } OR { "status": "error", "error": "Campaign not found" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Parameters * `id` (required) - Campaign ID # Calls Send and receive calls using RESTFUL connections {% hint style="info" %} **API Token Notice** You will need both your API Token and your Call API SID (ACCOUNT\_SID). Both are available in User Settings at the top right of the portal. The Call API SID is required in request URL for many commands to differentiate different voice call accounts. Every request will require you to set the HTTP username and password as the API\_Token (in curl this is: curl -u 'API\_Token:API\_Token') We only care about the username but many clients require both. {% endhint %} {% hint style="info" %} **Request Replies** JSON and XML are supported as possible responses to requests. XML is supported as backwards compatibility to competing platforms. JSON is the default. To force receive JSON replies, .json can be at the end of all URL requests. Most of the documentation has .json at the end of the URL. To receive XML replies, remove .json from the end of URL requests. {% endhint %} ### Overview Build voice applications for any app, website or voice based communications system with the help of our powerful drag and drop Visual Designer or robust Programmable Voice APIs. You can [jump to making call examples here.](https://apidocs.api19.com/call-apis/outgoing-calls/making-calls/example-code/outbound-to-tel) ### Programmable Voice features **Intelligent Call Control** Take control over your app call flow including call forwarding and routing, call transfers, collecting input, playing music, recording and storing calls, leaving a voicemail, sending an SMS and email and more. **Call Conference** CallAPI provides robust scalable audio conferencing functionality for your collaboration needs. You can create room-based and ad-hoc conferences with personal identification (PIN) codes that offer full conference room controls for a moderator including muting and dropping participants. **Speech recognition** CallAPI Speech Recognition API captures your speech in real-time, transcribes it, and returns text. Automatic speech recognition enables you to create applications and services that listen to users in 119 languages without any pre-training and acts on partial recognition results as your customer speaks. Imagine users driving your next app or service by talking to it! **Audio Playback** CallAPI enables your apps with a rich calling experience that includes playing customized voice prompts and hold music by uploading your choice of audio file. **Recording** CallAPI includes built-in and programmatic media recording. Using Visual Designer or APIs, your team can implement features for recording voicemail and meetings, integrating stored call recordings with your preferred Customer Relationship Management tools or build your own dashboard. CallAPI is compatible with popular external transcription services to transcribe recordings from voice to text. **IP Interfaces and API’s** CallAPI allows you to connect your existing SIP or WebRTC infrastructure from PBX to SIP or WebRTC Clients to the cloud and easily create VoIP call experiences. **Text-to-speech** Create synthesized audio messages that are delivered in language, accent and gender configured for your users. # Set Incoming URL Set the URL for incoming calls Incoming calls for numbers can be set either: 1. In the Call Flows under Numbers in the portal 2. On an individual DID basis ## By API Call {% hint style="info" %} URI: {% endhint %} **Supported Operations**: **HTTP POST** Sets the URL for a specific phone number to route to when needed. **Request Parameters** | Parameter | Description | | --------- | ---------------------------------------------------------- | | token | Your customer API Token | | did | The phone number to set the URL for or none to set no url. | | url | The HTTP/HTTPS URL to set route the call to. | Example CURL call: {% tabs %} {% tab title="Curl" %} ```php curl -X POST https://v1.api19.com/dids/my/callurl -d 'key=API_Token' \ -d 'did=number' \ -d 'url=http_url' ``` {% endtab %} {% endtabs %} # Incoming Calls ## HTTP Post from CallAPI to your web server Once you have the Incoming Call URL set, the web calls will come in normal HTTP post variables as displayed below.\ **POST Objects - Incoming Post Request - New Incoming Call**
```php POST fields in readable format: [CallSid] => IDfbf7e812ere32hfhfg6e10-Cd5dacca0c-CA9d3572be-9f7a-11ea-97f4-5ffeb3239325 [InstanceId] => ID242258723hHds8fh29G4569b66e10 [AccountSid] => AC06bc1hjh293hFH9edjJ23539a9ddb1 [From] => 3035550000 [To] => 8044731212 [CallStatus] => ringing OR completed OR failed OR in-progress OR no-answer [ApiVersion] => 2012-04-24 [Direction] => inbound [CallerName] => 3035550000 [ForwardedFrom] => null [CallTimestamp] => 2020-05-26T17:59:16.555Z [PostStatus] => callback OR new ``` **POST Objects - Status Update from an Outbound Call** ```php [CallSid] => ID242253601re32hfhfg6e10-CAceda56a709534034ae7c0e3a304b4d96 [InstanceId] => ID242258723hHds8fh29G4569b66e10 [AccountSid] => AC06bc1hjh293hFH9edjJ23539a9ddb1 [From] => 8044735555 [To] => 3035551212 [CallStatus] => in-progress [ApiVersion] => 2012-04-24 [Direction] => outbound-api [CallerName] => 8044735896 [ForwardedFrom] => null [CallTimestamp] => 2020-05-26T17:29:55.125Z [VoicemailDetector] => voicemail [or] person_found ``` #### 3.4.1 Post Fields - Incoming Calls | Attribute | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CallSid** | A string that uniquely identifies this call. | | **InstanceId** | Server instance ID that this call came from. | | **AccountSid** | The date that this call was created. | | **From** | The party who initiated the call. | | **To** | The party who received the call. | | **CallStatus** |

A descriptive status for the call. The value is one of these:

completed, failed, ringing, in-progress, no-answer, queued, wait-for-answer, or initiated

| | **ApiVersion** | Always set to 2012-04-24. | | **Direction** | Always inbound for inbound calls. | | **CallerName** |

If this call was an incoming call, the caller’s name.
Empty otherwise.

| | **ForwardedFrom** | Where the call was forwarded from (null normally). | | **CallTimestamp** | Timestamp when the call began: 2023-06-01T03:15:51.929Z. | | **PostStatus** |

Set to new or callback
new - the call is coming in for the first time.
callback - this is a callback notification / advancement of the call.

| ## Incoming Call Actions Once a call has been posted to your server, you can use the API Call Markup Language to process requests. A quick example: ``` Please hold while your call is connceted 18004444444 ``` [Click here to view the Markup Language documentation.](/call-api-markup/api-call-markup-language) # Listing Calls Listing and Searching Call History A Call represents a connection between a phone or user agent and the platform. This may be inbound or outbound. The Calls list resource represents the set of phone calls originated and terminated from an account. This section will focus on only using HTTP POST functions. ## Section URI {% hint style="info" %} List all calls **/call/2012-04-24/Accounts/{AccountSid}/ListCalls** {% endhint %} **or** {% hint style="info" %} List an individual call **/call/2012-04-24/Accounts/{AccountSid}/ListCalls/{CallSid}** {% endhint %} ## Standard Request Parameters
ParameterRequiredDescription
FromnoThe source or from phone number
TonoThe destination or to phone number
## Pagination Request Parameters None of the pagination requests are required
ParameterDescription
PageThe current page number. Zero-indexed, so the first page is 0. 0-20000
PageSizeHow many items are on each page 0-2000
StartTime

Only show recordings that were made on this date/time or later EndTime value examples allowed:

2024-04-01T10:10:10

2024-04-01 10:10:10

2024-04-01

EndTime

Only show recordings that were made on this date/time or earlier EndTime value examples allowed:

2024-04-01T10:10:10

2024-04-01 10:10:10

2024-04-01

CallSidOnly show recordings that have been started from this CallSid Value: CallSid=h923fh2h32fj23f2
SortBySort by the date created instead of the most recent on top Value: DateCreated or DateAsc
## POST or GET Requests Send us a request to list the calls for today or search for specific calls Searching your calls can include POST or GET variables From, To, Sid or Limit. {% tabs %} {% tab title="Search List" %} ```php curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/AC021d7d7d49d3234r34t3ea3769b9ed7/ListCalls \ -d 'From=17207741111' \ -d 'To=13038927627' \ -d 'PageSize=1000 \ -u '239h2g-23h9-239f23hf:AC021d7d7d49d3234r34t3ea3769b9ed7' ``` {% endtab %} {% tab title="List Last" %} ```javascript curl https://v1.api19.com/call/2012-04-24/Accounts/AC021d7d7d49d3234r34t3ea3769b9ed7/ListCalls \ -u '239h2g-23h9-239f23hf:AC021d7d7d49d3234r34t3ea3769b9ed7' ``` {% endtab %} {% tab title="List Individual Call" %} ```javascript curl https://v1.api19.com/call/2012-04-24/Accounts/AC021d7d7d49d3234r34t3ea3769b9ed7/ListCalls/ID13eeaa83f4c34aa28a9a7210995e1cbd-CA0257edff74b345b1b63076ef12a93b \ -u '239h2g-23h9-239f23hf:AC021d7d7d49d3234r34t3ea3769b9ed7' ``` {% endtab %} {% endtabs %} ## Calls Attributes in Response | Attribute | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sid | A string that uniquely identifies a call. | | ParentCallSid | A string that uniquely identifies the call that created this leg. | | DateCreated | The date that this call was created. | | DateUpdated | The date that this call was last updated. | | AccountSid | The unique id of the Account that created this call. | | To | The phone number or identifier that will be the recipient of this call. | | From | The phone number or identifier that originated this call. | | PhoneNumberSid | If the call was inbound, this is the Sid of the IncomingPhoneNumber that received the call. | | Status | A string representing the status of the call. Possible values are queued, ringing, in-progress, completed, failed, busy and no-answer. | | StartTime | The start time of the call. Empty if the call has not yet been started. | | EndTime | The end time of the call. Empty if the call has not ended. | | Duration | The length of the call in seconds. | | Price | The charge for this call, in the currency associated with the account. Populated after the call is completed. | | Direction | A string describing the direction of the call. Possible values are inbound, outbound-api, and outbound-dial | | AnsweredBy | If this call was initiated with answering machine detection, either human or machine. Empty otherwise. | | ApiVersion | Displays the current API version | | ForwardFrom | If this call was an incoming call forwarded from another number, the forwarding phone number (depends on carrier supporting forwarding). Empty otherwise. | | CallerName | If this call was an incoming call, the caller’s name. Empty otherwise. | | Uri |

The URI for this account, relative to

| ## Get call details ## Example JSON Responses Here is what the JSON will look like when there are multiple calls vs a single call {% tabs %} {% tab title="Single Call" %} ``` { "sid": "IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714", "InstanceId": "IDf0cbf85b95df45deb3cb404235e7c26e", "date_created": "Wed, 4 Sep 2024 00:26:56 +0000", "date_updated": "Wed, 4 Sep 2024 00:27:03 +0000", "account_sid": "AC025S7d7d49d7f923432552ea3769b9ed7", "to": "1303666627", "from": "1720444493", "status": "in-progress", "start_time": "2024-09-04T00:27:03.381Z", "duration": 0, "price_unit": "USD", "direction": "outbound-api", "answered_by": "1303666627", "api_version": "2012-04-24", "caller_name": "1720444493", "uri": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714.json", "ring_duration": 3, "subresource_uris": { "notifications": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714/Notifications.json", "recordings": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714/Recordings.json" } } ``` {% endtab %} {% tab title="Multiple Calls" %} ``` [ { "sid": "IDc473e064b2b34acbb104ea06acee5f42-CA5a6b8264a9c24e97a30fe3721fd9e5b4", "InstanceID": "IDc473e064b2b34acbb104ea06acee5f42", "date_created": "Wed, 4 Sep 2024 01:26:54 +0000", "date_updated": "Wed, 4 Sep 2024 01:26:56 +0000", "account_sid": "AC021d7d7d49d7f95749488ea3788wj92s", "to": "13038144444", "from": "17207747777", "status": "canceled", "start_time": "Wed, 4 Sep 2024 01:26:54 +0000", "duration": "0", "price_unit": "USD", "direction": "outbound-api", "answered_by": "13038144444", "api_version": "2012-04-24", "caller_name": "17207747777", "uri": "/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDc473e064b2b34acbb104ea06acee5f42-CA5a6b8264a9c24e97a30fe3721fd9e5b4", "ring_duration": "0", "subresource_uris": { "notification": "/call/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDc473e064b2b34acbb104ea06acee5f42-CA5a6b8264a9c24e97a30fe3721fd9e5b4/Notifications.json", "recordings": "/call/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDc473e064b2b34acbb104ea06acee5f42-CA5a6b8264a9c24e97a30fe3721fd9e5b4/Recordings.json" } }, { "sid": "IDf0cbf85b95df45deb3cb404235e7c26e-CAc991833d718849af98ac80582e3729fb", "InstanceID": "IDf0cbf85b95df45deb3cb404235e7c26e", "date_created": "Wed, 4 Sep 2024 01:25:06 +0000", "date_updated": "Wed, 4 Sep 2024 01:25:16 +0000", "account_sid": "AC021d7d7d49d7f95749488ea3788wj92s", "to": "13038144445", "from": "17207747772", "status": "completed", "start_time": "Wed, 4 Sep 2024 01:25:06 +0000", "duration": "5", "price_unit": "USD", "direction": "outbound-api", "answered_by": "13038144445", "api_version": "2012-04-24", "caller_name": "17207747772", "uri": "/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CAc991833d718849af98ac80582e3729fb", "ring_duration": "0", "subresource_uris": { "notification": "/call/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CAc991833d718849af98ac80582e3729fb/Notifications.json", "recordings": "/call/2012-04-24/Accounts/AC021d7d7d49d7f95749488ea3788wj92s/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CAc991833d718849af98ac80582e3729fb/Recordings.json" } } ] ``` {% endtab %} {% endtabs %} # Making Calls The /call/ function serves several purposes. In this section, we will cover the creating new calls utilizing **POST** variables. {% hint style="info" %} **API Token Notice** You will need both your API Token and your Call API SID (ACCOUNT\_SID). Both are available in User Settings at the top right of the portal. {% endhint %} ## Section URI {% hint style="info" %} **** {% endhint %} #### Supported Operations **HTTP GET**\ Returns a list representation of all Call resources for this Account, including the properties above. **HTTP POST**\ Makes a new Call and returns a representation of the Call resource, including the properties above #### Request Parameters | Parameter | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **From(Required)** | The phone number to use as the caller id. | | **To (Required)** | The phone number to call. | | **Url (Required)** | The fully qualified URL that should be executed when the call connects. | | **Method** | The HTTP method CallAPI should use when making its request to the above Url. Defaults to POST. | | **FallbackUrl** | The URL that CallAPI will request if execution of Url fails for any reason. | | **FallbackMethod** |

The HTTP method that CallAPI should use to request the FallbackUrl. Must be either GET or POST.
Defaults to POST.

| | **StatusCallbackEvent** |

A comma separated list of events on which we are interested to get a callback on. Possible values are initiated, ringing, answered, completed.
Defaults to none.

| | **StatusCallback** | URL to receive the callback events at. Defaults to none. | | **StatusCallbackMethod** | Set to GET or POST. Defaults to POST. | | **Timeout** | The number of seconds that CallAPI should allow the phone to ring before assuming there is no answer. Defaults to 60 seconds. | **StatusCallbackEvent** When creating a Call using the Calls API, an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over.\ With **StatusCallbackEvent**, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call. The **StatusCallbackEvent** attribute allows you to specify which events CallAPI should webhook on. To specify multiple events separate them with a comma as follows: *initiated,ringing,answered,completed.* If a StatusCallback is provided and no status callback events are specified, the completed event will be sent by default.. | initiated | The *initiated* event is fired when CallAPI starts dialing the call. | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ringing | The *ringing* event is fired when the call starts ringing. | | answered | The *answered* event is fired when the call is answered**.** | | completed |

The completed event is fired when the call is completed, regardless of the termination status: busy, canceled, completed, failed, or no-answer.
If no StatusCallbackEvent is specified, completed will be fired by default.

| | VoicemailDetector | person\_found or voicemail is sent if the original request had DetectVoicemail on it. | **StatusCallback** The StatusCallback attribute allows you to specify a URL for CallAPI to send webhook requests to on each event specified in the StatusCallbackEvent attribute. **StatusCallbackMethod** The StatusCallbackMethod attribute allows you to specify which HTTP method CallAPI should use when requesting the URL in the StatusCallback attribute. The default is POST **Status Callback HTTP Parameters** The parameters CallAPI passes to your application in an asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when CallAPI receives a call to one of your CallAPI numbers. The full list of parameters and descriptions of each are in the RCML Voice Request documentation. When the call progress events are fired, the Status Callback request also passes these additional parameters: | Parameter | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CallSid** | A unique identifier for this call generated by CallAPI . You can use CallSid to modify the child call by POSTing to Calls/{CallSid} with a new RCML URL. | | **CallStatus** | A descriptive status for the call. The value is one of *queued, initiated, ringing, in-progress, busy, failed, or no-answer*. See CallStatus for more details. | | **CallDuration** | The duration of the just-completed call, in seconds. Only present in the *completed* event. | | **Timestamp** | The timestamp when the event was fired, given as UTC in [RFC 2822](http://php.net/manual/en/class.datetime.php#datetime.constants.rfc2822) format. | | **CallbackSource** | A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always *call-progress-events*. | | **SequenceNumber** | The order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order. | **To redirect or terminate a live call, you make an HTTP POST request to an in¬-progress Call instance resource URI:** ``` /call/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid} or /call/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid} ``` # Example Code {% hint style="info" %} **API Token Notice** You will need both your API Token and your Call API SID (ACCOUNT\_SID). Both are available in User Settings at the top right of the portal. {% endhint %} ### Examples of making calls using the Call API **Full CallAPI URL:** ``` https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls.json ``` This section includes several examples in different languages of how to make calls. The following table includes the supported **POST** variables that can be sent with your **HTTP** calls. #### Request Parameters | Parameter | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **From (Required)** | The phone number to use as the caller id. | | **To (Required)** | The phone number to call. | | **Url (Required)** | The fully qualified URL that should be executed when the call connects. | | **Method** | The HTTP method Platform should use when making its request to the above Url. Defaults to POST. | | **FallbackUrl** | The URL that Platform will request if execution of Url fails for any reason. | | **FallbackMethod** | The HTTP method that Platform should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST. | | **StatusCallbackEvent** | A comma separated list of events on which we are interested in getting a callback on. Possible values are *initiated, ringing, answered, completed*. Defaults to none. | | **StatusCallback** | URL to receive the callback events at. Default none. | | **StatusCallbackMethod** | Set to *GET* or *POST*. Defaults to *POST.* | | **Timeout** |

The number of seconds that the Platform should allow the phone to ring before assuming there is no answer.
The default is 60 seconds.

| You can [view example code here](https://apidocs.api19.com/call-apis/outgoing-calls/making-calls/example-code/outbound-to-tel) # Outbound to Tel\# {% hint style="info" %} **API Token Notice** You will need both your API Token and your Call API SID (ACCOUNT\_SID). Both are available in User Settings at the top right of the portal. {% endhint %} ### Making an outbound call to a telephone number The CallAPI will make a call to USA or international phone number. After the call is made and answered the fourscore.xml file will be played. {% tabs %} {% tab title="Curl" %} ```php curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \ -d 'From=18727738823' \ -d 'To=19392234422' \ -d 'Url=https://example.api19.com/sample.php' \ -u 'API_Token:API_Token' ``` {% endtab %} {% endtabs %} Example Responses is a menu option under Example Code. {% hint style="info" %} **You'll need your CallAPI Account SID and your API Token** {% endhint %} # Outbound to SIP Device ### Making a call to a SIP client You must first create a SIP client in the portal under Connectivity/ SIP Accounts. In the example below, the client created is called Alice. When you make the call, the SIP phone on which Alice is registered will ring and the sample XML will be played. {% tabs %} {% tab title="Curl" %} ```php curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \ -d 'From=16175551212' \ -d 'To=client:alice' \ -d 'Url=https://example.api19.com/sample.php' \ -u 'API_Token:API_Token' ``` {% endtab %} {% endtabs %} > **You can add a custom SIP header by passing X-Custom-Header2=423 in the POST variables.** > > **In curl simply add: -d 'X-Custom-Header2=432' \\** A client can be created in the Clients section of the callapi. Example Responses is a menu option under {% hint style="info" %} You'll need both keys: CallAPI SID and API Token {% endhint %} # Example Responses Responses are sent in JSON or XML forward, depending on your request type ## Successful Responses A successful response will give you all information regarding the call {% tabs %} {% tab title="JSON" %} JSON is the preferred way to receive requests ``` { "sid": "ID308221e44jfd49b7a7231df9773763d8-CA5439261cd19a45b5b7f925c8f9bd78bd", "InstanceId": "ID308221e44jfd49b7a7231df9773763d8", "date_created": "Thu, 23 Apr 2020 03:47:38 +0000", "date_updated": "Thu, 23 Apr 2020 03:47:38 +0000", "account_sid": "AC597c33she92a3aed4f54j58ceb22w6qq", "to": "13035551212", "from": "8142892271", "status": "QUEUED", "start_time": "2020-04-23T03:47:38.000Z", "duration": 0, "price_unit": "USD", "direction": "outbound-api", "api_version": "2012-04-24", "caller_name": "8142892271", "uri": "/2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA5439261cd19a45b5b7f925c8f9bd78bd.json", "subresource_uris": { "notifications": "/2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA5439261cd19a45b5b7f925c8f9bd78bd/Notifications.json", "recordings": "/2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA5439261cd19a45b5b7f925c8f9bd78bd/Recordings.json" } } ``` {% endtab %} {% tab title="XML" %} XML is offered for backward compatibility for other service providers ``` ID308221e44jfd49b7a7231df9773763d8-CA8ccfe7efda354397a0504f47b883cd4e ID308221e44jfd49b7a7231df9773763d8 Thu, 23 Apr 2020 03:43:08 +0000 Thu, 23 Apr 2020 03:43:08 +0000 AC597c33she92a3aed4f54j58ceb22w6qq 13035551212 4843728023 QUEUED 2020-04-23T03:43:08.000Z 0 0.00 USD outbound-api 2012-04-24 4843728023 /2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA8ccfe7efda354397a0504f47b883cd4e /2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA8ccfe7efda354397a0504f47b883cd4e/Notifications /2012-04-24/Accounts/AC597c33she92a3aed4f54j58ceb22w6qq/Calls/ID308221e44jfd49b7a7231df9773763d8-CA8ccfe7efda354397a0504f47b883cd4e/Recordings ``` {% endtab %} {% endtabs %} ## Unsuccessful Responses {% tabs %} {% tab title="JSON Response 1" %} Error responses: ``` {"status":"error", "error":"user inactive"} ``` or ``` {"status":"error", "error":"Resource unavailable error} ``` \ Some responses will contain debug messages if the error is not recognized. {% endtab %} {% tab title="XML Response" %} ``` error user inactive ``` {% endtab %} {% endtabs %} # Modifying Live Calls Real time call modification allows you to interrupt an in-progress call and terminate it or have it begin processing RCML from a new URL. This is useful for any application where use async. Live Call Modification API is supported only for calls created with **Dial** verb using a RCML application. **HTTP POST** **to a Call** {% hint style="info" %} To redirect or terminate a live call, you make an **HTTP POST** request to an in­-progress Call instance resource URI: {% endhint %} ``` /call/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid} or /call/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid} ``` {% hint style="info" %} The following parameters are available for you to **POST** request when modifying a phone call: {% endhint %} ## Request Parameters | Parameter | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Url** | A valid URL that returns RCML. CallAPI will immediately redirect the call to the new RCML. | | **Method** |

The HTTP method CallAPI should use when requesting the above URL.
Defaults to POST.

| | **Status** |

Either canceled or completed.

Specifying canceled will attempt to hang up calls that are queued or ringing but will not affect calls already in progress.
Specifying completed will attempt to hang up a call even if it’s already in progress.

| | **Mute** |

Either true or false.
Setting value of this parameter to true will mute the call. Setting value of this parameter to false will unmute the call.

| ## Call in-Progress Any call that is currently ringing within a Dial verb is in-progress from the point of view of CallAPI, and thus you must use '**Status=completed**' to cancel it. **Optional Parameters** {% hint style="info" %} You may **POST** the following parameters: {% endhint %} **Request Parameters:** | Parameter | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **FallbackUrl** | A URL that CallAPI will request if an error occurs requesting or executing the RCML at Url. | | **FallbackMethod** |

The HTTP method that CallAPI should use to request the FallbackUrl. Must be either GET or POST.
Defaults to POST.

| | **StatusCallback** | A URL that CallAPI will request when the call ends to notify your app. | | **StatusCallbackMethod** | The **HTTP** method CallAPI should use when requesting the above **URL**. Defaults to **POST**. | | **MoveConnectedCallLeg** | If True, CallAPI will move both call legs to the new URL. | ## Description: A prerequisite for the Live Call Modification API is to know the **CallSid** ​of the call. The **CallSid** is generated by CallAPI for every incoming or outgoing call. When we create an outgoing call using the Calls REST API, CallAPI will generate the **CallSid** and the response will contain the **CallSid**. For an Incoming call, CallAPI will generate the **CallSid**, and will include it in the parameters of the **GET** or **POST** request to download the RCML from the application server. So the application server, will get the **CallSid** ​for this incoming call and can store it for later use. **Steps for an incoming call are the following:** * A new incoming call to CallAPI * CallAPI generates CallSid and other parameters for this call * CallAPI prepares GET/POST request and attaches the previously prepared parameters * CallAPI sends the GET/POST request to the URL assigned to the DID called * The Application server receives the GET/POST request * The Application server stores the CallSid along with the rest of the parameters for later use * The Application server prepares the response with the appropriate RCML for the given DID and send it back to CallAPI to process it Given that we have the **CallSid** available, the next step to modify a live call is to prepare the new **POST** request to CallAPI with the URL of the new destination application. Let’s assume that initially the Application server prepared an RCML that will connect the incoming call to Bob and that later Bob wants this call to be transferred to Alice. The Application Server will have to prepare a new RCML that will dial to Alice, and using the Live Call Modification API, will ask CallAPI to process this new RCML for the incoming call and thus will connect it to Alice. **Here are the steps:** * Incoming call - CallSid (1234567890) * Application server - Store CallSid and other parameters, Prepare and send RCML that connects the call to Bob (using Dial verb) * CallAPI process the given RCML and connects incoming call to Bob * Bob wants to transfer the call to Alice and sends the request to Controller (application server) * Application server: - Prepares new RCML with a given URL:\ `http://app.server/CallToAlice` that using *Dial* will dial to Alice - Uses Live Call Modification prepares a new POST request: `https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/YOUR_CALL_SID` - in the POST requests adds the following parameters: Url="**" * CallAPI processes this Live Call Modification request and redirects the incoming call to the new RCML application (to the new URL) * Eventually the incoming call will be connected to Alice. Similarly the application server can change an incoming call to Bob to a conference call where more participants can be added later. Given that application server already knows the CallSid for the incoming call to Bob. * Prepare a new RCML for the Dial Conference * Prepare new POST Live Call Modification request for the incoming call to be connected to the new url (that will dial to the conference) * Prepare new outgoing call request using the Calls Rest API that will connect Bob to the conference application URL:\ `` https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls` `` \ pass the following parameters: From=INCOMING\_CALL\_ID To=client:bob Url=CONFERENCE\_APPLICATION\_URL; * Later the application server can create more outgoing call requests, similar to the one above, to invite other clients, SIP URLs or PSTN numbers to the conference call. # Examples ## Redirect Call to a new RCML {% hint style="info" %} Live Call Modification **POST** request example: {% endhint %} {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Url=http://mycompany.com/api19/demos/dial­alice.xml' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} \ Redirect Call to a new RCML and connect both call legs ------------------------------------------------------ {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Url=http://mycompany.com/tcml/demos/conference.xml' \ -d 'MoveConnectedCallLeg=true' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} \ Terminate In Progress call -------------------------- {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Status=completed' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} ## Terminate Ringing call {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Status=canceled' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} \ Modifying Live Calls - Example ------------------------------ * In order to accomplish this, you need to create a client called Alice * Start a **SIP** phone and register Alice * From the terminal run the following curl command * Make sure Alice is using the port **5061** * The "**From=**" could be any number of your choice * The **Url** is the default sample example provided with CallAPI. ## Modifying a Live Call {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \ -d 'From=+16175551212' \ -d 'To=sip:alice@mycompany.com' \ -d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/callapi/demos/hello-play.xml' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} {% hint style="info" %} **You will see an output similar to the one below:** {% endhint %} ``` { "sid": "CAfa51b104354440b09213d04752f50271", "date_created": "2013-11-01T03:41:14.488-06:00", "date_updated": "2013-11-01T03:41:14.488-06:00", "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "to": "alice", "from": "+16175551212", "status": "queued", "start_time": "2013-11-01T03:41:14.488-06:00", "price": "0.0", "direction": "outbound-api", "api_version": "2012-04-24", "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271.json", "subresource_uris": { "notifications": "/call/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271/Notifications", "recordings": "/call/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271/Recordings" } } ``` Notice the "sid": "CAfa51b104354440b09213d04752f50271", This Call ID is what you must use to interact with the current call. You can now redirect the current call to another application as shown below Notice that the Call ID is referenced The call will now be redirected to the Url specified(hello-play.xml). {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'From=+16175551212' \ -d 'To=sip:alice@mycompany.com' \ -d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/callapi/demos/hello-play.xml' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} {% hint style="info" %} T**he output showing the same Call ID:** {% endhint %} ``` CAfa51b104354440b09213d04752f50271 2013-11-01T03:41:14.488-06:00 2013-11-01T03:41:14.488-06:00 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX alice +16175551212 ..... TRUNCATED ``` ### You can still redirect the current call back to the previous application {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/callapi/demos/hello-play.xml' \ -u 'API_Token' ``` {% endtab %} {% tab title="NodeJS" %} ```javascript const request = require('request'); // Provide your Account Sid and Auth Token from your Console Account page const ACCOUNT_SID = 'my_ACCOUNT_SID'; const AUTH_TOKEN = 'my_AUTH_TOKEN'; // Provide additional path parameters if applicable const CALL_SID = 'my_CALL_SID' request.({ method: 'POST', url: 'https://v1.api19.com/calls/2012-04-24/Accounts/' + ACCOUNT_SID + '/Calls/' + CALL_SID + '.json', auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }, form: { 'Url': 'https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/teleapi/demos/hello-play.xml' } }, function (error, response, body) { // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body' ... }); ``` {% endtab %} {% tab title="Python" %} ```python from http.client import HTTPSConnection from base64 import b64encode from urllib.parse import urlencode # Provide your Account Sid and Auth Token from your Console Account page ACCOUNT_SID = 'my_ACCOUNT_SID' AUTH_TOKEN = 'my_AUTH_TOKEN' // Provide additional path parameters if applicable CALL_SID = 'my_CALL_SID' userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii") headers = { 'Authorization' : 'Basic %s' % userAndPass, 'Content-type': 'application/x-www-form-urlencoded', 'Accept': 'text/plain' } # Update POST parameters accordingly params = urlencode({ 'Url': 'https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/teleapi/demos/hello-play.xml' }) conn = HTTPSConnection('v1.api19.com') conn.request("POST", '/calls/2012-04-24/Accounts/' + ACCOUNT_SID + '/Calls/' + CALL_SID + '.json', params, headers=headers) res = conn.getresponse() # Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read() ... ``` {% endtab %} {% tab title="Java" %} ```java import java.net.URL; import javax.net.ssl.HttpsURLConnection; import java.io.*; import java.util.Base64; public class JavaSampleClass { // Provide your Account Sid and Auth Token from your Console Account page public static final String ACCOUNT_SID = "my_ACCOUNT_SID"; public static final String AUTH_TOKEN = "my_AUTH_TOKEN"; // Provide additional path parameters if applicable public static final String CALL_SID = "my_CALL_SID" public static void main(String[] args) throws Exception { String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN; String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes()); URL url = new URL(("https://v1.api19.com/calls/2012-04-24/Accounts/" + ACCOUNT_SID + "/Calls/" + CALL_SID + ".json"); HttpsURLConnection conn = (HttpsURLConnection)url.openConnection(); conn.setRequestProperty("Authorization", "Basic " + encoded); conn.setRequestMethod("POST"); conn.setDoOutput(true); DataOutputStream os = new DataOutputStream(conn.getOutputStream()); // Update POST parameters accordingly os.writeBytes("Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/api19/demos/hello-play.xml"); os.close(); // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()' ... } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} The output showing the same Call ID {% endhint %} ``` CAfa51b104354440b09213d04752f50271 2013-11-01T03:41:14.488-06:00 2013-11-01T03:41:14.488-06:00 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX alice +16175551212 ..... TRUNCATED ``` You can still redirect the current call back to the previous application {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \ -d 'Status=completed' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} {% hint style="info" %} The output showing the same Call ID {% endhint %} ``` CAfa51b104354440b09213d04752f50271 2013-11-01T03:41:14.488-06:00 2013-11-01T03:41:14.488-06:00 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX alice +16175551212 ..... TRUNCATED ``` You can Mute/unMute an in progress call as shown bellow {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Conferences/CONFERENCE_SID/Participants/CALL_SID.json \ -d 'Mute=true' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Sample Mute Response** {% endhint %} ``` CA02b649d3ffe24408a1e141be089f347b CFcc373b0637114f088eae954fa73f0f57 Wed, 15 Mar 2017 10:10:57 +0000 Wed, 15 Mar 2017 10:15:33 +0000 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX true false true false /2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CA02b649d3ffe24408a1e141be089f347b ``` {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Conferences/CONFERENCE_SID/Participants/CALL_SID.json \ -d 'Mute=false' \ -u 'API_Token' ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Sample unMute Response** {% endhint %} ``` CA02b649d3ffe24408a1e141be089f347b CFcc373b0637114f088eae954fa73f0f57 Wed, 15 Mar 2017 10:10:57 +0000 Wed, 15 Mar 2017 10:16:44 +0000 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX false false true false /2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CA02b649d3ffe24408a1e141be089f347b ``` # Recordings Recordings are created when you use the verb. Recordings are hosted with callapi for you to retrieve. The Recordings list resource represents the set of an account’s recordings. #### 7.6.1 Recording List Resource URI ```php /call/2012-04-24/Accounts/ACCOUNT_SID/Recordings OR /call/2012-04-24/Accounts/{AccountSid}/Recordings/{RecordingSid} ``` {% hint style="warning" %} Unlike the Recording instance resource described above, the list of recordings IS protected by your account credentials like most parts of this API. You must use HTTP basic auth to access the Recordings list resource.\* {% endhint %} **HTTP GET.** Returns a list of all the Recording resources for this Account, including the properties above.\ **HTTP DELETE** Deletes a recording that belongs to this Account. The audio file is named using the RecordingSid and a file extension of .wav. The URLs that contain the actual audio recordings are accessible by everyone without the need to authenticate with callapi. This is per design to allow for your apps to easily access the recordings without revealing your credentials. The same is NOT true for the resource to retrieve the list of recordings. Unauthenticated users cannot access the RecordingSid and hence not able to download the actual recording. | Warning | Warning: Although Recording Sids in Recording URLs are essentially long random strings that are very difficult to guess, you still need to make sure that they don’t fall in the wrong hands. | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ## Resource Properties | Property | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Sid** | A string that uniquely identifies a recording. | | **DateCreated** | The date that the recording was created. | | **DateUpdated** | The date that the recording was last updated. | | **AccountSid** | The unique id of the Account that created the recording. | | **CallSid** | The unique id of the call during which the recording was made. | | **Duration** | The length of the recording, in seconds. | | **ApiVersion** | The API version in use during the recording. | | **Uri** | The URI for this account, relative to `https://v1.api19.com/call/2012-04-24/.` | | **FileUri** | The File URI for this recording, relative to `https://v1.api19.com/call/2012-04-24/`. It can be used to access the WAV file | \ Supported Operations -------------------- **HTTP GET.** Returns the representation of a Recording resource, including the properties above. **HTTP DELETE**. Removes the recording from the account. #### Recording List Resource URI {% hint style="info" %} There is two types of tokens: Call API SID Token and API Token; both must be used. {% endhint %} ### # Get List of Recordings HTTP GET or POST. The query string parameters allow you to limit the list returned. Note: parameters are case-sensitive ## Request Parameters None of the request parameters are required.
ParameterDescription
PageThe current page number. Zero-indexed, so the first page is 0.
0-20000
PageSizeHow many items are on each page
0-2000
StartTimeOnly show recordings that were made on this date/time or later

EndTime value examples allowed:
2024-04-01T10:10:10
2024-04-01 10:10:10
2024-04-01
EndTimeOnly show recordings that were made on this date/time or earlier

EndTime value examples allowed:
2024-04-01T10:10:10
2024-04-01 10:10:10
2024-04-01
CallSidOnly show recordings that have been started from this CallSid
Value: CallSid=h923fh2h32fj23f2
SortBySort by the date created instead of the most recent on top
Value: DateCreated or DateAsc
## Filter using the CallSid parameter. The following example will only return Recordings that have been started from the given CallSid {% tabs %} {% tab title="CURL" %} ```perl curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/Call_API_Token/Recordings.json -d 'CallSid=CAfe9ce46f104f5beeb10c83a5dad2be66' \ -d 'StartTime=2024-04-02 00:00:00' -d 'EndTime=2024-04-02 10:00:00' -d 'SortBy=DateCreated' -u 'API_Token:account_sid' ``` {% endtab %} {% endtabs %} The result will be similar to the one below ```javascript {"page":0,"num_pages":0,"page_size":50,"total":17,"start":"0","end":"17","uri":"/call/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Recordings.json","first_page_uri":"/call/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Recordings.json?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/call/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Recordings.json?Page=0&PageSize=50","recordings": [ { "sid":"RFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "date_created":"Mon, 6 Jan 2024 08:51:07 +0900", "date_updated":"Mon, 6 Jan 2024 08:51:07 +0900", "date_standard":"2024-01-06 08:51:07", "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "call_sid":"CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "duration":"14.70275", "api_version":"2012-04-24", "uri":"/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Recordings/RE50675909d9c94acda36f0e119b6cb431.json", "file_uri":"https://v1.api19.com/call/recordings/RE50675909d9c94acda36f0e119b6cb431.wav" }, ... ] } ``` # Delete a Recording Delete an existing recording {% hint style="info" %} HTTP DELETE **/2012-04-24/Accounts/{AccountSid}/Recordings/{RecordingSid}** or HTTP POST **/2012-04-24/Accounts/{AccountSid}/Recordings** {% endhint %} This function allows you to delete a recording on our system using an HTTP POST or an HTTP DELETE. You can put the recording sid OR just use the file name if it's easier. {% tabs %} {% tab title="CURL POST" %} ``` curl https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Recordings \ -d 'delete_file=recording_sid' -u 'API_Token' ``` {% endtab %} {% tab title="CURL DELETE" %} ```perl curl -X DELETE https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Recordings/RECORDING_SID \ -u 'API_Token:account_sid' ``` {% endtab %} {% endtabs %} #### Possible Responses ```javascript HTTP Status: 200 {"status": "ok"} OR HTTP Status: 404 {"status": "error", "error": "file missing"} ``` # API Call Markup Language Overview The API Call Markup Language (ACML) represents a set of instructions you can use to tell the Call API what to do when you receive an incoming call. When someone makes a call to one of your Call API numbers, the service will look up the URL associated with that phone number and make a request to that URL. The Call API will read the markup instructions at that URL to determine what to do: record the call, play a message for the caller, prompt the caller to press digits on their keypad, etc. {% hint style="info" %} An an example, the following will say a short message, and then record the caller’s voice: {% endhint %} ```markup Please leave a message after the tone. ``` For your initial response to a call, the HTTP Post variable PostStatus will be **new**. ACML is similar to HTML. Only one ACML document is rendered to the caller at once, but many documents can be linked together to build complex interactive voice applications. Calls from a Call API number to an outside number are controlled using ACML in the same manner as incoming calls. The initial URL for the call is provided as a parameter to the Call API request you make to initiate the call. \ How the Call APIs Interacts with Your Application ------------------------------------------------- ### Call API Request The way the Call API passes data to your application depends on the request method for the given URI. If the request method is GET then the data is passed in the query string (the part after the question mark). If the request method is POST then the data is sent as multi-part form data just like when a browser submits a form. When the Call API makes a request to your application it will include the following data as request parameters. ### **Request Parameters**
ParameterDescription
ParameterDescription
CallSidThe unique identifier for the call.
AccountSidYour account id.
FromThe phone number of the originator of the call.
ToThe phone number of the call recipient.
CallStatus

A descriptive status for the call. The value is one of these:

completed, failed, ringing, in-progress, no-answer, queued, or initiated

ApiVersionThe version of the Call API used to handle this call.
DirectionThe direction of the call. The possible values are inbound and outbound-dial.
CallerNameThe caller ID for the caller in the case of an inbound call.
PostStatusThis will be callback or new
new is when the call is first coming in and is brand new
callback are callbacks letting you know the status of the call
### Post Examples New Incoming Call to a DID\ **Notice:** The CallStatus is ringing and the PostStatus is new (meaing a new call) 
HTTP POST Variables
(
    [CallSid] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1-CAd183dab7c2174f61bc3baea248bdac64
    [InstanceId] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1
    [AccountSid] => ACd4fb7d0eefaf3c057a8b9c7774433568
    [From] => 13038881111
    [To] => 7209914899
    [CallStatus] => ringing
    [ApiVersion] => 2012-04-24
    [Direction] => inbound
    [CallerName] => null
    [ForwardedFrom] => null
    [CallTimestamp] => 2026-08-05T21:36:11.909Z
    [CallBackSource] => call-progress-events
    [SequenceNumber] => 1
    [SipCode] => 180
    [SipHeader_X-Originating-DNIS] => +17209914899
    [PostStatus] => new
)
Progress - Answered Call\ **Notice:** The CallStatus is answered and the SipCode is 200 
HTTP POST Variables
(
    [CallSid] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1-CAd183dab7c2174f61bc3baea248bdac64
    [InstanceId] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1
    [AccountSid] => ACd4fb7d0eefaf3c057a8b9c7774433568
    [From] => 13038881111
    [To] => 7209914899
    [CallStatus] => answered
    [ApiVersion] => 2012-04-24
    [Direction] => inbound
    [CallerName] => null
    [ForwardedFrom] => null
    [CallTimestamp] => 2026-08-05T21:34:35.550Z
    [CallBackSource] => call-progress-events
    [SequenceNumber] => 2
    [SipCode] => 200
    [SipHeader_X-Originating-DNIS] => +17209914899
    [PostStatus] => callback
)
Progress - Caller has hung up\ **Notice**: the CallStatus is completed and the SipCode is BYE 
HTTP Post Variables
(
    [CallSid] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1-CAd183dab7c2174f61bc3baea248bdac64
    [InstanceId] => IDe4818a0b8cfc4ca1b3cdad65264e8ba1
    [AccountSid] => ACd4fb7d0eefaf3c057a8b9c7774433568
    [From] => 13038881111
    [To] => 7209914899
    [CallStatus] => completed
    [ApiVersion] => 2012-04-24
    [Direction] => inbound
    [CallerName] => null
    [ForwardedFrom] => null
    [CallTimestamp] => 2026-08-05T21:36:11.909Z
    [CallBackSource] => call-progress-events
    [SequenceNumber] => 3
    [SipCode] => BYE
    [SipHeader_X-Originating-DNIS] => +17209914899
    [PostStatus] => callback
)
### Call API Response In the response to the request from the Call API, you should provide ACML that will instruct our service on how to handle the current call. **MIME Types.** Call API supports the MIME types described in the table below. ### **Supported MIME Types** | Parameter | Description | | ----------------------------- | -------------------------------------------------------------------- | | **text/xml, application/xml** | Call API interprets the returned document as an XML instruction set. | {% hint style="info" %} When your application returns the ACML document the root element of the document must always be specified or the parser will complain. {% endhint %} ## The Markup Verbs Using combinations of the verbs below allow you to create all kinds of interactive voice and messaging applications. * [**Say**](/call-api-markup/api-call-markup-language/say)\ Say some words with text to speech * [**Dial**](/call-api-markup/api-call-markup-language/dial)\ Call someone else, a phone number or other * [**SIP**](/call-api-markup/api-call-markup-language/dial/sip) * [**Client**](/call-api-markup/api-call-markup-language/dial/client) * [**Number**](/call-api-markup/api-call-markup-language/dial/number) * [**Play**](/call-api-markup/api-call-markup-language/play)\ Play a wav or mp3 file to the caller * [**Gather**](/call-api-markup/api-call-markup-language/gather)\ Gather digits or words and send them back to your server * [**Record**](/call-api-markup/api-call-markup-language/record)\ Record the current call * [**Hangup**](/call-api-markup/api-call-markup-language/hangup)\ Hangup on the call * [**Pause**](/call-api-markup/api-call-markup-language/pause)\ Pause the call for a moment (maybe to wait for digits) * [**Reject**](/call-api-markup/api-call-markup-language/reject)\ Reject this call * [**Redirect**](/call-api-markup/api-call-markup-language/redirect)\ Redirect this call to another URL References to ACML, RCML or CML are all the same. # Say The \ verb is used to synthesize text to speech and play it back to the remote party. ## Say Attributes | Name | Description | Allowed Values | Default Value | | ------------ | ------------------------------------------------------------------------- | -------------------- | ------------- | | **language** | Voice and Language | listed at the bottom | kevin | | **loop** | How many times to play the synthesized text. Zero will loop indefinitely. | non-negative integer | 1 | ## Nesting {% hint style="info" %} The **\** verb cannot have any other verbs or nouns nested. Only text can be part of the \ verb. {% endhint %} ## Examples {% hint style="info" %} Below is an example of using the \ verb. {% endhint %} ```markup Hello World ``` {% hint style="info" %} Choose your voice and language based on the list at the bottom of this page {% endhint %} ```markup Hello World ``` ## Voices To use a specific provider specify it in the language attribute, as shown below. Voices are all from AWS Polly. ```markup Danish (da-DK) language="naja-da-DK-female" - Naja language="mads-da-DK-male" - Mads Dutch (nl-NL) language="lotte-nl-NL-female" - Lotte language="ruben-nl-NL-male" - Ruben English (Australian) (en-AU) language="nicole-en-au-female" - Nicole language="olivia-en-au-female" - Olivia language="russell-en-au-male" - Russell English (British) (en-GB) language="amy-en-GB-female" - Amy language="emma-en-GB-female" - Emma language="brian-en-GB-male" - Brian English (Indian) (en-IN) language="aditi-en-IN-female" - Aditi language="raveena-en-IN-female" - Raveena English (US) (en-US) language="ivy-en-US-female" - Ivy language="joanna-en-US-female" - Joanna language="kendra-en-US-female" - Kendra language="kimberly-en-US-female" - Kimberly language="salli-en-US-female" - Salli language="joey-en-US-male" - Joey language="justin-en-US-male" - Justin language="kevin-en-US-male" - Kevin language="matthew-en-US-male" - Matthew English (Welsh) (en-GB-WLS) language="geraint-en-GB-WLS-male" - Geraint French (fr-FR) language="celine-fr-FR-female" - Celine language="lea-fr-FR-female" - Lea language="mathieu-fr-FR-male" - Mathieu French (Canadian) (fr-CA) language="chantal-fr-CA-female" - Chantal German (de-DE) language="marlene-de-DE-female" - Marlene language="vicki-de-DE-female" - Vicki language="hans-de-DE-male" - Hans Icelandic (is-IS) language="dora-is-IS-female" - Dóra/Dora language="karl-is-IS-male" - Karl Italian (it-IT) language="carla-it-IT-female" - Carla language="bianca-it-IT-female" - Bianca language="giorgio-it-IT-male" - Giorgio Japanese (ja-JP) language="mizuki-ja-PA-female" - Mizuki language="takumi-ja-PA-male" - Takumi Norwegian (nb-NO) language="liv-nb-NO-female" - Liv Polish (pl-PL) language="ewa-pl-PL-female" - Ewa language="maja-pl-PL-female" - Maja language="jacek-pl-PL-male" - Jacek language="jan-pl-PL-male" - Jan Portuguese (Brazilian) (pt-BR) language="camila-bp-BR-female" - Camila language="vitoria-bp-BR-female" - Vitoria language="ricardo-bp-BR-male" - Ricardo Portuguese (European) (pt-PT) language="ines-pt-PT-female" - Ines language="cristiano-pt-PT-male" - Cristiano Romanian (ro-RO) language="carmen-ro-RO-female" - Carmen Russian (ru-RU) language="tatyana-ru-RU-female" - Tatyana language="maxim-ru-RU-male" - Maxim Spanish (European) (es-ES) language="conchita-es-ES-female" - Conchita language="lucia-es-ES-female" - Lucia language="enrique-es-ES-male" - Enrique Spanish (Mexican) (es-MX) language="mia-es-MX-female" - Mia US Spanish (es-US) language="lupe-es-US-female" - Lupe language="penelope-es-US-female" - Penelope language="miguel-es-US-male" - Miguel Swedish (sv-SE) language="astrid-sv-SE-female" - Astrid Turkish (tr-TR) language="filiz-tr-TR-female" - Filiz Welsh (cy-GB) language="gwyneth-cy-GB-female" - Gwyneth ``` JSON of all supported languages: ``` { "Danish (da-DK)": [ { "language_use": "naja-da-DK-female", "name": "Naja" }, { "language_use": "mads-da-DK-male", "name": "Mads" } ], "Dutch (nl-NL)": [ { "language_use": "lotte-nl-NL-female", "name": "Lotte" }, { "language_use": "ruben-nl-NL-male", "name": "Ruben" } ], "English (Australian) (en-AU)": [ { "language_use": "nicole-en-au-female", "name": "Nicole" }, { "language_use": "olivia-en-au-female", "name": "Olivia" }, { "language_use": "russell-en-au-male", "name": "Russell" } ], "English (British) (en-GB)": [ { "language_use": "amy-en-GB-female", "name": "Amy" }, { "language_use": "emma-en-GB-female", "name": "Emma" }, { "language_use": "brian-en-GB-male", "name": "Brian" } ], "English (Indian) (en-IN)": [ { "language_use": "aditi-en-IN-female", "name": "Aditi" }, { "language_use": "raveena-en-IN-female", "name": "Raveena" } ], "English (US) (en-US)": [ { "language_use": "ivy-en-US-female", "name": "Ivy" }, { "language_use": "joanna-en-US-female", "name": "Joanna" }, { "language_use": "kendra-en-US-female", "name": "Kendra" }, { "language_use": "kimberly-en-US-female", "name": "Kimberly" }, { "language_use": "salli-en-US-female", "name": "Salli" }, { "language_use": "joey-en-US-male", "name": "Joey" }, { "language_use": "justin-en-US-male", "name": "Justin" }, { "language_use": "kevin-en-US-male", "name": "Kevin" }, { "language_use": "matthew-en-US-male", "name": "Matthew" } ], "English (Welsh) (en-GB-WLS)": [ { "language_use": "geraint-en-GB-WLS-male", "name": "Geraint" } ], "French (fr-FR)": [ { "language_use": "celine-fr-FR-female", "name": "Celine" }, { "language_use": "lea-fr-FR-female", "name": "Lea" }, { "language_use": "mathieu-fr-FR-male", "name": "Mathieu" } ], "French (Canadian) (fr-CA)": [ { "language_use": "chantal-fr-CA-female", "name": "Chantal" } ], "German (de-DE)": [ { "language_use": "marlene-de-DE-female", "name": "Marlene" }, { "language_use": "vicki-de-DE-female", "name": "Vicki" }, { "language_use": "hans-de-DE-male", "name": "Hans" } ], "Icelandic (is-IS)": [ { "language_use": "dora-is-IS-female", "name": "Dora" }, { "language_use": "karl-is-IS-male", "name": "Karl" } ], "Italian (it-IT)": [ { "language_use": "carla-it-IT-female", "name": "Carla" }, { "language_use": "bianca-it-IT-female", "name": "Bianca" }, { "language_use": "giorgio-it-IT-male", "name": "Giorgio" } ], "Japanese (ja-JP)": [ { "language_use": "mizuki-ja-PA-female", "name": "Mizuki" }, { "language_use": "takumi-ja-PA-male", "name": "Takumi" } ], "Norwegian (nb-NO)": [ { "language_use": "liv-nb-NO-female", "name": "Liv" } ], "Polish (pl-PL)": [ { "language_use": "ewa-pl-PL-female", "name": "Ewa" }, { "language_use": "maja-pl-PL-female", "name": "Maja" }, { "language_use": "jacek-pl-PL-male", "name": "Jacek" }, { "language_use": "jan-pl-PL-male", "name": "Jan" } ], "Portuguese (Brazilian) (pt-BR)": [ { "language_use": "camila-bp-BR-female", "name": "Camila" }, { "language_use": "vitoria-bp-BR-female", "name": "Vitoria" }, { "language_use": "ricardo-bp-BR-male", "name": "Ricardo" } ], "Portuguese (European) (pt-PT)": [ { "language_use": "ines-pt-PT-female", "name": "Ines" }, { "language_use": "cristiano-pt-PT-male", "name": "Cristiano" } ], "Romanian (ro-RO)": [ { "language_use": "carmen-ro-RO-female", "name": "Carmen" } ], "Russian (ru-RU)": [ { "language_use": "tatyana-ru-RU-female", "name": "Tatyana" }, { "language_use": "maxim-ru-RU-male", "name": "Maxim" } ], "Spanish (European) (es-ES)": [ { "language_use": "conchita-es-ES-female", "name": "Conchita" }, { "language_use": "lucia-es-ES-female", "name": "Lucia" }, { "language_use": "enrique-es-ES-male", "name": "Enrique" } ], "Spanish (Mexican) (es-MX)": [ { "language_use": "mia-es-MX-female", "name": "Mia" } ], "US Spanish (es-US)": [ { "language_use": "lupe-es-US-female", "name": "Lupe" }, { "language_use": "penelope-es-US-female", "name": "Penelope" }, { "language_use": "miguel-es-US-male", "name": "Miguel" } ], "Swedish (sv-SE)": [ { "language_use": "astrid-sv-SE-female", "name": "Astrid" } ], "Turkish (tr-TR)": [ { "language_use": "filiz-tr-TR-female", "name": "Filiz" } ], "Welsh (cy-GB)": [ { "language_use": "gwyneth-cy-GB-female", "name": "Gwyneth" } ] } ``` # Dial The \ verb connects the current caller to another phone . If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, ## Examples {% hint style="info" %} Examples of using the \ verb. {% endhint %} ```markup 1-444-555-666 ``` ```markup 1-444-555-666 ``` ```markup 1-444-555-666 ``` ## Dial Attributes | Name | Allowed Values | Default Value | | ------------- | -------------------------------------------------------------------------- | ----------------------- | | **action** | relative or absolute URL | no default for \ | | **method** | GET, POST | POST | | **timeout** | positive integer in seconds | 30 seconds | | **timeLimit** | positive integer (seconds) | 14400 seconds (4 hours) | | **callerId** | a valid phone number, or client identifier if you are dialing a \. | Caller’s callerId | | **record** | true, false | false | | **dialMusic** | relative or absolute URL | no default | * **action.** The action attribute takes a URL as the argument. When the dialed call ends, CallAPI will make a GET or POST request to this URL using the parameters below. If an action URL is provided, CallAPI will continue the current call after the dialed party has hung up, using the RCML received in your response to the action URL request. Any RCML verbs occurring after a which specifies an action attribute are unreachable. If no action is provided, will finish and CallAPI will move on to the next RCML verb in the document. If there is no next verb, CallAPI will end the phone call. * **method.** The method attribute takes the value of 'GET' or 'POST'. This tells CallAPI whether to request the action URL via an HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute. * **timeout** The timeout attribute sets the time (in seconds) that waits for the called party to answer the call. * **timelimit** The timeLimit attribute sets the maximum duration of the in seconds. * **callerId** The callerId attribute lets you specify the caller ID that will appear to the called party when CallAPI makes the call.\ By default, when you put a \ in your RCML response to CallAPI's inbound call request, the caller ID that the dialed party sees is the inbound caller’s caller ID. If you are dialing a \ , you can set a client identifier as the callerId attribute.\ For example, if you set up a client for incoming calls and you are dialing it, you could set the callerId attribute to client:thomas. * **record.** The record attribute lets you specify whether the call will be recorded or not. By default, the call is not recorded. If you set the attribute to 'true' CallAPI will start recording when the two calls are bridged.\ The current release of CallAPI does not support recordings for Dial Conference. This feature will be available in the next release. * dialMusic The dialMusic attribute lets you specify a custom RingBack tone to be played. The attribute should be set to a valid URL pointing to WAV file. ### Request Parameters You can nest the following nouns within the \ verb: ,\ , \ and \ . | Parameter | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DialCallStatus** | The outcome of the \ attempt. See the DialCallStatus section below for details. | | **DialCallSid** | The call sid of the new call leg. This parameter is not sent after dialing a conference. | | **DialCallDuration** | The duration in seconds of the dialed call. This parameter is not sent after dialing a conference. | | **RecordingUrl** | The URL of the recorded audio. This parameter is only sent if record="true" is set on the `Dial` verb, and does not include recordings from the \ verb or Record=True on REST API calls.. | **DialCallStatus Values** | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | completed | The called party answered the call and was connected to the caller. | | busy | CallAPI received a busy signal when trying to connect to the called party. | | no-answer | The called party did not pick up before the timeout period passed. | | failed | CallAPI was unable to route to the given phone number. This is frequently caused by dialing a properly formated but non-existent phone number. | | canceled | The call was canceled via the REST API before it was answered. | {% hint style="info" %} The current release of CallAPI doesn’t support recording for Dial Conference. This feature will be available in the next release {% endhint %} **Nesting.** You can nest the following nouns within \: \, \, \ ##
# Number The **\** noun specifies a phone number to dial. You can use multiple **\** nouns within a **\** verb to simultaneously call all of them at once. The first call to pick up is connected to the current call and the rest are hung up. \ Number Attributes ----------------- | Name | Allowed Values | Default Value | | -------------------- | ----------------------------------------------- | ------------- | | url | any url | none | | method | `GET`, `POST` | `POST` | | statusCallbackEvent | `initiated`, `ringing`, `answered`, `completed` | none | | statusCallback | any url | none | | statusCallbackMethod | `GET`, `POST` | `POST` | {% hint style="info" %} **url.** The 'url' attribute allows you to specify a URL for a RCML document that will run on the called party’s end, after he/she answers, but before the parties are connected. You can use this RCML to privately play or say information to the called party, or provide a chance to decline the phone call using \ and \. The current caller will continue to hear ringing while the RCML document executes on the other end. RCML documents executed in this manner are not allowed to contain the \ verb {% endhint %} ### **method** The 'method' attribute allows you to specify which HTTP method CallAPI should use when requesting the URL in the 'url' attribute. The default is POST. ### **statusCallbackEvent** When dialing out to a PSTN Number using \, an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over. With **statusCallbackEvent**, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call. The **statusCallbackEvent** attribute allows you to specify which events CallAPI should webhook on. To specify multiple events separate them with a comma: `initiated,ringing,answered,completed`. If a statusCallback is provided and no status callback events are specified the completed event will be sent by default. As opposed to creating an outbound call via the API, outbound calls created using \ are initiated right away and never queued. The following shows a timeline of possible call events that can be returned and the different call statuses that a \ leg may experience: The **\** noun specifies a PSTN Number to dial. You can use multiple **\** nouns within a **\** verb to simultaneously attempt a connection with many numbers at once. The first number to accept the incoming connection is connected to the call and the other connection attempts are canceled.
| Event | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | initiated | The `initiated` event is fired when CallAPI starts dialing the call. | | ringing | The `ringing` event is fired when the call starts ringing. | | answered | The `answered` event is fired when the call is answered. | | completed | The `completed` event is fired when the call is completed regardless of the termination status: `busy`, `canceled`, `completed`, `failed`, or `no-answer`. If no `statusCallbackEvent` is specified, `completed` will be fired by default. | ### **statusCallback** When dialing out to a PSTN Number using , an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over. \ With statusCallbackEvent, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call. The statusCallbackEvent attribute allows you to specify which events CallAPI should webhook on. \ To specify multiple events separate them with a comma: initiated,ringing,answered,completed. If a statusCallback is provided and no status callback events are specified the completed event will be sent by default. Compared to creating an outbound call via the API, outbound calls created using are initiated right away and never queued. \ The following shows a timeline of possible call events that can be returned and the different call statuses that a leg may experience: The \ noun specifies a PSTN Number to dial. You can use multiple nouns within a verb to simultaneously attempt a connection with many numbers at once. The first number to accept the incoming connection is connected to the call and the other connection attempts are canceled. **statusCallbackMethod** The **statusCallbackMethod** attribute allows you to specify which HTTP method CallAPI should use when requesting the URL in the statusCallback attribute. The default is POST. #### **Status Callback HTTP Parameters** The parameters CallAPI passes to your application in its asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when CallAPI receives a call to one of your CallAPI numbers. The full list of parameters and descriptions of each are in the RCML Voice Request documentation. {% hint style="info" %} When the call progress events are fired, the Status Callback request also passes these additional parameters: {% endhint %} | Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CallSid | A unique identifier for this call, generated by CallAPI. You can use the `CallSid` to modify the child call by POSTing to Calls/{CallSid} with a new RCML URL. | | CallStatus | A descriptive status for the call. The value is one of **`queued`**, **`initiated`**, **`ringing`**, **`in-progress`**, **`busy`**, **`failed`**, or **`no-answer`**. See the CallStatus section for more details. | | CallDuration | The duration in seconds of the just-completed call. Only present in the `completed` event. | | Timestamp | The timestamp when the event was fired, given as UTC in [RFC 2822](http://php.net/manual/en/class.datetime.php#datetime.constants.rfc2822) format. | | CallbackSource | A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always **`call-progress-events`.** | | SequenceNumber | The order in which the events were fired, starting from `0`. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order. | ## Examples {% hint style="info" %} Examples of using the \ verb. {% endhint %} ```markup 1-444-555-666 ``` ```markup 1-444-555-666 ``` ```markup 1-444-555-666 ``` # Client ## Noun Attributes {% hint style="info" %} The `` noun supports the following attributes that modify its behavior: {% endhint %} | Attribute Name | Allowed Values | Default Value | | ------------------------ | ----------------------------------------------- | ------------- | | **name** | String | none | | **url** | any url | none | | **method** | `GET`, `POST` | `POST` | | **statusCallbackEvent** | `initiated`, `ringing`, `answered`, `completed` | none | | **statusCallback** | any url | none | | **statusCallbackMethod** | `GET`, `POST` | `POST` | ### **name** The 'name' attribute allows you to inform the client who will answer to a video call. This attribute should be used only when `