From cf8f7df10c8e5e05ce4ea6bfdb964b0c17804d10 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Wed, 31 May 2023 15:50:57 +0100 Subject: [PATCH 01/15] Alex changes - first 2k lines to new tabbed format --- docs/wholesale/api/v3.md | 1483 +++++++++++++++++++++----------------- 1 file changed, 818 insertions(+), 665 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 08d7acf..01ccea6 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -67,9 +67,9 @@ https://api.simwood.com/v3/tools/time - will return a timestamp from the API You’ll see that in both above cases the output is JSON, e.g: -`` +``` {"timestamp":1388748052,"rfc":"Fri, 03 Jan 2014 11:20:52 +0000"} -`` +``` JSON ("JavaScript Object Notation") is used as it’s a lightweight format designed for exchange of data structures which has an additional advantage of being relatively human readable. All modern languages such @@ -107,7 +107,9 @@ If you pull up an example URL in your browser it’ll do this for you. For your languages will tackle this in different ways but most will ‘just deal with it’ automatically for you. cURL for example, will just take the username and password as parameters, e.g.: -``curl --user name:password https://api.simwood.com/v3/…`` +``` +curl --user name:password https://api.simwood.com/v3/… +``` PHP’s cURL implementation is very similar in that you’d set CURLOPT_USERPWD with [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php). @@ -121,7 +123,9 @@ will need to be replaced with account ID (typically a six digit number)* Which would return the following -``[{"balance":"12.32","currency":"GBP"}] `` +``` +[{"balance":"12.32","currency":"GBP"}] +``` Adding `?pretty=true` to the end of the URL would give you the same information in the following format; ``` @@ -142,6 +146,7 @@ Simwood ### PUT and DELETE requests In the spirit of being REST-ful, many URLs can be acted upon with different methods. The URL does not change, only the HTTP method used against it. One example of this is number configuration, for example; + ``` https://api.simwood.com/v3/numbers/{ACCOUNT}/allocated/{NUMBER} ``` @@ -218,6 +223,7 @@ report and a link to it. As the return suggests, you can retrieve the actual res ``` https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23. ``` + #### But don’t worry... Whilst is is important to understand the effect a given request method will have, we are somewhat relaxed in our interpretation of them where possible. DELETE is always DELETE with no alternative but we will accept a @@ -295,8 +301,9 @@ The functions below are used to retrieve these; /v3/files/{ACCOUNT} `` -|GET|Lists uncollected files on the account | -|:--|:----------------------------------------------------------------------------------| +| Method | Description | +| :----- | :------------------------------------- | +| GET | Lists uncollected files on the account | ```json { @@ -313,8 +320,10 @@ The functions below are used to retrieve these; /v3/files/{ACCOUNT}/{HASH} `` -|GET |Retrieve specific file on account, where HASH is the hash returned when the report was requested. File will be deleted after retrieval. | -|:--|--------------------------------------------------------------------------------------------------------| +| Method | Description | +| :----- | :-------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Retrieve specific file on account, where HASH is the hash returned when the report was requested. File will be deleted after retrieval. | + ## API Endpoints @@ -324,13 +333,14 @@ hopefully consistent. The method shown indicates behaviour as described earlier. Each endpoint is documented below in the following format; -`/v3/URL` +``/v3/URL`` -|GET |Explains what happens when the GET method is used | -|:----|:------------------------------------------------------------------------------------------------------------| -|POST |Explains what happens when the POST method is used. Will also explain what parameter is used for -| |*parameter* - An example GET / POST or PUT parameter | -| |*anotherparam* - Another parameter to be sent by POST | +| Method | Description | +| :----- | :----------------------------------------------------------------------------------------------- | +| GET | Explains what happens when the GET method is used | +| POST | Explains what happens when the POST method is used. Will also explain what parameter is used for | +| | *parameter* - An example GET / POST or PUT parameter | +| | *anotherparam* - Another parameter to be sent by POST | `Please Note ` - Where example responses are shown in this documentation they may be reformatted to be more easily human-readable, the actual response will have escaped slashes (e.g. / replaced with \/) and not @@ -352,50 +362,35 @@ Your IP address, as seen by the Simwood API service ``` curl https://api.simwood.com/v3/tools/myip ``` -| Request Type | result | -|:--|:----| -| GET | Return your external IP address, as seen by the Simwood API| +| Method | Description | +| :----- | :---------------------------------------------------------- | +| GET | Return your external IP address, as seen by the Simwood API | ### Time The current server timestamp ``` curl https://api.simwood.com/v3/tools/time ``` -| Request Type | result | -|:--|:----| -| GET | Returns the current timestamp| +| Method | Description | +| :----- | :---------------------------- | +| GET | Returns the current timestamp | ### Explain This tool is provided to help debug requests to the Simwood API. It accepts any request method (GET, PUT, POST, DELETE etc) and returns a human-readable report of the information submitted. - - -```bash + -curl "https://api.simwood.com/v3/tools/explain?test=1&pretty=true" + | Method | Description | + | :----- | :---------------------------------------------------- | + | ANY | Returns human-readable report of the request received | -or -curl -X POST "https://api.simwood.com/v3/tools/explain?test=1&pretty=true" -``` - - - + - - - - - - - - - -
Request TypeResult
ANY Returns human-readable report of the request receive -
- -``` +```json Simwood API - Explain Tool ======================================================== Query ID: swAPI6410ece80eaff @@ -415,30 +410,31 @@ No JSON Request body ======================================================= Simwood API v3 http://mirror.simwood.com/pdfs/APIv3.pdf ``` - -
- - + + #### NB As this is intended to be a human-readable report for debugging purposes the format may change at any time, and without notice, and should not be relied upon. ## Account Management #### Account Type + + + Your account will be one of the following four types; `developer, startup, virtual_interconnect, or managed_interconnect`, each have different commercials but are functionally identical. All new accounts start off as ‘Developer’, we encourage you to move to ‘Start-Up’ for production use, and to consider ‘Virtual Interconnect’ or ‘Managed Interconnect’ as your requirements evolve. The differences between these account types can be found in the [Simwood Account Pricing](https://cdn.simwood.com/docs/simwood_account_pricing.pdf) document. -##### /v3/accounts/{ACCOUNT}/type - - - ```bash -curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/type - ``` + + +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Get your current account type, and limitations Account type will be one of the following; developer, startup, virtual_interconnect, managed_interconnect | +| PUT | Upgrade or downgrade your account. This option is only available to customers of account_type developer or startup | +| :-- | *account_type* | +| :-- | *startup* upgrade to startup (if developer) | @@ -451,46 +447,36 @@ curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com "number_limit": 5, "channel_limit": 5, "min_prepay": 50 -} } + } +} ``` -please replace all variables above for the curl command to work. check introduction page to see how you can set envronmental variabls in your lab. - -| Request Type | result | -|:--|:----| -| GET | Get your current account type, and limitations Account type will be one of the following; `developer, startup, virtual_interconnect, managed_interconnect` | -| PUT | Upgrade or downgrade your account
This option is only available to customers of account_type `developer` or `startup`
-| | account_type updgrade to `developer`(if startup), or upgrade to `startup`(if developer) | #### Charges Apply -$.. There is a minimum commitment associated with the Start-Up package, along with other commercial differences. Please see the Simwood Product Brochure for more information +There is a minimum commitment associated with the Start-Up package, along with other commercial differences. Please see the Simwood Product Brochure for more information #### PLEASE NOTE -You can migrate between developer and startup at any time. By changing your package type to Start-Up please ensure you are aware of the commercial obligations of this package, including the **minimum pre- payment amount** (which differs from the developer package) and the **minimum total spend** per month, which replaces the service charge of the Developer pack. +You can only migrate from Developer to Start-up. For all other account changes please contact our Operations Desk via eMail to team@simwood.com, or call us on 44330 122 3000 to discuss your requirements further. -It is not possible to switch to our **Virtual Interconnect** or **Managed Interconnect** options online either via the API or Portal. Please contact us if you are interested in these packages. +### Credit Account Management -If you are unsure, please contact our Operations Desk via eMail to team@simwood.com, or call us on 0330 122 3000 to discuss your requirements further. +``` +/v3/accounts/{ACCOUNT}/credit/invoices/* +``` -### Credit Account Management The current status of all invoices on your account is available through the API. - + -```bash -#List of unpaid invoices on account (since June 2010) -curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/unpaid - -#List of paid invoices on account (since June 2010) -curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/paid - -#List of invoices on account (since June 2010) -curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/all -``` +| Method | Endpoint | Description | +| :------ | :-------------------------------------------- | :--------------------------------------------------- | +| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/unpaid | List of unpaid invoices on account (since June 2010) | +| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/paid | List of paid invoices on account (since June 2010) | +| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/all | Upgrade or downgrade your account | @@ -521,20 +507,28 @@ curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com #### PDF Copy Invoices + ``` /v3/accounts/{ACCOUNT}/credit/invoices/{INVOICE_NUMBER}[.pdf] ``` - +| Method | Description | +| :----- | :--------------------------------------------------------------------- | +| GET | Get invoice INVOICE_NUMBER as a pdf file. The .pdf suffix is optional. | ### Prepay Account Management -`/v3/accounts/{ACCOUNT}/prepay/summary` + +``` +/v3/accounts/{ACCOUNT}/prepay/summary +``` - + +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | Requests a report of Summary of account movements. If the optional from_date and to_date parameters are not specified will default to today. | +| :-- | *from_date* Start date of report (in form YYYY-MM-DD) | +| :-- | *to_date* End date of report (in form YYYY-MM-DD) | - ```bash -curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/prepay/summary - ``` @@ -554,33 +548,60 @@ curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.sim -| | | -|:--|:-------| -| POST | Requests a report of Summary of account movements. If the optional *from_date* and *to_date* parameters are not specified will default to today.
**from_date** Start date of report (in form YYYY-MM-DD)
**to_date** End date of report (in form YYYY-MM-DD) | -**Other examples** -```bash -#GET List all account pre-payments +``` /v3/accounts/{ACCOUNT}/prepay/prepayments/all +``` -#GET List last (1) or last ten (10) pre-payments to account +| Method | Description | +| :----- | :----------------------------- | +| GET | List all account pre-payments. | + +``` /v3/accounts/{ACCOUNT}/prepay/prepayments/latest/[1|10] +``` + +| Method | Description | +| :----- | :----------------------------------------------------- | +| GET | List last (1) or last ten (10) pre-payments to account. | -#GET Transfers between this prepay account and others. + +``` /v3/accounts/{ACCOUNT}/prepay/transfers/all +``` + +| Method | Description | +| :----- | :------------------------------------------------ | +| GET | Transfers between this prepay account and others. | -#List last (1) or last ten (10) transfers on the prepay account + +``` /v3/accounts/{ACCOUNT}/prepay/transfers/latest/[1|10] ``` -#### Prepay Account Balance -The API provides tools for checking and protecting your pre-paid balance(s) +| Method | Description | +| :----- | :-------------------------------------------------------------- | +| GET | List last (1) or last ten (10) transfers on the prepay account. | -```bash -#Return balance of account + +#### Prepay Account Balance +``` /v3/accounts/{ACCOUNT}/prepay/balance ``` -*Example result* +The API provides tools for checking and protecting your pre-paid balance(s) + + + + + +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Return balance of account.| + + + + + ```json [ { @@ -589,20 +610,30 @@ The API provides tools for checking and protecting your pre-paid balance(s) } ] ``` + + #### Low Balance Alerts + +``` +/v3/accounts/{ACCOUNT}/prepay/balance/alert +``` + You can set an amount at which you will receive a notification (configured via the notifications, detailed below) when your balance drops below the specified amount. A maximum of **one** notification will be sent per day. -` /v3/accounts/{ACCOUNT}/prepay/balance/alert` - - - - - - - - - + + -
GET + + +| Method | Description | +| :----- | :---------------------------------------------------- | +| GET | Returns the current level of alert. | +| PUT | Sets the alert balance to the specified alert_balance | -Returns the current level of alert.
-```bash + + + +```json [ { "account": ACCOUNT, @@ -611,38 +642,44 @@ Returns the current level of alert.
] ``` -
PUT - -Sets the alert balance to the specified alert_balance
- -**alert_balance** The balance at which an alert should be generated - -
+#### Balance Locking +``` +/v3/accounts/{ACCOUNT}/prepay/balance/locked +``` -#### Balance Locking We provide the ability to ‘lock’ a portion of your balance to make it unavailable to spend. i.e. you can specify the balance at which we’ll treat your account as ‘out of credit’ and therefore kill calls in progress. This is normally zero but the balance locking facility enables customers to keep large credit balances without risking the entire amount in the event that they, or a customer, suffer a compromise. You can set alerts based on the *available* balance (i.e. balance-locked balance) using the balance alert above. + + +| Method | Description | +| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | +| PUT | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent. | +| :-- | *balance* The amount to be protected. | +| DELETE | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | + + + + + +```json +[{"account":ACCOUNT,"balance":10.4688,"locked":5,"available":5.4688}] +``` + + + + -`/v3/accounts/{ACCOUNT}/prepay/balance/locked` -| Method | Description | -|:--|:-------| -| **GET** | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend
```[{"account":ACCOUNT,"balance":10.4688,"locked":5,"available":5.4688}]``` | -| **PUT** | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent.
*balance* The amount to be protected.| -| **DELETE** | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | **NB** *The above ‘locked balance’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account.* @@ -651,16 +688,24 @@ You can set alerts based on the *available* balance (i.e. balance-locked balance ### Termination Rate Functions #### Available Tariffs + +``` +/v3/accounts/{ACCOUNT}/rates/tariffs +``` + Some account types have more than one available tariff or rate deck, these can be viewed as follows where this is applicable to your account; -`/v3/accounts/{ACCOUNT}/rates/tariffs` -| Method| Description| -|:--|:--| -| GET |Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck)| + + + +| Method | Description| +| :----- |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck) | -*Example result* + + ```json { @@ -683,51 +728,52 @@ Some account types have more than one available tariff or rate deck, these can b ] } ``` + + + #### Ratecard Downloads (CSV Format) -Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API; +``` +/v3/accounts/{ACCOUNT}/rates/csv/[default|silver|platinum|gold|name] +``` -`/v3/accounts/{ACCOUNT}/rates/csv/[default|silver|platinum|gold|name]` +Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API; - + +| Method | Description | +| :----- | :---------------------------------------- | +| GET | Request the latest ratecard in CSV Format | - ```bash - #Get Request the latest ratecard in CSV Format -curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/rates/csv/default - ``` -```bash +```csv Effective: 2023-03-10 "prefix","location","day","evening","weekend","connection","minimum_sec","increment_sec" 44113403,"UK - Fixed - Simwood",0.000310,0.000310,0.000310,0.0000,1,1 44113454,"UK - Fixed - Simwood",0.000310,0.000310,0.000310,0.0000,1,1 - ``` + + **NB: The options silver, platinum and gold are only for ‘legacy’ or ‘startup’ account types with multiple rate decks. Virtual Interconnect and Managed Interconnect customers should use default or the file name provided from the above query** -
#### Destination Lookup -`/v3/accounts/{ACCOUNT}/rate/{NUMBER}` - -| Method| Description| -|:--|:--| -| GET |Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge.| +``` +/v3/accounts/{ACCOUNT}/rate/{NUMBER} +``` - + +| Method | Description | +| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge. | - ```bash - #Get Note number is in 164 format. ie UK is 44XXXXXXXXXX -curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/rate/$NUMBER - ``` @@ -745,37 +791,50 @@ curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.sim + ### General Accounting Reports / CDRs -`/v3/accounts/{ACCOUNT}/reports/voice/summary/day/[in|out]` +``` +/v3/accounts/{ACCOUNT}/reports/voice/summary/day/[in|out] +``` -| Method| Description| -|:--|:--| -| **POST** | Request a summary of [incoming] or [outgoing] voice charges
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------- | +| POST | Request a summary of [incoming] or [outgoing] voice charges. | +| | *date* Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | -`/v3/accounts/{ACCOUNT}/reports/voice/cdr/day` +``` +/v3/accounts/{ACCOUNT}/reports/voice/cdr/day +``` -| Method| Description| -|:--|:--| -| **POST** | Request daily CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current.| +| Method | Description | +| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | Request daily CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | -`/v3/accounts/{ACCOUNT}/reports/voice/cdr/latest/[10|100|1000|10000]` +``` +/v3/accounts/{ACCOUNT}/reports/voice/cdr/latest/[10|100|1000|10000] +``` -| Method| Description| -|:--|:--| -| **POST** | Request report of last [ 10 \| 100 \| 1,000 \| 10,000 ] Voice CDRs | +| Method | Description | +| :----- | :-------------------------------------------------------------- | +| POST | Request report of last [ 10 \ 100 \ 1,000 \ 10,000 ] Voice CDRs | -`/v3/accounts/{ACCOUNT}/reports/sms/cdr/day` +``` +/v3/accounts/{ACCOUNT}/reports/sms/cdr/day +``` -| Method| Description| -|:--|:--| -| **POST** |Request daily SMS CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| Method | Description | +| :----- | :--------------------------------------------------------------------------------------------------------------- | +| POST | Request daily SMS CDR report | +| | *date* Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | -`/v3/accounts/{ACCOUNT}/reports/sms/cdr/latest/[10|100|1000|10000]` +``` +/v3/accounts/{ACCOUNT}/reports/sms/cdr/latest/[10|100|1000|10000] +``` -| Method| Description| -|:--|:--| -| **POST** | Request report of last [ 10 \| 100 \| 1,000 \| 10,000 ] SMS CDRs | +| Method | Description | +| :----- | :------------------------------------------------------------ | +| POST | Request report of last [ 10 \ 100 \ 1,000 \ 10,000 ] SMS CDRs | ### Summary Reports (Instant) @@ -785,30 +844,32 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon **NB These are intended to be indicative only and are not suitable for billing purposes.** -`/v3/accounts/{ACCOUNT}/summary/([in|out])/{KEY}` - -| Method| Description| -|:--|:--|:--| -| GET / POST | | Request an inbound or outbound summary report by {KEY} (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown.
The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | -| |date_start | Optionally specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | -| |limit|Optionally specify limit of results to return, default 9999| -| |sort|Key to sort by| -| |filter| Array of "search_key" => "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST" | - - -#### Summary Report Keys -The following keys are available for summary reports; +``` +/v3/accounts/{ACCOUNT}/summary/([in|out])/{KEY} +``` -| Key| Description| -|:--|:--| -| **destid** | Summary by Destination ID | -| **iso** | Summary by ISO Country Code (of destination) | -| **codec** | Summary by Codec | -| **tag** | Summary by Tag (as set with "X-simwood-tag" header) | -| **trunk** | Summary by Trunk | +Tabs> + +| Method | Description | +| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET / POST | Request an inbound or outbound summary report by {KEY} (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | +| | *date_start* Optionally specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | +| | *limit* Optionally specify limit of results to return, default 9999 | +| | *sort* Key to sort by | +| | *filter* Array of "search_key" => "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST" | -#### Example Summary Report -The report below was generated based on a key of ‘trunk’ with a sort of ‘calls’; + + + +| Key | Description | +| :----- | :-------------------------------------------------- | +| destid | Summary by Destination ID | +| iso | Summary by ISO Country Code (of destination) | +| codec | Summary by Codec | +| tag | Summary by Tag (as set with "X-simwood-tag" header) | +| trunk | Summary by Trunk | + + ```json [ @@ -830,71 +891,105 @@ The report below was generated based on a key of ‘trunk’ with a sort of ‘c } ] ``` + + + #### Event Notifications +``` +/v3/accounts/{ACCOUNT}/notifications +``` + Some notifications can now (as of v3.15) be received via Webhooks, for more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf -`/v3/accounts/{ACCOUNT}/notifications` + + +| Method | Description | +| :----- | :-------------------------------------------- | +| GET | List available notifications on your account. | + -| Method| Description| -|:--|:--| -| **GET** |List available notifications on your account
`["blocked_calls","prepay_debit"]` | + + -
+``` +["blocked_calls","prepay_debit"] +``` + + -`/v3/accounts/{ACCOUNT}/notifications/available` +``` +/v3/accounts/{ACCOUNT}/notifications/available +``` -| Method| Description| -|:--|:--| -| **GET** |List available notification TYPEs | +| Method | Description | +| :----- | :-------------------------------- | +| GET | List available notification TYPEs | -`/v3/accounts/{ACCOUNT}/notifications/{TYPE}` +``` +/v3/accounts/{ACCOUNT}/notifications/{TYPE} +``` -| Method| Description| -|:--|:--| -| **GET** | List configured recipients for notifications of {TYPE} | -| **DELETE** | Delete all configured notifications of {TYPE} | +| Method | Description | +| :----- | :----------------------------------------------------- | +| GET | List configured recipients for notifications of {TYPE} | +| DELETE | Delete all configured notifications of {TYPE} | -`/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}` +``` +/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD} +``` -| Method| Description| -|:--|:--| -| **GET** |Shows all configured recipients of notifications of {TYPE} using {METHOD}
METHOD is one of email or sms* | -|**POST**|Add a new notification recipient to receive notifications of {TYPE} using {METHOD}. Returns a hash corresponding to this recipient
*destination* eMail address or Mobile Number (in E164 format) of the recipient.| +| Method | Description | +| :----- | :--------------------------------------------------------------------------------------------------------------------------------- | +| GET | Shows all configured recipients of notifications of {TYPE} using {method} | +| :-- | *method* is one of **email** or **sms** | +| POST | Add a new notification recipient to receive notifications of {TYPE} using {METHOD}. Returns a hash corresponding to this recipient | +| :-- | *destination* eMail address or Mobile Number (in E164 format) of the recipient. | -`/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}/{HASH}` +``` +/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}/{HASH} +``` -| Method| Description| -|:--|:--| -| **GET** |Shows the ifnormation on this recipient| -|**DELETE**| Deletes this recipient | +| Method | Description | +| :----- | :-------------------------------------- | +| GET | Shows the ifnormation on this recipient | +| DELETE | Deletes this recipient | The {HASH} referred to above can be generated locally and is simply an md5()’d version of the notification address. This is used simply to avoid potential url encoding issues. -** *SMS** notification requires credit balance, sent messages will be deducted from your usual credit. +NB **SMS** notification requires credit balance, sent messages will be deducted from your usual credit. -`/v3/accounts/{ACCOUNT}/notifications/history` +``` +/v3/accounts/{ACCOUNT}/notifications/history +``` -| Method| Description| -|:--|:--|:--| -| **GET** | | Retrieve a history of recent (last 60 days) notifications on your account All parameters below are optional, by default will return all notifications for the last 60 days.
Returns a JSON Array of Objects, each Object contains a "data" attribute which contains an Object containing all variables in the original notification.
Please note if the original message contained a password it will be redacted and replaced with ###### as these are not stored.| -| | *class* | Class of notification ( e.g. trunk or billing ) | -| | *date_start* | Start date (no more than 60 days ago) | -| | *date_end* | End date (YYYY-MM-DD HH:ii:ss) | +| Method | Description | +| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Retrieve a history of recent (last 60 days) notifications on your account All parameters below are optional, by default will return all notifications for the last 60 days.Returns a JSON Array of Objects, each Object contains a "data" attribute which contains an Object containing all variables in the original notification. Please note if the original message contained a password it will be redacted and replaced with ###### as these are not stored. | +| | *class* Class of notification ( e.g. trunk or billing ) | +| | *date_start* Start date (no more than 60 days ago) | +| | *date_end* End date (YYYY-MM-DD HH:ii:ss) | ## Voice Termination ### Account Limits (and Dynamic Channel Limits) -`/v3/voice/{ACCOUNT}/limits` - -**GET** Shows limits in effect on an account including any Dynamic Channel Limits +``` +/v3/voice/{ACCOUNT}/limits +``` + + +| Method | Description | +| :----- | :------------------------------------------------------------------------ | +| GET | Shows limits in effect on an account including any Dynamic Channel Limits | -```json + + +```json { "channel_allocation": 30, "channel_allocation_global_numbers": 10, @@ -913,11 +1008,15 @@ The {HASH} referred to above can be generated locally and is simply an md5()’d "limit_rate_out": "30/10s" } } ``` + + + #### Dynamnic Channel Limits Applies only to accounts without a dedicated channel allocation Any dynamic channel limits shown in the "dynamic" block take precedence over the usual account limits. e.g. in the above example due to the low balance there is a concurrent channel limit of 3 channels and a rate limit of 30 calls per 10 seconds. + #### Channel Allocation (Inbound/Outbound) Applies only to accounts with a dedicated channel allocation @@ -936,63 +1035,56 @@ We impose these limits to protect and manage our network utilisation. If you require more channels or a higher rate of calls per second please contact team@simwood.com ### Adjusting your Channel Allocation -Customers with a dedicated channel allocation can manage this allocation, splitting channels between inbound and outbound as required. -`/v3/voice/{ACCOUNT}/limits` - +``` +/v3/voice/{ACCOUNT}/limits +``` - +Customers with a dedicated channel allocation can manage this allocation, splitting channels between inbound and outbound as required. - - + + +| Method | Description | +| :----- | :----------------------------------------------------------------- | +| PUT | Update channel limits | +| | *limit_concurrent_in* inbound channel limit | +| | *limit_concurrent_out* outbound channel limit | +| | NB the above must, together, total the value of channel_allocation | - - - - - - + + -```bash +```json { "limit_concurrent_in": 10, "limit_concurrent_out": 20 } ``` + + - - - - - - - - -
PUT -Update channel limits
-
JSON request
limit_concurrent_ininbound channel Limit
limit_concurrent_outoutbound channel Limit
NB the above must, together, total the value of channel_allocation
JSON response -```bash -{ - "success": true - "data": { - "limit_concurrent_in": 10, - "limit_concurrent_out": 20 -} } -``` -
+### Channel Statistics +``` +/v3/voice/{ACCOUNT}/channels/current +``` -### Channel Statistics -`/v3/voice/{ACCOUNT}/channels/current` + + +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------------- | +| GET | Current channel utilisation | +| | NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below | -```json -# GET Current channel utilisation -NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below + + + +```json [ { "datetime": "2014-02-30 12:34:35", @@ -1002,30 +1094,28 @@ NB: this is returned as an array (with one member) for compatibility with the /c } ] ``` + + -`/v3/voice/{ACCOUNT}/channels/history` - +``` +/v3/voice/{ACCOUNT}/channels/history +``` + + +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------------- | +| GET | Recent (around 24h) channel utilisation samples | +| | The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one. | +| | *1m* One minute | +| | *5m* (Default) Five Minutes | +| | *1h* One Hour | - - - - - - - - - - - - -
GET -
Recent (around 24h) channel utilisation samples -The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one.
interval
-Optional interval for samples in the following form; -
1m - One Minute -
5m - Five Minutes(Default) -
1h - Hourly
+ + ```json - [ { "datetime": "2023-03-18 17:40:00", @@ -1050,34 +1140,28 @@ Optional interval for samples in the following form; "channels": 11, "channels_out": 10, "channels_in": 1 - }, - .... + } ] - ``` - -
+ + ### Real-Time Calls in Progress -`/v3/voice/{ACCOUNT}/inprogress/current` +``` +/v3/voice/{ACCOUNT}/inprogress/current +``` + + +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------------- | +| GET | Number and value of calls in progress relative to account balance. Useful for fraud monitoring. | - - - - - - - - - - - -
GET -
Number and value of calls in progress relative to account balance. Useful for fraud monitoring.
+ + ```json @@ -1127,12 +1211,8 @@ Optional interval for samples in the following form; } ``` - -
+ + **As of version 3.15 this information is now also able to be pushed directly to you via Webhooks, for more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** @@ -1142,15 +1222,20 @@ The above example shows many calls in progress to the UK, along with two to Mexi See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/** for some examples of how this data can be used to help protect you against fraud and monitor your VoIP traffic. ### Call Control -`/v3/voice/{ACCOUNT}/inprogress/{CALL_ID}` - +``` +/v3/voice/{ACCOUNT}/inprogress/{CALL_ID} +``` + + +| Method | Description | +| :----- | :------------------------------------------ | +| GET | Get information on current call in progress | +| DELETE | End a call in progress | - - - -Get information on current call in progress + + ```json { @@ -1161,71 +1246,85 @@ See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/* "progress": "2019-09-23 12:27:17", "answered": "2019-09-23 12:27:21", "destid": "2303" -} } + } + } ``` + + - - - - -End a call in progress +**This is designed to be used in conjunction with the Webhook HTTP Events (Beta) detailed at https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** -```json -{ - "success": true -} +The {CALL_ID} in the above URL is the call_id element in the JSON objects you receive for call_inbound, call_outbound and inprogress_calls HTTP Webhook events posted to your platform. + +As this is a BETA endpoint, the information returned from the above may change at any time, although we will endeavour to ensure backwards compatibility therefore, whilst parameters will be added, it is unlikely that any of the above will be removed. +### Voice CDRs (Inline Response) + +``` +/v3/voice/{ACCOUNT}/cdr ``` +In addition to the CDR Reports (above) you can retrieve any CDRs from the last three months with a simple inline response (rather than polling for a report) - - -
GET
DELETE
-**This is designed to be used in conjunction with the Webhook HTTP Events (Beta) detailed at https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** + + +| Method | Description | +| :----- | :------------------------------------------ | +| GET | Get information on current call in progress | +| DELETE | End a call in progress | -The {CALL_ID} in the above URL is the call_id element in the JSON objects you receive for call_inbound, call_outbound and inprogress_calls HTTP Webhook events posted to your platform. -As this is a BETA endpoint, the information returned from the above may change at any time, although we will endeavour to ensure backwards compatibility therefore, whilst parameters will be added, it is unlikely that any of the above will be removed. + + -### Voice CDRs (Inline Response) +```json +{ + "success": true, + "data": { + "to": "447700900123", + "start": "2019-09-23 12:27:12", + "progress": "2019-09-23 12:27:17", + "answered": "2019-09-23 12:27:21", + "destid": "2303" + } + } -In addition to the CDR Reports (above) you can retrieve any CDRs from the last three months with a simple inline response (rather than polling for a report) +``` + + -`/v3/voice/{ACCOUNT}/cdr` +| Method | Description | +| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET/POST | Both GET and POST are supported. The request can either be made as a GET query string or JSON POST body. At present, the filter attribute is only supported where requested by POST with a JSON body. | +| | date_start Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | +| | *date_end* Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_end, otherwise defaults to now. | +| | *limit* Optionally specify limit of results to return, default 500 | +| | *start* Optional offset to start from (for pagination) | +| | *filter* Object of "search_key" => "value" e.g. {"trunk": "930000- TEST"} would return CDRs only for the trunk named "930000- TEST". | +| | At present you can filter only on the following values, more will be added in the future; **from, to, toISO, trunk, tag** | -| Method| Description| -|:--|:--|:--| -| **GET/POST** | | Both GET and POST are supported. The request can either be made as a GET query string or JSON POST body. At present, the filter attribute is only supported where requested by POST with a JSON body. | -|| date_start | Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | -| | date_end | Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_end, otherwise defaults to now. | -| | limit | Optionally specify limit of results to return, default 500 | -| | start | Optional offset to start from (for pagination) | -| | filter | Object of "search_key" => "value" e.g. {"trunk": "930000- TEST"} would return CDRs only for the trunk named "930000- TEST".
At present you can filter only on the following values, more will be added in the future; **from, to, toISO, trunk, tag** | +``` +/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD} +``` -`/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}` +| Method | Description | +| :------- | :------------------------------------------------------------------------------------------------------------------- | +| GET/POST | As above, a shorthand way of retrieving CDRs for a particular day. The date must be within the last 90 calendar days | +| | *limit* Optionally specify limit of results to return, default 500 | +| | *start* Optional offset to start from (for pagination) | +| | *filter* As above | -| Method| Description| -|:--|:--|:--| -| **GET/POST** | | As above, a shorthand way of retrieving CDRs for a particular day. The date must be within the last 90 calendar days | -| | limit | Optionally specify limit of results to return, default 500| -| | start | Optional offset to start from (for pagination) | -| | filter| As above| -
+``` +/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}/{REFERENCE} +``` -*/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}/{REFERENCE}* - - - - - -
GET Retrieve more information, where available, on a specific call using the reference value returned from the above CDRs (or the CDR Reporting) -
+ **This function is temporarily unavailable as of version v3.10.5 ** @@ -1233,18 +1332,23 @@ Retrieve more information, where available, on a specific call using the referen ### Rejected Calls +``` +/v3/voice/{ACCOUNT}/rejected +``` + When calls are rejected by Simwood for any reason (e.g. exceeding a channel limit, invalid CLI information, or because they are on a blacklist or your own do not call list) no CDR is generated and, therefore, they cannot be retrieved with the above endpoints. These rejections are notified using the notification endpoint you have configured (e.g. by eMail or HTTP post) Additionally, the most recent rejections can be retrieved from the following API endpoints. -`/v3/voice/{ACCOUNT}/rejected` + + +| Method | Description | +| :----- | :----------------------------------------- | +| GET | Get all available recently rejected calls. | - - - - + + ```json @@ -1264,23 +1368,47 @@ These rejections are notified using the notification endpoint you have configure ] } ``` - - - -
GET Get all available recently rejected calls -
+ + -`/v3/voice/{ACCOUNT}/rejected/{REASON}` +``` +/v3/voice/{ACCOUNT}/rejected/{REASON} +``` + + + + +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------- | +| GET | As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli"). | + + + + + +```json + +{ + "success": true, + "data": [ + { + "calldate": "2016-02-08 07:00:04", + "reason": "maxcost", + "from": "441632496000", + "to": "447700900123", + "message": "Call to 447700900123 will exceed 0.1 ( 0.25450 )", + "source_ip": "10.0.0.0", + "trunk": "9XXXXX-L001", + "notified": false + } + ] +} +``` + + - - - - - -
GET -As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli") -
**NB** Rejection data should be considered ephemeral. In any event the above endpoints will never return more than data from the current day and the preceding day. @@ -1290,51 +1418,58 @@ As above, but an optional REASON is specified to return only rejections of the s ### Trunk Management -Trunks should following the naming ACCOUNT-{ID} e.g. if your account is 930004 and the trunk for ACME Products you could name the trunk 930004-ACMEPRODUCTS.
+``` +/v3/voice/{ACCOUNT}/trunks +``` + +Trunks should following the naming ACCOUNT-{ID} e.g. if your account is 930004 and the trunk for ACME Products you could name the trunk 930004-ACMEPRODUCTS. The "L001" trunk is your default **IP-Authenticated** trunk and cannot be renamed, additionally there are some features (Trunk Balances, Realtime Trunk Calls in Progress etc) that are not available on the L001 trunk. -`/v3/voice/{ACCOUNT}/trunks` +| Method | Description | +| :----- | :------------------------------- | +| GET | List all active outbound trunks. | - - - - - -
GET -List all active outbound trunks. -
-`/v3/voice/{ACCOUNT}/trunks/{TRUNK}` +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK} +``` | Method| Description| |:--|:--| -| **GET** | Request information on specified {TRUNK} | -| **PUT** | Create new trunk {TRUNK}
**NB for an ‘auth’ trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions)

or (if additional optional configuration parameters specified, see overleaf)**
Update existing {TRUNK} settings such as channel and rate limits

When creating a new trunk, the **type** can be one of;
**IP** create an IP-authenticated Trunk
**auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| -| **DELETE** | Delete trunk {TRUNK}
**NB the default trunk {ACCOUNT}-L001 cannot be deleted** | +|GET | Request information on specified {TRUNK} | +| PUT | Create new trunk {TRUNK}| +||NB for an ‘auth’ trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions) or (if additional optional configuration parameters specified, see overleaf) Update existing {TRUNK} settings such as channel and rate limits.| +||When creating a new trunk, the **type** can be one of; **IP** create an IP-authenticated Trunk or **auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| +| DELETE | Delete trunk {TRUNK} **NB the default trunk {ACCOUNT}-L001 cannot be deleted** | Newly created trunks are available for use immediately although, at times, may not show in the outbound trunk list for a short time. #### Trunk Options -`/v3/voice/{ACCOUNT}/trunks/{TRUNK}` -| Method| Description| -|:--|:--|:--| -| **PUT** | | Update existing {TRUNK} settings such as channel and rate limits
**The options below are only to be used when updating an existing trunk**| -|| *enabled*
*[optionala]*| Enable [1] or Disable [0] this trunk.
NB this takes precedence over in/out below| -||*enable_in*
*[optional]* | Enable [1] or Disable [0] inbound calls on this trunk (when being used via SIP registration)| -|| *enabled_out*
*[optional]* | Enable [1] or Disable [0] outbound calls on this trunk. | -|| *limit_concurrent\_\* *
*[optional]*
The * above to be replaced by one of the parameters opposite | Concurrent channel limit for the class of calls indicated as an integer value or [null] (do not impose a limit)
**out out_international
out_international_hotspot out_per_number in** | -|| *limit_rate\_\* *
*[optional]* | Rate limit for each of the above outbound categories in the form calls/duration (or [null] where no limit) e.g.
**5/10s** 5 calls per 10 seconds
**100/12h** 100 calls in 12 hours
**NB The timeframe must be one of [ 12h \| 10s \| 1s ]** | -|| *cli_format*
*[optional]* | For inbound calls associated with this trunk, receive the CLI in the selected format, one of [ e164 \| +164 \| uk \| us ] | -|| *cli_default*
*[optional]* | Default Presentation Number to be presented when no valid CLI is provided or cli_force_default set (E164 format)| -|| *cli_force_default*
*[optional]* | Set to [1] to force above value to be used on all calls. [0] allows customer-specified CLI | -|| *nni_default*
*[optional]* | Default Network Number to be used when required **must be a number on your account** in E.164 format (e.g.441632960123) | -|| *max_cpm*
*[optional]* | Maximum cost per minute (in your billing currency) of the B leg of the call. Using this can help ensure a customer trunk cannot make calls to expensive destinations | -|| *max_cpc*
*[optional]* | To be used in conjunction with the above, sets a maximum connection cost per call.| -|| *max_cost*
*[optional]* | Sets a maximum cost per call, i.e. when the cost of the call reaches (approximately) this amount it will be cleared | -|| *max_dur*
*[optional]* | Sets a maximum duration per call, when the call reaches this duration, it will be cleared. | -|| *emergency_enabled*
*[optional]* | Set to [1] to enable emergency calls (requires account activation) | +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK} +``` + +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| PUT | Update existing {TRUNK} settings such as channel and rate limits
**The options below are only to be used when updating an existing trunk** | +| | *enabled* *[optional]* Enable [1] or Disable [0] this trunk.
NB this takes precedence over in/out below | +| | *enable_in* *[optional]* Enable [1] or Disable [0] inbound calls on this trunk (when being used via SIP registration) | +| | *enabled_out* *[optional]* Enable [1] or Disable [0] outbound calls on this trunk. | +| | *limit_concurrent\_\* *[optional]* The * above to be replaced by one of the following parameters | +| | Concurrent channel limit for the class of calls indicated as an integer value or [null] (do not impose a limit) *out out_international*, *out_international_hotspot*, *out_per_number in* | +| | *limit_rate\_\* * *[optional]* Rate limit for each of the above outbound categories in the form calls/duration (or [null] where no limit) e.g: | +| | *5/10s* 5 calls per 10 seconds *100/12h*, 100 calls in 12 hours **NB The timeframe must be one of [ 12h \| 10s \| 1s ]** | +| | *cli_format* *[optional]* For inbound calls associated with this trunk, receive the CLI in the selected format, one of [ e164 \| +164 \| uk \| us ] | +| | *cli_default* *[optional]* Default Presentation Number to be presented when no valid CLI is provided or cli_force_default set (E164 format) | +| | *cli_force_default* *[optional]* Set to [1] to force above value to be used on all calls. [0] allows customer-specified CLI | +| | *nni_default* *[optional]* Default Network Number to be used when required **must be a number on your account** in E.164 format (e.g.441632960123) | +| | *max_cpm* *[optional]* Maximum cost per minute (in your billing currency) of the B leg of the call. Using this can help ensure a customer trunk cannot make calls to expensive destinations | +| | *max_cpc* *[optional]* To be used in conjunction with the above, sets a maximum connection cost per call. | +| | *max_cost* *[optional]* Sets a maximum cost per call, i.e. when the cost of the call reaches (approximately) this amount it will be cleared | +| | *max_dur* *[optional]* Sets a maximum duration per call, when the call reaches this duration, it will be cleared. | +| | *emergency_enabled* *[optional]* Set to [1] to enable emergency calls (requires account activation) | **NB** If you update a trunk and one or more parameters are invalid, the update will succeed with the **valid parameters**, please check the output returned and ensure the trunk is configured as you expect. @@ -1343,49 +1478,65 @@ Please note that all trunk settings are updated immediately, therefore disabling ### Trunk Balances + +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/balance +``` + Each trunk can have its own balance, this allows you to manage the spend of individual customers. You can also view "inprogress" information for a trunk which will show the value of calls in progress. Where the value of calls in progress exceeds the trunk balance, calls in progress will be ended. -`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/balance` -| Method| Description| -|:--|:--|:--| -| **GET** | Get Balance for {Trunk}| -| **PUT** | Set or adjust the balance for {TRUNK}
*balance* - Sets the balance of the trunk to balance
**-or-**
*adjust* - Adjust the trunk balance by the amount shown, use negative amounts to decrement the balance.| -| **GET** | Remove the balance from trunk {TRUNK}
**NB The trunk will function as before, without it’s own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)**| + +| Method | Description | +| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Get Balance for {Trunk} | +| PUT | Set or adjust the balance for {TRUNK} | +| | *balance* Sets the balance of the trunk to balance. | +| | **-or-** | +| | *adjust* Adjust the trunk balance by the amount shown, use negative amounts to decrement the balance. | +| DELETE | Remove the balance from trunk {TRUNK} **NB The trunk will function as before, without it’s own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)** | **The trunk balance feature is provided for convenience and is not a substitute for your own billing and credit control procedures. Simwood will not be liable for any calls made on a trunk when its trunk-specific balance is depleted for any reason.** +**Examples:** -| **Set balance on trunk 920123-ACME to £200**| -|:--| -|{"balance": 200}| +| **Set balance on trunk 920123-ACME to £200** | +| :------------------------------------------- | +| {"balance": 200} | We strongly recommend that "balance" is used to set an initial balance only, and thereafter the level is maintained using the "adjust" function. -|**Adjust balance on trunk 920123-ACME by £50 (e.g. if Customer has topped up)**| -|:--| -| {"adjust": 50}| +| **Adjust balance on trunk 920123-ACME by £50 (e.g. if Customer has topped up)** | +| :------------------------------------------------------------------------------ | +| {"adjust": 50} | -|Adjust balance on trunk 920123-ACME by £20 (e.g. to deduct supplementary services)| -|:--| -| {"adjust": -20}| +| Adjust balance on trunk 920123-ACME by £20 (e.g. to deduct supplementary services) | +| :--------------------------------------------------------------------------------- | +| {"adjust": -20} | **NB Your account primary -L001 IP trunk does not support Trunk Balances.** ### Per-Trunk Realtime Call Information + +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/inprogress +``` + As with your account you can also view realtime "in progress" information on a per-trunk basis. -`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/inprogress` + + - - - - +| Method | Description | +| :----- | :----------------------------------------------------------------------------- | +| GET | Provides information on the calls currently in progress on the specified TRUNK | + + + + ```json @@ -1398,10 +1549,8 @@ Provides information on the calls currently in progress on the specified TRUN "approx_seconds_remaining": 56838, } ``` - - - -
GET -Provides information on the calls currently in progress on the specified TRUNK -
+ + Where a trunk has a balance the three additional elements will be present which have the same meaning as in your account snapshot but pertain only to the TRUNK specified; @@ -1412,37 +1561,48 @@ These are omitted where a trunk has no balance, but you can still view the curre **NB Your account primary -L001 IP trunk does not support this feature.** ### Trunk IP Functions + The following applies only to trunks using IP-Based authentication, your primary trunk ({ACCOUNT}-L001) is an example of one such trunk which does not require a SIP username and password. Please ensure you only add IP addresses that you control and DELETE any that are no longer required. Please note that that this functionality should **NOT** be used to update an account with dynamic IP addresses - such installations, where unavoidable, should use authenticated SIP trunks as described above. +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl +``` +| Method | Description | +| :----- | :---------------------------------------------------------- | +| GET | Request a list of IP address authorised on ip-based {TRUNK} | -||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl| -|:--|:--| -| **GET** |Request a list of IP address authorised on ip-based {TRUNK}| +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl/{IP} +``` -
- -||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl/{IP}| -|:--|:--| -| **PUT** |Add {IP} to ip-based {TRUNK}| -|**DELETE**|Remove {IP} from ip-based {TRUNK}| +| Method | Description | +| :----- | :-------------------------------- | +| PUT | Add {IP} to ip-based {TRUNK} | +| DELETE | Remove {IP} from ip-based {TRUNK} | ### Trunk Password Functions The following applies only to authenticated trunks (those using a username and password) or being used for SIP registration. -`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/password_reset` +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/password_reset +``` - - - - + + + +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | Request and return a new password for this trunk. | +| | NB The old password will be disabled immediately, any devices configured to use this trunk will need reconfigured to continue to make outbound calls. | + + + + ```json @@ -1453,11 +1613,8 @@ Request and return a new password for this trunk.
"pass":"e5d5aca5e39251bdc19554d3" } ``` - - - - -
POST -Request and return a new password for this trunk.
-NB The old password will be disabled immediately, any devices configured to use this trunk will need reconfigured to continue to make outbound calls. -
+ + **NB** It is not possible to specify a password for a trunk, they are automatically generated. @@ -1470,54 +1627,63 @@ Not to be confused with IP ACLs (to determine which IPs can make outbound calls The ACL is specified in a JSON-encoded object as follows; -|| -|:-| -|allow Array Allowed Prefixes e.g. [441,442,443,448]| -|deny Array Denied Prefixes e.g. [44870]| +| Variable | Description | +| :------- | :-------------------------------------------- | +| *allow* | Array Allowed Prefixes e.g. [441,442,443,448] | +| *deny* | Array Denied Prefixes e.g. [44870] | This would be encoded in JSON as follows; + ```json {"allow":[441,442,443,448],"deny":[44870]} ``` This example would allow calls to all UK Geographic, 03 Numbers and all 08 Numbers except 0870. -
-Please note
-(1) Longest prefix matching is used, so 44870 in the **deny** list will block even if 448 is allowed.
-(2) If only **allow** is specified, this is treated as a whitelist. all other destinations will be denied.
-(3) If only **deny** is specified, this is treated as a blacklist. all other destinations will be allowed.
+ +Please note: +(1) Longest prefix matching is used, so 44870 in the **deny** list will block even if 448 is allowed. +(2) If only **allow** is specified, this is treated as a whitelist. all other destinations will be denied. +(3) If only **deny** is specified, this is treated as a blacklist. all other destinations will be allowed. (4) Account-level blocks will override any trunk settings. -(e.g. a trunk cannot call a destination blocked at the account level)
+(e.g. a trunk cannot call a destination blocked at the account level). (5) Trunk level blocks will override any account-level allows. (e.g. you may deny certain trunks access to destinations that are otherwise allowed) -`/v3/voice/{ACCOUNT}/outbound/destinationacl` +``` +/v3/voice/{ACCOUNT}/outbound/destinationacl +``` -`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/destinationacl` +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/destinationacl +``` -| Method| Description| -|:-|:-| -|**GET**|Retrieve active ACL on your account or trunk as specified| -|**PUT**|Replace active ACL with the JSON object PUT.
**The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’**| -|**DELETE**|Remove the ACL associated with the account or trunk
**Please note that the default is to allow access to ALL destinations without restriction - please ensure this is what you want.**| +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | Retrieve active ACL on your account or trunk as specified | +| PUT | Replace active ACL with the JSON object PUT. **The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’** | +| DELETE | Remove the ACL associated with the account or trunk **Please note that the default is to allow access to ALL destinations without restriction - please ensure this is what you want.** | -Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE;
- **X-Reason: 447700900123 matches trunk do not route 447**
- **X-Reason: 449098790000 matches customer do not route 449**
+Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE; + **X-Reason: 447700900123 matches trunk do not route 447** + **X-Reason: 449098790000 matches customer do not route 449** -Either one of these may have (cached) appended where the number has been blocked more than once in the last 60s, in such case the prefix may not be shown.
+Either one of these may have (cached) appended where the number has been blocked more than once in the last 60s, in such case the prefix may not be shown. **NB** The above ‘destination acl’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account. ### Trunk Routing Configuration It is now possible to set a trunk-level routing configuration which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls for a group of numbers to one destination, and another group of numbers to a different destination. -||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config| -|:-|:-| -|**GET**|Return configuration for {TRUNK}| -|**PUT**|Replace active configuration with the JSON object PUT.| -|**DELETE**|Remove configuration for {TRUNK}| +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config +``` + +| Method | Description | +| :----- | :----------------------------------------------------- | +| GET | Return configuration for {TRUNK} | +| PUT | Replace active configuration with the JSON object PUT. | +| DELETE | Remove configuration for {TRUNK} | For full syntax and available options please refer to [Number Routing Configuration](#number-routing-configuration) below. @@ -1526,11 +1692,31 @@ As detailed below, inbound numbers can be associated with a trunk either for bil **NB** If a number has its own specific routing configuration, then any trunk association defined in the ‘options’ block will continue to take priority. -||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/numbers| -|:-|:-| -|**GET**|Return the currently associated numbers
{ "success": true, "data": [ "443301223000", "443301223001", "443301223002", ... ] }| -|**PUT**|Associate more numbers to the trunk, passing the numbers you wish to append as an array, per the example below
{ "data": [ "443301223003", "443301223004", "443301223005", ... ] }| -| **POST** | Replace the list of associated numbers entirely, passing the numbers you wish to replace it with as an array. Passing an empty array will remove any direct associations with this trunk.
**NB** All existing associations with this trunk will be removed!
{ “data”: [ “443301223100”, “443301223101”, “443301223102”, ... ]} | +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/numbers +``` + + + + +| Method | Description | +| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Return the currently associated numbers. | +| PUT | Associate more numbers to the trunk, passing the numbers you wish to append as an array, per the example below. | +| | { "data": [ "443301223003", "443301223004", "443301223005", ... ] } | +| POST | Replace the list of associated numbers entirely, passing the numbers you wish to replace it with as an array. Passing an empty array will remove any direct associations with this trunk. **NB** All existing associations with this trunk will be removed! | +| | { “data”: [ “443301223100”, “443301223101”, “443301223102”, ... ]} | + + + +```json + +{ + "success": true, "data": [ "443301223000", "443301223001", "443301223002" ] + } +``` + + When associating numbers to a trunk, any individual routing configuration currently set on those numbers will @@ -1557,15 +1743,25 @@ You can access your outbound SIP rates from any* standard BT landline using our Access is restricted to authorised CLIs. IDA users are managed much like trunks (see above), each number added automatically creates a ‘trunk’ in the form {ACCOUNT}-IDA01xxxxxxxxx, you will see these identifiers as the trunk in your CDRs and the same settings can be applied as to trunks (see above) -||/v3/voice/{ACCOUNT}/ida| -|:-|:-| -|**GET**|Retrieve active IDAs on your account| -||/v3/voice/{ACCOUNT}/ida/{CLI}| -|:-|:-| -|**GET**|Retrieve the details associated with this IDA User| -|**PUT**|Create a new IDA user with the specified {CLI}
**or (if additional parameters are supplied)**
update an existing IDA user (see above "Trunk Management" for an example of what parameters are available)| -|**DELETE**|Delete the IDA user with the specified {CLI}| +``` +/v3/voice/{ACCOUNT}/ida +``` +| Method | Description | +| :----- | :----------------------------------- | +| GET | Retrieve active IDAs on your account | + +``` +/v3/voice/{ACCOUNT}/ida/{CLI} +``` + +| Method | Description | +| :----- | :--------------------------------------------------------------------------------------------------------- | +| GET | Retrieve active IDAs on your account | +| PUT | Create a new IDA user with the specified {CLI} **or (if additional parameters are supplied)** | +| | update an existing IDA user (see above "Trunk Management" for an example of what parameters are available) | +| DELETE | Delete the IDA user with the specified {CLI} | + Users making calls using the IDA service should dial the full number prefixed with 12940 e.g. to call 029 2120 2120 you would dial **1294002921202120** @@ -1573,7 +1769,7 @@ Users making calls using the IDA service should dial the full number prefixed wi 2. If another Simwood customer has enabled a CLI for the IDA service you will not be able to associate the same CLI with your own account. -\* Some landlines may not permit IDA calls +*Some landlines may not permit IDA calls* **IDA for Virtual Interconnect ("Hosted IDA")** Virtual Interconnect - Inbound customers using their own IDA codes should not use the above functionality. Please contact us for more information on IDA for Virtual Interconnect. @@ -1582,18 +1778,20 @@ Virtual Interconnect - Inbound customers using their own IDA codes should not us ### Number Allocation #### UK Number Ranges -`/v3/numbers/{ACCOUNT}/ranges` - +``` +/v3/numbers/{ACCOUNT}/ranges +``` - - - - +| Method | Description | +| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | Retrieves a list of all available UK number ranges, including descriptions. This is intended for customers to populate, for example, a drop down to allow customers to select an area | +| | NB: This does not return international numbering at this time. | + + ```json @@ -1618,64 +1816,67 @@ etrieves a list of all available UK number ranges, including descriptions. This ] } ``` - - - - - -
GET -etrieves a list of all available UK number ranges, including descriptions. This is intended for customers to populate, for example, a drop down to allow customers to select an area
-NB This does not return international numbering at this time. + + -
+ + #### Available Numbers -||/v3/numbers/{ACCOUNT}/available/[all\|gold\|standard]/[1\|10\|100]| -|:-|:-| -|**GET**|Returns 1,10 or 100 numbers available for allocation matching the pattern specified.
One of all, gold, or standard should be specified in the URL;
**all** returns all available numbers matching *pattern*
**gold** returns only gold numbers matching *pattern*
**standard** returns only non-gold numbers matching *pattern*| -||***pattern***
Search for numbers matching specified pattern (can use wildcards e.g \*203\*)
**NB** For backward compatibility, please note that if country_code is not set, a search for 4420\* and 20\* are identical and are assumed to be UK numbers (without the leading 0). Similarly, a search for 1212\* will be assumed to be the UK (0121 2\*), NOT the USA 1-212.| -||***country_code***
Optional country code, currently only one of [1\|44] Defaults to 44 for UK numbering, use 1 for USA numbering.| -||[{ "country_code":"44", "number":"1134032330", "recommended_gold_premium": 0, "wholesale_gold_premium" 0, "block":"03dd542cafcecf43fc06024ee6099311424c71cf", "bill_class":"Carrier", "SMS": 0 }]| +``` +/v3/numbers/{ACCOUNT}/available/[all\|gold\|standard]/[1\|10\|100] +``` +| Method | Description | +| :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Returns 1,10 or 100 numbers available for allocation matching the pattern specified.One of all, gold, or standard should be specified in the URL;*all* returns all available numbers matching *pattern* **gold** returns only gold numbers matching *pattern* *standard* returns only non-gold numbers matching *pattern* | +| | *pattern* Search for numbers matching specified pattern (can use wildcards e.g \*203\*) **NB** For backward compatibility, please note that if country_code is not set, a search for 4420\* and 20\* are identical and are assumed to be UK numbers (without the leading 0). Similarly, a search for 1212\* will be assumed to be the UK (0121 2\*), NOT the USA 1-212. | +| | *country_code* [Optional] country code, currently only one of [1\|44] Defaults to 44 for UK numbering, use 1 for USA numbering. | -
+``` +/v3/numbers/{ACCOUNT}/available/consecutive/[10\20\30\40\50\60\..100] +``` -||/v3/numbers/{ACCOUNT}/available/consecutive/[10\|20\|30\|40\|50\|60\|..100]| -|:-|:-| -|**POST**|Request a report of 10,20,30,40,50,60,70,80,90 or 100 consecutive numbers available for allocation matching the pattern specified.
**NB** This function currently does not support country_code or non UK searches| +| Method | Description | +| :----- | :----------------------------------------------------- | +|POST|Request a report of 10,20,30,40,50,60,70,80,90 or 100 consecutive numbers available for allocation matching the pattern specified.*NB* This function currently does not support country_code or non UK searches| ||*pattern* Search for numbers matching specified pattern (can use wildcards e.g *203*)| -Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported.
+Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported. **NB** Some number types, e.g. OTT Mobile Numbers are only available as gold numbers at this time. #### Allocated Numbering -|||/v3/numbers/{ACCOUNT}/allocated/all| -|:-|:-|:-| -|**POST**||Request a report of all current allocated numbers on account.| -||*pattern*|Optionally specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*)| -||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)
**NB Keys are case-insensitive, wildcards not supported.**| -||*filter_config*|Only return numbers that have their own individual routing configuration.| - - -
-|||/v3/numbers/{ACCOUNT}/allocated/[10\|100\|1000\|10000]| -|:-|:-|:-| -|**POST**||Request a report of the first [ 10 \| 100 \| 1,000 \| 10,000 ] numbers that match the optional pattern.| +| Method | Description | +| :----- | :----------------------------------------------------- | +| POST| Request a report of all current allocated numbers on account.| ||*pattern*|Optionally specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*)| -||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)
**NB Keys are case-insensitive, wildcards not supported.**| +||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)**NB Keys are case-insensitive, wildcards not supported.**| ||*filter_config*|Only return numbers that have their own individual routing configuration.| +``` +/v3/numbers/{ACCOUNT}/allocated/[10\|100\|1000\|10000] +``` +| Method | Description | +| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | Request a report of the first [ 10 \| 100 \| 1,000 \| 10,000 ] numbers that match the optional pattern. | +| | *pattern* [Optional] specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*) | +| | *key* [Optional] Only return those numbers that match the specified key in their metadata (see Advanced Routing below) **NB Keys are case-insensitive, wildcards not supported.** | +| | *filter_config* [Optional] Only return numbers that have their own individual routing configuration. | -Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported. +Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported. +``` +/v3/numbers/{ACCOUNT}/allocated/{NUMBER} +``` -|||/v3/numbers/{ACCOUNT}/allocated/{NUMBER}| -|:-|:-| -|**GET**|Return configuration information on allocated {NUMBER}| -|**PUT**|Allocate an available {NUMBER} to the account| -|**DELETE**|De-configure and irrevocably remove {NUMBER} from account| +| Method | Description | +| :----- | :-------------------------------------------------------- | +| GET | Return configuration information on allocated {NUMBER} | +| PUT | Allocate an available {NUMBER} to the account | +| DELETE | De-configure and irrevocably remove {NUMBER} from account | **$ Gold Number Activation Fee** Where {NUMBER} is a Gold Number an activation fee will be charged @@ -1683,14 +1884,21 @@ Please note the above options (e.g. 1|10|100) are the only options, arbitrary va #### Last Call -`/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/lastcall` - - - - +``` +/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/lastcall +``` + + + + + +| Method | Description | +| :----- | :------------------------------------------------------------------- | +| GET | Returns a JSON object describing the most recent call to this number | + + + ```json { @@ -1703,11 +1911,8 @@ Returns a JSON object describing the most recent call to this number "duration":"68" } } ``` - - - - -
GET -Returns a JSON object describing the most recent call to this number -
+ + ### Number Routing Configuration @@ -1715,10 +1920,22 @@ Introduced in May 2014, the following is the preferred way of configuring a numb When a new configuration is provided this will take precedence over any existing configuration. -`/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config` +``` +/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config +``` -**GET** Return configuration information on allocated {NUMBER} -**See Configuration Syntax (New) below** + + + +| Method | Description | +| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | Return configuration information on allocated {NUMBER} | +| PUT | Replace active configuration for {NUMBER} with the JSON object PUT. | +| | The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’ | +| DELETE | De-configure the configuration of {NUMBER} **NB** if configuration is still present on the /voice endpoint, it will be used | + + + ```json @@ -1745,31 +1962,33 @@ When a new configuration is provided this will take precedence over any existing } } ``` - - - -| Method| Description| -|:-|-| -|**PUT**|Replace active configuration for {NUMBER} with the JSON object PUT.
**The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’**
{"success": true}
If any error(s) occurred whilst validating the configuration these will be shown;
{ "success": false, "errors": [ "Message #1", "Message #2" ] }| -|**DELETE**|De-configure the configuration of {NUMBER}
**NB** if configuration is still present on the /voice endpoint, it will be used| + + Similarly, it is now possible to set a [trunk-level configuration](#trunk-routing-configuration) which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls to a group of numbers to a single destination, and another group of numbers to a different destination. -||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config| -|:-|:-| -|**GET**|Return configuration for {TRUNK}| -|**PUT**|Replace active configuration with the JSON object PUT.| -|**DELETE**|Remove configuration for {TRUNK}| +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config +``` + +| Method | Description | +| :----- | :----------------------------------------------------- | +| GET | Return configuration for {TRUNK} | +| PUT | Replace active configuration with the JSON object PUT. | +| DELETE | Remove configuration for {TRUNK} | -
Lastly, the default configuration will be used for all numbers on your account where no other configuration exists - this is ideal for customers who send all calls to a SIP URI and handle onward routing themselves +``` +/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config +``` + +| Method | Description | +| :----- | :------------------------------------------------------------- | +| GET | Return configuration for {ACCOUNT} | +| PUT | Replace active default configuration with the JSON object PUT. | +| DELETE | Remove default configuration | -||/v3/numbers/{ACCOUNT}/default/config| -|:-|:-| -|**GET**|Return default number configuration for {ACCOUNT}| -|**PUT**|Replace active default configuration with the JSON object PUT| -|**DELETE**|Remove default configuration| #### Number Configuration Syntax - Advanced **NB** The syntax described in this section applies equally to number, trunk, and default configuration @@ -1780,9 +1999,7 @@ Numbers are configured using a JSON object which is described below, offering in An example (annotated) configuration is below, and the full list of options can be found overleaf. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+ ```json "rules": { @@ -1795,13 +2012,9 @@ An example (annotated) configuration is below, and the full list of options can }, ``` -Rules define times of day that routing blocks (below) apply, outwith the rules given - - or if the rules section is omitted entirely - the default routing block will be used.
+Rules define times of day that routing blocks (below) apply, outwith the rules given - or if the rules section is omitted entirely - the default routing block will be used. + ```json "routing": { @@ -1816,14 +2029,9 @@ An example (annotated) configuration is below, and the full list of options can } ], ``` -This block will run during the officehours time block defined above (Mon-Fri 9am-5pm) -and will call the SIP endpoint shown and the user on the registration proxy simultaneously. -
+This block will run during the *officehours* time block defined above (Mon-Fri 9am-5pm) +and will call the SIP endpoint shown and the user on the registration proxy simultaneously. ```json [ @@ -1843,12 +2051,7 @@ and will call the SIP endpoint shown and the user on the registration proxy simu ] ], ``` -After the timeout above (30s) we will try the PSTN number provided
+After the timeout above (30s) we will try the PSTN number provided ```json "default": [ @@ -1863,14 +2066,8 @@ and will call the SIP endpoint shown and the user on the registration proxy simu ] }, ``` -The default routing block will be used outwith the office hours specified above. +The *default* routing block will be used outwith the office hours specified above. So calls outside of normal office hours will be forwarded directly to the PSTN number shown. -
```json "options": { @@ -1882,21 +2079,14 @@ So calls outside of normal office hours will be forwarded directly to the PSTN n }, ``` -Per number configuration options (detailed above) apply to the number at all times
+Per number configuration options (detailed above) apply to the number at all times ```json +{ "meta": [] } ``` -The meta block contains arbitrary metadata that you want to associate with the number
+The *meta* block contains arbitrary metadata that you want to associate with the number. #### Number Configuration Syntax @@ -1905,12 +2095,12 @@ So calls outside of normal office hours will be forwarded directly to the PSTN n The following options can be set on a per-number basis, they apply to the entire configuration at all times -|Option||Description|| +|Option|Parameters|Description|Default| |:-|:-|:-|-| |*enabled*|[true\|false]|Allows number to be disabled [false] without removing the configuration.|Default [true]| |*block_payphone* | [true\|false] | Prevents inbound calls originating from payphones |Default [false]| |*acr*|[true\|false]|Apply ACR to this number. ACR Prevents calls originating from Withheld numbers reaching this number. Withheld callers will be diverted to a recorded announcement.|Default [false]| -|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block.

You can also configure this using the endpoint /v3/numbers/[ACCOUNT]/allocated/ {NUMBER]/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| +|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block.

You can also configure this using the endpoint /v3/numbers/{ACCOUNT}/allocated/ {NUMBER}/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| #### **$.. Chargeable Options** @@ -1921,7 +2111,7 @@ Please see https://simwood.com/rates for full information The ‘rules’ parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters; -|Parameter||description| +|Parameter|Format|Description| |:-|:-|:-| |*dow*|Array of values [1..7]|The days of week this rule is active (according to ISO 8601) e.g. **1 = Monday, 7 = Sunday.**
**NB if one day must still be an array. e.g. [3] not 3**| |*time*|Array [start,end]|Array of two values, denoting the start and end time this rule applies in 24h format (e.g. [0900,1700] would represent 9am - 5pm. The leading 0 can be omitted)| @@ -1931,36 +2121,12 @@ The ‘rules’ parameter in the JSON object should be an array of named objects **Example** - - - - +|Office Hours|Mon - Fri 0900-1700 | ```json
"rules":
"officehours": [
{
"dow": [1,2,3,4,5],
"time": [900,1700]
} ]
}
``` +| Weekends | +Sat/Sun (All Day) | - - - - - - - - - - - - - - - - - - -
Office Hours -Mon - Fri
0900-1700 -		 - -```bash -"rules": { - "officehours": [ - { - "dow": [1,2,3,4,5], - "time": [900,1700] -} ] -} -``` -
Weekends -Sat/Sun
(All Day) -		 - -```bash +```json +{ "rules": { "weekend": [ { @@ -1968,19 +2134,12 @@ Sat/Sun
(All Day) } ] } ``` -
Christmas / New Year -
Dec 25th -
December 26th -
January 1st -
January 2nd -		 - +| Christmas / New Year | +Dec 25th +December 26th +January 1st +January 2nd +| ```bash "rules": { "christmasholiday": [ @@ -1992,13 +2151,7 @@ Sat/Sun
(All Day) "day": [1,2] } ] } -``` -
+```| #### "routing" From 6116400d49770d50f59433b312e1eec4e7a89e6b Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Wed, 31 May 2023 15:57:59 +0100 Subject: [PATCH 02/15] Fixed build error --- docs/wholesale.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wholesale.md b/docs/wholesale.md index 510afbd..8a1fbd7 100644 --- a/docs/wholesale.md +++ b/docs/wholesale.md @@ -5,6 +5,6 @@ title: Wholesale ## Customer API documentation -- [v3.19.1
](https://cdn.simwood.com/docs/simwood_apiv3.pdf) (PDF) +- [v3.19.1](https://cdn.simwood.com/docs/simwood_apiv3.pdf) (PDF) Note Please click on the [Carrier Services](/docs/wholesale/introduction) to see the rest of the sidebar menu \ No newline at end of file From d6e7c0379e72e778df0f3caedbe22187e6a16f26 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Wed, 31 May 2023 15:58:21 +0100 Subject: [PATCH 03/15] Fixed build error --- docs/wholesale/api/v3.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 01ccea6..6ae0300 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -809,7 +809,7 @@ Effective: 2023-03-10 | Method | Description | | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | Request daily CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| POST | Request daily CDR report date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | ``` /v3/accounts/{ACCOUNT}/reports/voice/cdr/latest/[10|100|1000|10000] @@ -848,15 +848,15 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon /v3/accounts/{ACCOUNT}/summary/([in|out])/{KEY} ``` -Tabs> + | Method | Description | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET / POST | Request an inbound or outbound summary report by {KEY} (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | -| | *date_start* Optionally specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | -| | *limit* Optionally specify limit of results to return, default 9999 | -| | *sort* Key to sort by | -| | *filter* Array of "search_key" => "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST" | +| | *date_start* [Optional] specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | +| | *limit* [Optional] specify limit of results to return, default 9999 | +| | *sort* [Optional] Key to sort by | +| | *filter* Array of "search_key" to "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST"| From ee7580e399ad772207b1043fd40aca05b0b80c99 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Wed, 31 May 2023 16:01:35 +0100 Subject: [PATCH 04/15] Syntax adjustment --- docs/wholesale/api/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 6ae0300..ff78ae8 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -856,7 +856,7 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon | | *date_start* [Optional] specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | | | *limit* [Optional] specify limit of results to return, default 9999 | | | *sort* [Optional] Key to sort by | -| | *filter* Array of "search_key" to "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST"| +| | *filter* Array of "search_key" to "value" | From decda47665b060e1245429fc3dc44bd7e81681dc Mon Sep 17 00:00:00 2001 From: Fred Date: Thu, 8 Jun 2023 13:40:36 +0300 Subject: [PATCH 05/15] added new updates for hosted pbx docs --- docs/direct/api/v1.md | 2643 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 2354 insertions(+), 289 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index ade69f5..c44d8f1 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -254,7 +254,7 @@ All dates and times are formatted according to the ISO 8601 profile. For example | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | +| HTTP Method(s) | [GET](#get) , [POST](#post) | | JSON Representation(s) | customer | | Additional Formats | None | @@ -264,35 +264,42 @@ The customers resource is the starting point for most account-level operations. { "type": "customer", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "company": "Bloggs co", - "firstName": "Fred", - "lastName": "Bloggs", - "telephone": "07557000000", - "email": "contact@fredbloggs.com", - "address1": "60 Cleveland St", - "address2": "Fitzrovia", - "city": "London", - "postcode": "W1T 4JZ", - "country": "GB", - "properties": { - "testid" : "abc123", - "test2" : "GB134324" - }, + "id": "5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5", + "created": "2010-12-21T08:30:31Z", + "accountType": "BUSINESS", + "company": "Sipcentric Ltd.", + "firstName": "Charles", + "lastName": "Chance", + "telephone": "18002274500", + "email": "support@sipcentric.com", + "address1": "The Oaks", + "address2": "Ribbesford", + "city": "Bewdley", + "postcode": "98048", + "country": "US", + "properties": {}, + "enabled": true, + "currency": "GBP", "links": { - "callBundles" : "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids" - } + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/5/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/5/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/5/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/5/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/5/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/5/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/5/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/5/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/5/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/5/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" + }, + "partnerId": "1", + "partnerCompany": "Nimvelo", + "userEmailUpdatable": false } ``` @@ -300,6 +307,7 @@ The customers resource is the starting point for most account-level operations. | :----------------------------- | :--------------------------------------------------------------------------------------------- | | **Property** | **Description** | | type
*required* | The resource type ("customer").
*String* | +| id
*required* | The unique id ("5").
*String* | | uri
*read-only* | URI of this instance.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | accountType
*read-only* | The account types are:
Business (**business**) - full hosted PBX with all the usual business features (call queues, IVRs etc)
Residential Plus (**residential**) - a cut down version aimed at home users, but still having the concept of extensions and ring groups to enable everyone in the home to have their own extension/number and use the mobile app etc.
Residential (**wlr**) - a basic PSTN replacement service, having just a phone number and voicemail. No concept of extensions or mobile apps.| @@ -314,7 +322,11 @@ The customers resource is the starting point for most account-level operations. | postcode
*required* | Primary location postcode.
*String* | | country
*required* | Primary location country.
*String* | | properties[]
*optional* | A collection of customisable properties that could be used to store varying ids
*Array* | +| enabled
*required* | enabled or not.
*Boolean* | | links[]
*read-only* | A collection of links to related sub-resources.
*Array* | +| partnerId
*required* | partner id ("1")
*string* | +| partnerCompany
*required* | The Partner Company
*string* | +| userEmailUpdatable
*required* | Can the users receive Email updates
*Boolean* | #### List customers @@ -338,21 +350,46 @@ HTTP/1.1 200 OK "pageSize": 1, "page": 1, "items": [ - { - "type": "customer", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "company": "Bloggs co", - "firstName": "Fred", - "lastName": "Bloggs", - "telephone": "07557000000", - "email": "contact@fredbloggs.com", - "address1": "60 Cleveland St", - "address2": "Fitzrovia", - "city": "London", - "postcode": "W1T 4JZ" - } - ] + { + "type": "customer", + "id": "5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5", + "created": "2010-12-21T08:30:31Z", + "accountType": "BUSINESS", + "company": "Sipcentric Ltd.", + "firstName": "Charles", + "lastName": "Chance", + "telephone": "18002274500", + "email": "support@sipcentric.com", + "address1": "The Oaks", + "address2": "Ribbesford", + "city": "Bewdley", + "postcode": "98048", + "country": "US", + "properties": {}, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/5/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/5/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/5/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/5/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/5/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/5/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/5/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/5/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/5/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/5/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" + }, + "partnerId": "1", + "partnerCompany": "Nimvelo", + "userEmailUpdatable": false + } +] } ``` @@ -374,32 +411,118 @@ GET https://pbx.sipcentric.com/api/v1/customers/me HTTP/1.1 200 OK { - "type": "customer", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "company": "Bloggs co", - "firstName": "Fred", - "lastName": "Bloggs", - "telephone": "07557000000", - "email": "contact@fredbloggs.com", - "address1": "60 Cleveland St", - "address2": "Fitzrovia", - "city": "London", - "postcode": "W1T 4JZ", - "links": { - "callBundles" : "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids" - } + "type": "customer", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-01-24T13:00:35Z", + "accountType": "BUSINESS", + "company": "Fred Test", + "firstName": "Fred", + "lastName": "Muteesa", + "email": "test@simwood.com", + "country": "GB", + "properties": {}, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + }, + "partnerId": "41", + "partnerCompany": "Ops Team Test", + "userEmailUpdatable": false +} +``` + +#### Create a Customer + +`POST /customers/{customerId}/customers/` + +To create a new customer, a representation of a `customer` must be POSTed to the `customers` resource. The newly created `Customer` ID will then be included in the body of the response. + +Example request: + +``` +POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook + +{ +"type": "customer", +"telephone":"03301229999", +"accountType": "BUSINESS", +"company": "Simwood", +"firstName": "Fred", +"lastName": "TEST API", +"email": "test@test.com", +"address1": "Simwood House", +"address2": "Cube m4 Business Park", +"city": "Bristol", +"postcode": "BS16 1FX", +"country": "GB", +"properties": { +"customid" : "abc123" +}, +"enabled": true, +"currency": "GBP", +"userEmailUpdatable": false +} +``` + +```response +HTTP/1.1 201 Created + + +{ + "type": "customer", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Simwood", + "firstName": "Fred", + "lastName": "TEST API", + "telephone": "03301229999", + "email": "test@test.com", + "address1": "Simwood House", + "address2": "Cube m4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": { + "customid": "abc123" + }, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + }, + "userEmailUpdatable": false } + ``` @@ -418,25 +541,33 @@ HTTP/1.1 200 OK The phonebook sub-resource allows users to read and organize an account's shared phone book entries. Each entry is represented by a `phonebookentry`. ```exampleRepresentation -{ - "type" : "phonebookentry", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773", - "created" : "2014-03-10T13:38:00.000+0000", - "name" : "Sipcentric", - "phoneNumber" : "01212854400", - "speedDial" : 5 -} + { + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@test.com", + "speedDial": 123, + "priority": 0 + } ``` | Type: *phonebookentry* | | |:------------------------------|:-------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("phonebookentry").
*String* | +| id
*required* | The resource id
*string* | | uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of parent of this instance
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | name
*required* | Full name of the contact.
*String* | | phoneNumber
*required* | Phone number of the contact.
*String* | +| email
*optional* | Email of the contact
*String* | | speedDial
*optional* | Assigned speed-dial for this contact (1-9999).
*Integer* | +| priority
*required* | priority of this contact. -50 for low, 0 for normal, 50 for high
*String* | #### List phone book entries @@ -455,26 +586,34 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=1 HTTP/1.1 200 OK { - "totalItems" : 18, - "pageSize" : 2, - "page" : 1, - "items" : [ - { - "type" : "phonebookentry", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716", - "created" : "2014-03-10T13:37:00.000+0000", - "name" : "Fred Mobile", - "phoneNumber" : "07902000000", - "speedDial" : 3 - }, { - "type" : "phonebookentry", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773", - "created" : "2014-03-10T13:38:00.000+0000", - "name" : "Sipcentric", - "phoneNumber" : "01212854400" - } - ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" + "totalItems": 5, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@test.com", + "speedDial": 123, + "priority": -50 + }, + { + "type": "phonebookentry", + "id": "84039", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-04T09:13:08Z", + "name": "Fred test 3", + "phoneNumber": "256761303030", + "priority": 0 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" } ``` @@ -496,11 +635,16 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773 HTTP/1.1 200 OK { - "type" : "phonebookentry", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773", - "created" : "2014-03-10T13:38:00.000+0000", - "name" : "Sipcentric", - "phoneNumber" : "01212854400" + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@test.com", + "speedDial": 123, + "priority": -50 } ``` @@ -521,7 +665,7 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook "type" : "phonebookentry", "name" : "Fred Mobile", "phoneNumber" : "07902000000", - "speedDial" : 4 + "priority" : 0 } ``` @@ -529,12 +673,14 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook HTTP/1.1 201 Created { - "type": "phonebookentry", - "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716", - "created" : "2014-03-10T13:38:00.000+0000", - "name": "Fred Mobile", - "phoneNumber": "07902000000", - "speedDial": 4 + "type": "phonebookentry", + "id": "84072", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84072", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:30:15Z", + "name": "Fred Mobile", + "phoneNumber": "07902000000", + "priority": 0 } ``` @@ -603,32 +749,37 @@ The SMS sub-resource contains a record of every SMS message sent or received on ``` { - "type" : "smsmessage", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", - "created" : "2014-03-10T13:37:00.0000+0000", - "direction" : "OUT", - "from" : "01212854400", - "to" : "07902000000", - "body" : "Hey, this API is awesome!", - "sendStatus" : "SENT", - "deliveryStatus" : 1, - "cost" : 0.1 + "type": "smsmessage", + "id": "31408968", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hello M. confirm receipt of this sms", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 } ``` | Type: *smsmessage* | | |:----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Property** | **Description** | -| type
*required* | The resource type ("smsmessage").
*String* | -| uri
*read-only* | URI of this instance.
*String* | -| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | -| direction
*read-only* | Direction of the message.
*Enum: IN, OUT* | -| from
*required* | Name or phone number of the sender.
*String* | -| to
*required* | Phone number of the recipient.
*String* | -| body
*required* | The message body.
*String* | -| sendStatus
*read-only* | The send status of an outgoing message.
*Enum: PENDING, SENT, FAILED* | +| type
*required* | The resource type ("smsmessage").
String* | +| id
*required* | The of the resource type ("31408968").
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | +| direction
*read-only* | Direction of the message.
*Enum: IN, OUT* | +| from
*required* | Name or phone number of the sender.
| +| to
*required* | Phone number of the recipient.
*String* | +| body
*required* | The message body.
*String* | +| sendStatus
*read-only* | The send status of an outgoing message.
*Enum: PENDING, SENT, FAILED* | | deliveryStatus
*read-only* | The delivery status of an outgoing message (where available):
1 = Delivered to handset
2 = Rejected from handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMS carrier
16 = Rejected by SMS carrier
*Integer* | -| cost
*read-only* | Message cost in GBP.
*Float* | +| cost
*read-only* | Message cost in GBP.
*Float* | +| creditdUsed
*required* | Number of credits used.
*String* | #### List SMS messages @@ -642,34 +793,43 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1 ```response HTTP/1.1 200 OK - { - "totalItems": 188, - "pageSize": 2, - "page": 1, - "items": [ - { - "type": "smsmessage", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253369", - "created" : "2014-03-10T13:38:00.000+0000", - "direction": "IN", - "from": "07902000000", - "to": "01212854400", - "body": "I know, it's great!", - "cost": 0.0 - }, { - "type": "smsmessage", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", - "created" : "2014-03-10T13:37:00.000+0000", - "direction": "OUT", - "from": "01212854400", - "to": "07902000000", - "body": "Hey, this API is awesome!", - "sendStatus": "SENT", - "deliveryStatus": 1, - "cost": 0.1 - } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=2" + "totalItems": 3, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "smsmessage", + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:48:45Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hey, this API is awesome!", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 + }, + { + "type": "smsmessage", + "id": "31414338", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414338", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:45:07Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "second check on you", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" } ``` @@ -687,16 +847,19 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 HTTP/1.1 200 OK { - "type" : "smsmessage", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", - "created" : "2014-03-10T13:37:00.0000+0000", - "direction" : "OUT", - "from" : "01212854400", - "to" : "07902000000", - "body" : "Hey, this API is awesome!", - "sendStatus" : "SENT", - "deliveryStatus" : 1, - "cost" : 0.1 + "type": "smsmessage", + "id": "31408968", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hello M. confirm receipt of this sms", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 } ``` @@ -704,7 +867,9 @@ HTTP/1.1 200 OK `POST /customers/{customerId}/sms` -To send a new SMS, simply POST a representation of a new `smsmessage` to the list resource. If successful, a representation of the newly created `smsmessage` will be returned in the body of the response. +To send a new SMS, simply POST a representation of a new `smsmessage` to the list resource. If successful, a representation of the newly created `smsmessage` will be returned in the body of the response. + +**NB** the From number has to be a number configured in your account. ``` POST https://pbx.sipcentric.com/api/v1/customers/25/sms @@ -721,14 +886,17 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/sms HTTP/1.1 201 Created { - "type": "smsmessage", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", - "direction": "OUT", - "from": "01212854400", - "to": "07902000000", - "body": "Hey, this API is awesome!", - "sendStatus": "SENT", - "cost": 0.1 + "type": "smsmessage", + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "direction": "OUT", + "from": "07902000000", + "to": "01212854400", + "body": "Hey, this API is awesome!", + "sendStatus": "SENT", + "cost": 0.080, + "creditsUsed": 1 } ``` @@ -754,42 +922,52 @@ The scope of a call can be: ``` -{ - "type": "call", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592317", - "created" : "2014-03-10T13:37:00.000+0000", - "scope": "EXTERNAL", - "direction": "IN", - "from": "07557000000", - "to": "Sales Group <500>", - "callStarted": "2014-03-10T13:37:00.000+0000", - "outcome": "NO_ANSWER", - "duration": 0, - "cost": 0, - "callId": "ast01-1400142051.1562723", - "linkedId": "ast01-1400142051.1562723", - "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723" - } -} + { + "type": "call", + "id": "209925287", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/209925287", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-04-05T12:59:05Z", + "scope": "EXTERNAL", + "direction": "OUT", + "from": "Fred Muteesa <100>", + "to": "01912058750", + "callerId": "02031371636", + "callStarted": "2023-04-05T12:58:55Z", + "outcome": "ANSWERED", + "duration": 7, + "cost": 0.010, + "callId": "366e05e5-1680699535.1182575", + "linkedId": "366e05e5-1680699535.1182575", + "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", + "final": true, + "links": { + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=366e05e5-1680699535.1182575" + }, + } ``` | Type: *call* | | |:-------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Property** | **Description** | -| type
*required* | The resource type ("call").
*String* | -| uri
*read-only* | URI of this instance.
*String* | -| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | -| scope
*read-only* | The scope of the call (see above for details).
*Enum: LOCAL, DOMAIN, EXTERNAL* | -| direction
*read-only* | Direction of the call.
*Enum: IN, OUT* | +| type
*required* | The resource type ("call").
*String* | +| id
*required* | The unique if of the resource .
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*required* | The url to the customer account .
*String* | +| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | +| scope
*read-only* | The scope of the call (see above for details).
*Enum: LOCAL, DOMAIN, EXTERNAL* | +| direction
*read-only* | Direction of the call.
*Enum: IN, OUT* | | from
*required* | The name and/or phone number of the caller.
*String* | -| to
*required* | The name and/or phone number of recipient.
*String* | -| callStarted
*read-only* | UTC time when the call started (ISO8601 format).
*String* | -| outcome
*read-only* | The final outcome of the call.
*Enum: ANSWERED, NO_ANSWER, BUSY, FAILED* | +| to
*required* | The name and/or phone number of recipient.
*String* | +| callerId
*required* | The number presented as the caller ID
*String* | +| callStarted
*read-only* | UTC time when the call started (ISO8601 format).
*String* | +| outcome
*read-only* | The final outcome of the call.
*Enum: ANSWERED, NO_ANSWER, BUSY, FAILED* | | duration
*read-only* | The duration of the call in seconds.
*Integer* | | cost
*read-only* | The cost of the call in GBP.
*Float* | | callId
*read-only* | A unique ID for this call or call leg.
*String* | | linkedId
*read-only* | This ID is the same across all legs of an end-to-end call and can be used to group those multiple parts together. In an end-to-end call with multiple hops, the value of "linkedId" will always be equal to the "callId" of the first call in the chain.
*String* | +| srcEndpoint
*required* | the end point that originated the call
*String* | +| final
*required* | True or False
*Boolean* | | links[]
*read-only* | A collection of links to related sub-resources.
*Array* | #### Get call history @@ -825,7 +1003,9 @@ HTTP/1.1 200 OK "items": [ { "type": "call", + "id": "7592432", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592432", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:47:05.000+0000", "scope": "EXTERNAL", "direction": "IN", @@ -842,7 +1022,9 @@ HTTP/1.1 200 OK } }, { "type": "call", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592134", + "id": "7592434", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592434", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "scope": "EXTERNAL", "direction": "OUT", @@ -962,6 +1144,7 @@ The properties of each sound type are listed below. |:---------------------------|:-------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("prompt").
*String* | +| id
*required* | The unique resource id ("prompt").
*String* | | uri
*read-only* | URI of this instance.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | name
*read-only* | Name of the prompt.
*String* | @@ -1003,13 +1186,17 @@ HTTP/1.1 200 OK "page" : 1, "items" : [ { "type" : "prompt", + "id": "1046", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:38:00.0000+0000", "name" : "thank-you-for-calling", "size" : 129612 }, { "type" : "prompt", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/sounds/1035", + "id": "1035", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.0000+0000", "name" : "calls-may-be-recorded", "size" : 69426 @@ -1035,6 +1222,7 @@ HTTP/1.1 200 OK { "type" : "prompt", + "id": "1035", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", "created" : "2014-03-10T13:37:00.0000+0000", "name" : "calls-may-be-recorded", @@ -1066,7 +1254,9 @@ The recordings sub-resource provides a way to retrieve and manage the call recor ```exampleRepresentation { "type": "recording", + "id": "1358371", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "direction": "IN", "partyId": "106", @@ -1124,7 +1314,9 @@ HTTP/1.1 200 OK "items" : [ { "type" : "recording", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372", + "id": "1358372", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T14:09:00.0000+0000", "direction" : "OUT", "partyId" : "07557000000", @@ -1135,7 +1327,9 @@ HTTP/1.1 200 OK "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928" }, { "type" : "recording", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", + "id": "1358371", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:42:00.0000+0000", "direction" : "IN", "partyId" : "07557000000", @@ -1166,7 +1360,9 @@ HTTP/1.1 200 OK { "type": "recording", + "id": "1358371", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:42:00.0000+0000", "direction" : "IN", "partyId" : "07557000000", @@ -1202,7 +1398,9 @@ A time interval (`timeinterval`) defines the single or set of time periods which ```exampleRepresentation { "type": "timeinterval", + "id": "431", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", @@ -1234,7 +1432,9 @@ A time interval (`timeinterval`) defines the single or set of time periods which |:-----------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("timeinterval").
*String* | -| uri
*read-only* | URI of this instance.
*String* | +| id
*required* | request of this instance.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | name
*required* | Name assigned to the time interval.
*String* | | repeat
*required* | The repeat frequency.
*Enum: WEEKLY, YEARLY* | @@ -1267,7 +1467,9 @@ HTTP/1.1 200 OK "page" : 1, "items" : [ { "type" : "timeinterval", + "id": "32", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "name" : "Christmas Day", "repeat" : "YEARLY", @@ -1279,7 +1481,9 @@ HTTP/1.1 200 OK } ] }, { "type" : "timeinterval", + "id": "8675", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:27:00.000+0000", "name" : "Office Hours", "repeat" : "WEEKLY", @@ -1327,7 +1531,9 @@ HTTP/1.1 200 OK { "type": "timeinterval", + "id": "431", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", @@ -1363,7 +1569,7 @@ HTTP/1.1 200 OK | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | +| HTTP Method(s) | [GET](#get) ,[POST](#post), [PUT](#put), [DELETE](#delete) | | JSON Representation(s) | phone
virtual
group
queue
ivr
mailbox | | Additional Formats | None | @@ -1444,7 +1650,9 @@ The properties of each endpoint type are listed below. |:------------------------------|:-----------------------------------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("queue").
*String* | +| id
*required* | The resource id.
*String* | | uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | shortNumber
*required* | The 3-digit internal number of this endpoint.
*String* | | name
*required* | Name assigned to the endpoint.
*String* | @@ -1454,7 +1662,9 @@ The properties of each endpoint type are listed below. |:---------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("ivr").
*String* | -| uri
*read-only* | URI of this instance.
*String* | +| id
*required* | The resource id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | shortNumber
*required* | The 3-digit internal number of this endpoint.
*String* | | name
*required* | Name assigned to the endpoint.
*String* | @@ -1473,7 +1683,9 @@ The properties of each endpoint type are listed below. |:------------------------------|:-------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("mailbox").
*String* | -| uri
*read-only* | URI of this instance.
*String* | +| id
*required* | The resource id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | shortNumber
*required* | The 3-digit internal number of this endpoint.
*String* | | name
*required* | Name assigned to the endpoint.
*String* | @@ -1501,7 +1713,9 @@ HTTP/1.1 200 OK "items": [ { "type": "ivr", + "id": "83066", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:38:00.000+0000", "shortNumber": "001", "name": "Main IVR", @@ -1509,7 +1723,9 @@ HTTP/1.1 200 OK }, { "type": "phone", + "id": "101", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "shortNumber" : "102", "name" : "John Simmonds", @@ -1539,7 +1755,9 @@ HTTP/1.1 200 OK { "type": "phone", + "id": "101", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "shortNumber" : "102", "name" : "John Simmonds", @@ -1555,6 +1773,177 @@ HTTP/1.1 200 OK } ``` +#### List endpoints filterd by type. + +`GET /customers/{customerId}/endpoints?type={endpointType}` + +you might want to get all extensions or all ivrs that are on the account. In this case you send a GET request with a type parameter as shown below. + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone +``` + +```response + +{ + "totalItems": 2, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "phone", + "id": "83069", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-01-24T17:12:05Z", + "shortNumber": "100", + "name": "Fred Muteesa", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/49610", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/phonestatus" + } + }, + { + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-15T19:43:10Z", + "shortNumber": "102", + "name": "fred", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + } + } + ] +} + +``` + +#### Updating an endpoint. + +`PUT /customers/{customerId}/endpoints/{endpointId} ` + +Depending on what property of the end point you want to update, you will need to send a PUT request to the following resrouce. You have to know the endpointID and the endpoint type. Depending on the endpoint type you are updating, some fields are required in the body, hence if you miss difinition of one of the parameters, your request will fail. In the example below I am updating the name of the IVR, but the rest of the fields I have included must be provided for the request to work. + +Example Request: + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 + +Json body +{"type":"ivr", +"id":"83066", +"name":"fred-lab-ivr2", +"timeout":5, +"shortNumber":500 +} + +``` + +```Response +HTTP/1.1 200 OK + +{ + "type": "ivr", + "id": "83066", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-01-24T16:43:22Z", + "shortNumber": "500", + "name": "fred-lab-ivr2", + "timeout": 5, + "items": [] +} + +``` + + +#### Add an extension endpoint +To add an extention or phone type endpoint to an account, you need to send a POST request as shown below. Please not that some short numbers are reserved and can not be added as extensions. an example is **101**. the system will automatically return an error in case you try to add these numbers. + + +example request: + +``` +POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints + +Body +{"callRecording":"OFF","timeout":30,"name":"fred","shortNumber":"102","type":"phone"} + +``` + +```Response + +HTTP/1.1 200 OK + +{ + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-15T19:43:10Z", + "shortNumber": "102", + "name": "fred", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + } +} +``` + + +#### Delete Endpoint + +`DELETE /customers/{customerId}/endpoints/{endpointId}` + +To delete an endpoint all you need is the endpointId and CusomterId. +see example below: + +Example Request + +``` +DELETE https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 +``` + + + + ### Phone Numbers | Resource Information | | @@ -1563,7 +1952,7 @@ HTTP/1.1 200 OK | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | +| HTTP Method(s) | [GET](#get), [POST](#post) | | JSON Representation(s) | did | | Additional Formats | None | @@ -1572,7 +1961,9 @@ Phone numbers provide a route into the system from outside - they can support ca ```exampleRepresentation { "type" : "did", + "id": "50", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "number" : "01212854400", "identifier" : "", @@ -1599,7 +1990,9 @@ Phone numbers provide a route into the system from outside - they can support ca |:-------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("did").
*String* | -| uri
*read-only* | URI of this instance.
*String* | +| id
*required* | The resource id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | number
*read-only* | The phone number in E.164 format.
*String* | | identifier
*optional* | An optional label which is prefixed to the caller ID name on incoming calls to identify which number was called. Useful when multiple numbers each route to the same internal endpoint.
*String* | @@ -1636,7 +2029,9 @@ HTTP/1.1 200 OK "page" : 1, "items" : [ { "type" : "did", + "id": "47", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "number" : "01212854400", "identifier" : "Main", @@ -1647,7 +2042,9 @@ HTTP/1.1 200 OK "faxEnabled" : false }, { "type" : "did", + "id": "50", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "number" : "01212854411", "identifier" : "", @@ -1689,7 +2086,9 @@ HTTP/1.1 200 OK { "type" : "did", + "id": "47", "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created" : "2014-03-10T13:37:00.000+0000", "number" : "01212854400", "identifier" : "Main", @@ -1701,137 +2100,411 @@ HTTP/1.1 200 OK } ``` -### Outgoing Caller IDs +#### Add a new Phone Number -| Resource Information | | -|:-------------------------------|:------------------------------------------| -| Location | /customers/{customerId}/outgoingcallerids | -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | outgoingcallerid | -| Additional Formats | None | +`POST /customers/{customerId}/phonenumbers` -Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. +To add an availablenumber to a customer account please use a POST as per the below. +NB: This number should be available in the simwood inventory. you can check Available numbers api , to see available numbers. -```exampleRepresentation -{ - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "07932000000", - "allowCalls": false, - "allowSms": true +Example request: + +``` +POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers + + { + "createFrom":"4-44-113-4037921", + "type":"did" } ``` -| Type: *outgoingcallerid* | | -|:------------------------------|:----------------------------------------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("outgoingcallerid").
*String* | -| uri
*read-only* | URI of this instance.
*String* | -| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | -| number
*read-only* | Name or number to be displayed for outgoing calls and/or messages.
*String* | -| allowCalls
*read-only* | Whether the name/number has been approved for use with outgoing calls.
*Boolean* | -| allowSms
*read-only* | Whether the name/number has been approved for use with outgoing SMS.
*Boolean* | +```response +HTTP/1.1 200 OK + +{ + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + } +} +``` +#### Linking Phone Number to extension -#### List outgoing caller ids +`PUT /customers/{customerId}/phonenumbers/{phonenumberId}` -`GET /customers/{customerId}/outgoingcallerids` +To link a phonenumber in a customer's account to an extension inside the customer account please use a PUT as per the example below. +"id" in the body is the ID of the phone number, and "destination" is the ID of the extension we want to link to. -Lists the IDs which have been approved for use on the account. +NB: This phone number should already be added to the account. Please see , adding Phone numbers. Example request: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids +PUT https://pbx.sipcentric.com/api/v1/customers/{customerId}/phonenumbers/{phonenumberId}/ + +Body { +"type": "did", +"id": "73224", +"uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}", +"parent": "https://pbx.sipcentric.com/api/v1/customers/25", +"created": "2022-01-06T11:12:46Z", +"number": "01134031453", +"formatted": "0113 403 1453", +"smsCapable": false, +"faxEnabled": false, +"links": { +"routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}/routingrules" +}, +"destination":"89937" +} ``` ```response HTTP/1.1 200 OK { - "totalItems": 2, - "pageSize": 20, - "page": 1, - "items": [ - { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "Sipcentric", - "allowCalls": false, - "allowSms": true - }, - { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "01212854411", - "allowCalls": true, - "allowSms": true + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" } - ] } ``` -#### Get outgoing caller id +#### UN-Linking Phone Number and extension -`GET /customers/{customerId}/outgoingcallerids/{id}` -Get the instance of a specific caller ID. +`PUT /customers/{customerId}/phonenumbers/{phonenumberId}` + +To un-link or remove the link between a phonenumber and an extension, you need to send another PUT request without detination in the body. -Example request: + +Example Request ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 +PUT https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 + +Body +{ + "type":"did", + "id":"94854", + "uri":"https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent":"https://pbx.sipcentric.com/api/v1/customers/25", + "created":"2023-05-12T14:11:06.000Z", + "number":"01134037921", + "formatted":"0113 403 7921", + "smsCapable":false, + "faxEnabled":false, + "links":{ + "routingRules":"https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + } + } ``` -```response +```Response HTTP/1.1 200 OK { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "01212854411", - "allowCalls": true, - "allowSms": true + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + } } ``` -### Credit Status +#### Delete Phone Number +`DELETE /customers/{customerId}/phonenumbers/{phonenumberId}` + +To delete a number from an accouont, a DELETE request must be made to the instance resource. + + + +Example +``` +DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 + +``` + + + +### Available Numbers | Resource Information | | |:-------------------------------|:-------------------------------------| -| Location | /customers/{customerId}/creditstatus | +| Location | /customers/{customerId}/availablenumber | | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | creditstatus | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | availablenumber | | Additional Formats | None | -The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. +The Available Numbers sub-resource returns a list of available numbers that can be added to a customer account, represented by a `availablenumber` instance. After listing the available numbers you can add a number to your account see. ```exampleRepresentation { - "type": "creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "accountType": "PREPAID", - "creditRemaining": 19.571 + "type": "availablenumber", + "id": "4-44-113-4037921", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", + "country": "44", + "areaCode": "113", + "number": "4037921", + "formatted": "0113 403 7921" } ``` -| Type: *creditstatus* | | + + +| Type: *availablenumber* | | |:-------------------------------|:------------------------------------------------------| | **Property** | **Description** | -| type
*read-only* | The resource type ("creditstatus")
*String* | -| uri
*read-only* | URI of this instance.
*String* | -| accountType
*read-only* | The type of account.
*Enum: PREPAID, POSTPAID* | -| balance
*read-only* | Balance on the account
*Float* | +| type
*required* | The resource type ("availablenumber")
*String* | +| id
*read-only* | The resource availablenumber id this is the id you use to add number to your account
*String* | +| uri
*read-only* | URI to get this available number.
*String* | +| country
*read-only* | Country code for the number("44")
*date* | +| areaCode
*read-only* | Area Code for the number("113")
*string* | +| number
*read-only* | these are the last 7 digits of the number("4037921")
*string* | +| username
*read-only* | username for this user
*string* | +| formated
*read-only* |the number formatted ("0113 403 7921")
*string* | + + + +#### Get availablenumber + +`GET /availablenumbers?areaCode=113&country=44&pageSize=100` + + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/availablenumbers?areaCode=113&country=44&pageSize=100&location=GB +``` + +```response +HTTP/1.1 200 OK + +{ + "totalItems": 21, + "pageSize": 100, + "page": 1, + "items": [ + { + "type": "availablenumber", + "id": "4-44-113-4037921", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", + "country": "44", + "areaCode": "113", + "number": "4037921", + "formatted": "0113 403 7921" + }, + { + "type": "availablenumber", + "id": "4-44-113-4037924", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037924", + "country": "44", + "areaCode": "113", + "number": "4037924", + "formatted": "0113 403 7924" + }, + ...... + ] +} +``` + +#### Get an available number + +`GET /availablenumber/{availablenumberId}` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921 +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "availablenumber", + "id": "4-44-113-4037921", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", + "country": "44", + "areaCode": "113", + "number": "4037921", + "formatted": "0113 403 7921" +} +``` + + + +### Outgoing Caller IDs + +| Resource Information | | +|:-------------------------------|:------------------------------------------| +| Location | /customers/{customerId}/outgoingcallerids | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | outgoingcallerid | +| Additional Formats | None | + +Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. + +```exampleRepresentation +{ + "type": "outgoingcallerid", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created" : "2014-03-10T13:37:00.000+0000", + "number": "07932000000", + "allowCalls": false, + "allowSms": true +} +``` + +| Type: *outgoingcallerid* | | +|:------------------------------|:----------------------------------------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("outgoingcallerid").
*String* | +| id
*required* | The resource id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | +| number
*read-only* | Name or number to be displayed for outgoing calls and/or messages.
*String* | +| allowCalls
*read-only* | Whether the name/number has been approved for use with outgoing calls.
*Boolean* | +| allowSms
*read-only* | Whether the name/number has been approved for use with outgoing SMS.
*Boolean* | + + +#### List outgoing caller ids + +`GET /customers/{customerId}/outgoingcallerids` + +Lists the IDs which have been approved for use on the account. + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids +``` + +```response +HTTP/1.1 200 OK + +{ + "totalItems": 2, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "outgoingcallerid", + "id": "115", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created" : "2014-03-10T13:37:00.000+0000", + "number": "Sipcentric", + "allowCalls": false, + "allowSms": true + }, + { + "type": "outgoingcallerid", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created" : "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "allowCalls": true, + "allowSms": true + } + ] +} +``` + +#### Get outgoing caller id + +`GET /customers/{customerId}/outgoingcallerids/{id}` + +Get the instance of a specific caller ID. + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "outgoingcallerid", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created" : "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "allowCalls": true, + "allowSms": true +} +``` + +### Credit Status + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/creditstatus | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | creditstatus | +| Additional Formats | None | + +The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. + +```exampleRepresentation +{ + "type": "creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "accountType": "PREPAID", + "creditRemaining": 19.571 +} +``` + +| Type: *creditstatus* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("creditstatus")
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| accountType
*read-only* | The type of account.
*Enum: PREPAID, POSTPAID* | +| balance
*read-only* | Balance on the account
*Float* | #### Get credit status @@ -1871,7 +2544,9 @@ The call bundles sub-resource contains all bundles which have been added to an a ```exampleRepresentation { type: "customerbundle", + id: "1040" uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", + parent: "https://pbx.sipcentric.com/api/v1/customers/25", created: "2014-03-01T00:00:00.000+0000", name: "1000 Mins - UK Local/National", inclusiveMins: 1000, @@ -1889,7 +2564,9 @@ The call bundles sub-resource contains all bundles which have been added to an a |:---------------------------------|:------------------------------------------------------------------------------------------| | **Property** | **Description** | | type
*required* | The resource type ("customerbundle").
*String* | -| uri
*read-only* | URI of this instance.
*String* | +| id
*required* | The resource id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | name
*read-only* | The bundle name.
*String* | | inclusiveMins
*read-only* | The number of minutes to predefined destinations included in the bundle.
*Integer* | @@ -1923,7 +2600,9 @@ HTTP/1.1 200 OK "items": [ { type: "customerbundle", + id: "1040" uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", + parent: "https://pbx.sipcentric.com/api/v1/customers/25", created: "2014-03-01T00:00:00.000+0000", name: "1000 Mins - UK Local/National", inclusiveMins: 1000, @@ -1956,7 +2635,9 @@ HTTP/1.1 200 OK { "type": "customerbundle", + "id": "1040" "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2014-03-01T00:00:00.000+0000", "name": "1000 Mins - Local/National (Free)", "inclusiveMins": 1000, @@ -1970,6 +2651,1390 @@ HTTP/1.1 200 OK } ``` + +### Call Charging + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/callcharging | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | callcharging | +| Additional Formats | None | + +The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. + +```exampleRepresentation +{ + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + +| Type: *callcharging* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("callcharging")
*String* | +| id
*required* | The resource cutomer id.
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| chargingPlan
*read-only* | The URI to the customer's call charging plan .
*string* | +| postpaid
*read-only* | Postpaid or prepaid
*boolean* | +| creditLimit
*read-only* | Credit Limit on the account
*Float* | +| warningThreshold
*read-only* | The warning Threshold on the account
*Float* | + +#### Get callcharging plan + +`GET /customers/{customerId}/callcharging` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/callcharging +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + + +### Permissions + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/permissions | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | permissions | +| Additional Formats | None | + +The Permissions sub-resource returns the current customer permissions for an account, represented by a `permissions` instance. + +```exampleRepresentation +{ + "type": "customerpermissions", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true +} +``` + +| Type: *permissions* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("permissions")
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer permissions.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| incomingCalls
*read-only* | Can account receive calls?
*boolean* | +| outgoingCalls
*read-only* | Can the account make calls?
*boolean* | +| internationalCalls
*read-only* | can the customer make international calls?
*boolean* | +| addFeatures
*read-only* | Can the customer add features?
*boolean* | +| removeFeatures
*read-only* | Can the customer remove features?
*boolean* | +| enableRecording
*read-only* | Can the customer enable recording?
*boolean* | + +#### Get Customer Permissions + +`GET /customers/{customerId}/permissions` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/permissions +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "customerpermissions", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true +} +``` + +### billing + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/billing | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | billing | +| Additional Formats | None | + +The billing sub-resource returns the current billing configuration and pricing plan for an different features, represented by a `billing` instance. + +```exampleRepresentation +{ + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "paymentsEnabled": false, + "providersEnabled": [], + "upgradeAllowed": true, + "downgradeAllowed": true, + "paymentMethodRequired": false, + "currency": "GBP", + "frequency": "MONTHLY", + "nextBillingDate": "2023-06-01T01:00:00Z", + "featurePricing": { + "virtual": 0.00, + "mailbox": 1.00, + "ivr": 3.00, + "phone": 11.00, + "trunk": 8.50, + "did": 2.00, + "queue": 3.00, + "group": 2.00 + }, + "links": { + "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + } +} +``` + +| Type: *billing* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("billing")
*String* | +| uri
*read-only* | URI to get customer billing.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| paymentsEnabled
*read-only* | is the account being billed?
*boolean* | +| upgradeAllowed
*read-only* | Can the account upgrade
*boolean* | +| downgradeAllowed
*read-only* | can account downgrade?
*boolean* | +| paymentMethodRequired
*read-only* | is payment required for this account?
*boolean* | +| currency
*read-only* | account currency default is GBP
*string* | +| frequency
*read-only* | billing frequence (Monthly)
*string* | +| featurePricing
*read-only* | prices of the features
*string* | + +#### Get billing + +`GET /customers/{customerId}/billing` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/billing +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "paymentsEnabled": false, + "providersEnabled": [], + "upgradeAllowed": true, + "downgradeAllowed": true, + "paymentMethodRequired": false, + "currency": "GBP", + "frequency": "MONTHLY", + "nextBillingDate": "2023-06-01T01:00:00Z", + "featurePricing": { + "virtual": 0.00, + "mailbox": 1.00, + "ivr": 3.00, + "phone": 11.00, + "trunk": 8.50, + "did": 2.00, + "queue": 3.00, + "group": 2.00 + }, + "links": { + "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + } +} +``` + +### Estimates + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /estimates +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | estimates | +| Additional Formats | None | + +The Available Charging Plans resource returns a list of charging plans that can be used, represented by a `estimates` instance. +This resource is used to set customers price plans. + + + +```exampleRepresentation +{ + "type" : "invoice", + "id" : "E5", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", + "created" : "2023-05-17T15:22:38Z", + "netAmount" : 133.00, + "vatAmount" : 26.60, + "total" : 159.60, + "lines" : [ { + "description" : "Phone Extension", + "unitPrice" : 3.00, + "quantity" : 31, + "lineTotal" : 93.00, + "usage" : false + }, { + "description" : "Virtual Extension", + "unitPrice" : 0.00, + "quantity" : 11, + "lineTotal" : 0.00, + "usage" : false + }, + ...... + ], + "date" : "2023-05-17T15:22:38Z", + "credit" : false, + "currency" : "GBP" +} +``` + + + +| Type: *estimates* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("invoice")
*String* | +| id
*read-only* | The resource estimate id (E5)
*String* | +| uri
*read-only* | URI to get this estimate.
*String* | +| created
*required* | date when this estimate was created
*date* | +| netAmount
*required* | net amount
*float* | +| vatAmount
*requried* | vat charged
*float* | +| total
*read-only* | total charge
*float* | +| lines
*read-only* | array or billable resources
*float* | +| lines
*read-only* | array or billable resources
*array* | +| description
*read-only* | name of resource
*float* | +| unitPrice
*read-only* | the unit price of resrouce
*float* | +| quantity
*read-only* | number of resources
*integer* | +| lineTotal
*read-only* |
*float* | +| usage
*read-only* |whethere resource is usable or not
*boolean* | + + +#### Get estimates + +`GET /customers/{customerId}/billing/estimates/` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate +``` + +```response +HTTP/1.1 200 OK + +{ + "type" : "invoice", + "id" : "E5", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", + "created" : "2023-05-17T15:22:38Z", + "netAmount" : 133.00, + "vatAmount" : 26.60, + "total" : 159.60, + "lines" : [ { + "description" : "Phone Extension", + "unitPrice" : 3.00, + "quantity" : 31, + "lineTotal" : 93.00, + "usage" : false + }, { + "description" : "Virtual Extension", + "unitPrice" : 0.00, + "quantity" : 11, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "Additional Mailbox", + "unitPrice" : 0.00, + "quantity" : 3, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "Ring Group", + "unitPrice" : 0.00, + "quantity" : 5, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "Call Queue", + "unitPrice" : 0.00, + "quantity" : 7, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "Voice Menu/IVR", + "unitPrice" : 0.00, + "quantity" : 7, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "Public Number", + "unitPrice" : 0.00, + "quantity" : 34, + "lineTotal" : 0.00, + "usage" : false + }, { + "description" : "500 Mins - UK Mobile", + "unitPrice" : 25.00, + "quantity" : 1, + "lineTotal" : 25.00, + "usage" : false + }, { + "description" : "250 Mins - UK Mobile", + "unitPrice" : 15.00, + "quantity" : 1, + "lineTotal" : 15.00, + "usage" : false + }, { + "description" : "1000 Mins - Local/National (Free)", + "unitPrice" : 0.00, + "quantity" : 1, + "lineTotal" : 0.00, + "usage" : false + } ], + "date" : "2023-05-17T15:22:38Z", + "credit" : false, + "currency" : "GBP" +} + +``` + + + + + + +### limits + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/limits | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | limits | +| Additional Formats | None | + +The limits sub-resource returns the current limits on different features for an account , represented by a `limits` instance. + +```exampleRepresentation +{ + "type": "customerlimits", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 50, + "group": 10, + "queue": 10, + "ivr": 10, + "mailbox": 10, + "trunk": 5, + "did": 20, + "channel": 5 +} +``` + +| Type: *limits* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("customerlimits")
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer limits.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| phone
*read-only* | total numbers of phones
*integer* | +| group
*read-only* | total number of groups
*integer* | +| queue
*read-only* | total number of queues
*integer* | +| ivr
*read-only* | total allowed ivrs
*integer* | +| mailbox
*read-only* | totalk mailboxes allowed
*integer* | +| did
*read-only* | total DID's allowed
*integer* | +| channel
*read-only* | total allowed channels
*integer* | + +#### Get limits + +`GET /customers/{customerId}/limits` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/limits +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "customerlimits", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 50, + "group": 10, + "queue": 10, + "ivr": 10, + "mailbox": 10, + "trunk": 5, + "did": 20, + "channel": 5 +} +``` + +### pricing + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/pricing | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get),[PUT](#put) | +| JSON Representation(s) | pricing | +| Additional Formats | None | + +The pricing sub-resource returns the current pricing or cost of different services for an account, represented by a `pricing` instance. + +```exampleRepresentation +{ + "type" : "customerpricing", + "id" : "25", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/pricing", + "parent" : "https://pbx.sipcentric.com/api/v1/customers/25", + "phone" : 2.00, + "virtual" : 0.10, + "group" : 4.00, + "queue" : 4.00, + "ivr" : 2.00, + "mailbox" : 2.00, + "did" : 3.00 +} +``` + +| Type: *pricing* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("customerpricing")
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer pricing.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| phone
*read-only* | price of phone
*float* | +| group
*read-only* | price of groups
*float* | +| queue
*read-only* | price of queues
*float* | +| ivr
*read-only* | price of ivrs
*float* | +| mailbox
*read-only* | price of mailboex
*float* | +| did
*read-only* | price per DID
*float* | + + +#### Get pricing + +`GET /customers/{customerId}/pricing` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/pricing +``` + +```response +HTTP/1.1 200 OK + +{ + "type" : "customerpricing", + "id" : "25", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/pricing", + "parent" : "https://pbx.sipcentric.com/api/v1/customers/25", + "phone" : 2.00, + "virtual" : 0.10, + "group" : 4.00, + "queue" : 4.00, + "ivr" : 2.00, + "mailbox" : 2.00, + "did" : 3.00 +} +``` + +`PUT /customers/{customerId}/pricing` + +To change the current pricing, please use a PUT as per the below. + +Example request: + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing + +{ + "type" : "customerpricing", + "phone" : 7 +} +``` + +```response +HTTP/1.1 200 OK +``` + +### linkedusers + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/linkedusers | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | linkedusers | +| Additional Formats | None | + +The Linked Users sub-resource returns the users that are linked to an account, represented by a `linkedusers` instance. + +```exampleRepresentation +{ + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "fred.muteesa+test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" +} +``` + +| Type: *linkedusers* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("customerlinkedusers")
*String* | +| id
*read-only* | The resource linkeduser id
*String* | +| uri
*read-only* | URI to get this linkeduser.
*String* | +| created
*read-only* | date and timestamp when this user was created
*date* | +| userId
*read-only* | Id of this user
*string* | +| email
*read-only* | email of this user
*string* | +| username
*read-only* | username for this user
*string* | +| accessLevel
*read-only* | this user's access level
*string* | +| enabled
*read-only* | enabled or not
*bolean* | +| pending
*read-only* | price per DID
*float* | +| acceptedInvite
*read-only* | price per DID
*float* | +| owner
*read-only* | whether this user is the account owner or not
*float* | +| recordingAccess
*read-only* | can access all records
*float* | + + +#### Get linkedusers + +`GET /customers/{customerId}/linkedusers` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers +``` + +```response +HTTP/1.1 200 OK + +{ + "totalItems": 1, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "fred.muteesa+test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" + } + ] +} +``` + +#### Get a linkeduser + +`GET /customers/{customerId}/linkedusers/{linkeduserId}` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180 +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "fred.muteesa+test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" +} +``` + +#### Get self linkeduser details +`GET /customers/{customerId}/linkedusers/me` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/me +``` + +```response +HTTP/1.1 200 OK + +{ + "type" : "linkeduser", + "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers/me", + "userId" : "27062", + "firstName" : "Fred", + "lastName" : "Muteesa", + "email" : "fred.muteesa@simwood.com", + "username" : "fred@sipcentric", + "accessLevel" : "ADMIN", + "enabled" : true, + "pending" : false, + "owner" : false, + "recordingAccess" : "NONE" +} +``` + +## Charging Plans + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /chargingPlans +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) (PUT/POST/DELETE) - not allowed | +| JSON Representation(s) | chargingplans | +| Additional Formats | None | + +The Available Charging Plans resource returns a list of charging plans that can be used, represented by a `chargingplans` instance. +This resource is used to set customers price plans. + + + +```exampleRepresentation + { + "type": "chargingplan", + "id": "1", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", + "name": "Standard", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 +} +``` + + + +| Type: *chargingplans* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("chargingplans")
*String* | +| id
*read-only* | The resource chargingplans id
*String* | +| uri
*read-only* | URI to get this chargingplan.
*String* | +| currency
*required* | The currency for this charging plan("GBP")
*date* | +| domainCostMinute
*required* |
*float* | +| roundSeconds
*requried* |
*integer* | +| minDuration
*read-only* | minimum duration
*integer* | +| minCharge
*read-only* | what is the charge per minute
*float* | + + + +#### Get chargingplans + +`GET /chargingplans/` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/chargingplans/ +``` + +```response +HTTP/1.1 200 OK + +"totalItems": 10, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "chargingplan", + "id": "1", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", + "name": "Standard", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 + }, + { + "type": "chargingplan", + "id": "36", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/36", + "name": "Special - 4.5p Mobile / 0.5p Landline", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 1, + "minCharge": 0.010 + }, + .... + ] +} +``` + +#### Get a charging plan + +`GET /chargingplans/{chargingplanId}` + +Example request: + +``` +GET https://pbx.sipcentric.com/api/v1/chargingplans/8 +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "chargingplan", + "id": "8", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/8", + "name": "Partner L2", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 +} +``` + + +## Analytics + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/calls/stats | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) (PUT/POST/DELETE) - not allowed | +| JSON Representation(s) | stats | +| Additional Formats | None | + +This section will describe the analytics that you see on your default dashboard in your account webui. +We can use the sipcentric API to pull this information and get back results using API requests. +Below are examples of requests we can send. I will be explaining the meaning of the returned results for every example provided here. + +#### Total Duration +`GET customers/{customerId}/calls/stats?` + + +Example request: + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration + +``` + + + + + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration", + "columnHeaders": [ + { + "name": "duration", + "columnType": "METRIC" + } + ], + "rows": [ + [ + 108.0 + ] + ], + "totals": { + "duration": 108.0 + } +} +``` + +**Explanation:** +From the above results we see that the total Duration for account 5 is 108.0 seconds. on the Web ui this will be represented as *1 minute and 48 seconds* + + +#### Total cost + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost + +``` + + +```response +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost", + "columnHeaders": [ + { + "name": "cost", + "columnType": "METRIC" + } + ], + "rows": [ + [ + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } +} + +``` + +**Explanation:** +This request has returned the current total cost as £0.00 + + + +#### Inbound Vs Outbound Duration + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration", + "columnHeaders": [ + { + "name": "direction", + "columnType": "DIMENSION" + }, + { + "name": "duration", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "in", + 0.0 + ], + [ + "out", + 108.0 + ] + ], + "totals": { + "duration": 108.0 + } +} + +``` +**Explanation:** +From the above response we can see that inbound has 0 seconds and Outbound has 108.0 which gives us a total of 108.0 seconds + + +#### Get Duration by Extension +This example will show us the total number of seconds consumed by exach extension. This is further categorized by inbound and outbound duration. + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension + +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension", + "columnHeaders": [ + { + "name": "endpoint", + "columnType": "DIMENSION" + }, + { + "name": "duration_in", + "columnType": "METRIC" + }, + { + "name": "duration_out", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "Charles Chance <102>", + 0.0, + 55.0 + ], + [ + "Ivan Example <111>", + 0.0, + 0.0 + ], + [ + "Jared Example <215>", + 53.0, + 0.0 + ] + ], + "totals": { + "duration_in": 53.0, + "duration_out": 55.0 + } +} + +``` +**Explanation:** +In the above example, we see that this week has had three exentions making or receiving calls. +charles, Ivan, Jared + + + +#### Get Calls by Extensions +The request would give us the number of calls made or received by each extension in the account. + + +Example + +``` +GET +https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=count_in&metric=count_out&endpointType=extension + +``` + +```response +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=count_in&metric=count_out&endpointType=extension", + "columnHeaders": [ + { + "name": "endpoint", + "columnType": "DIMENSION" + }, + { + "name": "count_in", + "columnType": "METRIC" + }, + { + "name": "count_out", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "Charles Chance <102>", + 1.0, + 5.0 + ], + [ + "Ivan Example <111>", + 1.0, + 0.0 + ], + [ + "Jared Example <215>", + 3.0, + 1.0 + ] + ], + "totals": { + "count_in": 5.0, + "count_out": 6.0 + } +} +``` + +**Explantion** +The above result shows us that we have received 5 calls and made 6 calls. You can also see that charles received 1 call and made 5 calls. + + +#### Get Calls Outcome +This request gives you visibility into Call dispositions. That is, what happened to the call, was it answered or not? +You are able to see the number Unanswered calls + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in + +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in", + "columnHeaders": [ + { + "name": "outcome", + "columnType": "DIMENSION" + }, + { + "name": "count", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "NO ANSWER", + 2.0 + ] + ], + "totals": { + "count": 2.0 + } +} + +``` + + +#### Get Top Callers + +You can use the exmaple below to see which number calls your DID's the most. + +Example + +``` +GET +https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=callerid&metric=count&sort=-count&scope=external&direction=in&limit=10 + +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=callerid&metric=count&sort=-count&scope=external&direction=in&limit=10", + "columnHeaders": [ + { + "name": "callerid", + "columnType": "DIMENSION" + }, + { + "name": "count", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "07760431465", + 1.0 + ] + ], + "totals": { + "count": 1.0 + } +} + +``` + + + + +#### Get Average Wait Time + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue + +``` + +```response +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + }, + { + "name": "avg_duration", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "avg_duration": "NaN" + } +} + +``` + + +#### Get Daily Calls + +You can also see total calls per day of the week. + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out + +``` + +```response +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + }, + { + "name": "count_in", + "columnType": "METRIC" + }, + { + "name": "count_out", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0, + 0.0 + ], + [ + "2023-05-23T00:00:00.000+03:00", + 2.0, + 6.0 + ], + [ + "2023-05-24T00:00:00.000+03:00", + 0.0, + 0.0 + ], + [ + "2023-05-25T00:00:00.000+03:00", + 0.0, + 0.0 + ], + [ + "2023-05-26T00:00:00.000+03:00", + 0.0, + 0.0 + ], + [ + "2023-05-27T00:00:00.000+03:00", + 0.0, + 0.0 + ], + [ + "2023-05-28T00:00:00.000+03:00", + 0.0, + 0.0 + ] + ], + "totals": { + "count_in": 2.0, + "count_out": 6.0 + } +} +``` + + +#### Get Daily Cost + +You can also get information about how much you spend per day. + +Example + +``` +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost + +``` + +```response +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + }, + { + "name": "cost", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ], + [ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } +} +``` + + + ## Global Resources ### Token Generator From 3707d2627ebb5a7222dc6a061eb144b9c43bf8ac Mon Sep 17 00:00:00 2001 From: Fred Date: Mon, 12 Jun 2023 09:30:54 +0300 Subject: [PATCH 06/15] remove charles address --- docs/direct/api/v1.md | 68 +++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index c44d8f1..2cae99d 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -38,7 +38,7 @@ Instead of defining its own, arbitrary methods, the Sipcentric API utilizes four #### GET -*Retrieving* a representation of a resource is as easy as GETting its URI. A simple way to test this is to type the URI of the desired resource into the address bar of your web browser. +*Retrieving* a representation of a resource is as easy as GETting its URI. A simple way to Test this is to type the URI of the desired resource into the address bar of your web browser. ##### Response Codes @@ -269,14 +269,14 @@ The customers resource is the starting point for most account-level operations. "created": "2010-12-21T08:30:31Z", "accountType": "BUSINESS", "company": "Sipcentric Ltd.", - "firstName": "Charles", - "lastName": "Chance", - "telephone": "18002274500", + "firstName": "Fred", + "lastName": "Test", + "telephone": "07557000000", "email": "support@sipcentric.com", "address1": "The Oaks", "address2": "Ribbesford", "city": "Bewdley", - "postcode": "98048", + "postcode": "98999", "country": "US", "properties": {}, "enabled": true, @@ -357,14 +357,14 @@ HTTP/1.1 200 OK "created": "2010-12-21T08:30:31Z", "accountType": "BUSINESS", "company": "Sipcentric Ltd.", - "firstName": "Charles", - "lastName": "Chance", - "telephone": "18002274500", + "firstName": "Fred", + "lastName": "Test", + "telephone": "07557000000", "email": "support@sipcentric.com", "address1": "The Oaks", "address2": "Ribbesford", "city": "Bewdley", - "postcode": "98048", + "postcode": "98999", "country": "US", "properties": {}, "enabled": true, @@ -419,7 +419,7 @@ HTTP/1.1 200 OK "company": "Fred Test", "firstName": "Fred", "lastName": "Muteesa", - "email": "test@simwood.com", + "email": "Test@simwood.com", "country": "GB", "properties": {}, "enabled": true, @@ -463,8 +463,8 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook "accountType": "BUSINESS", "company": "Simwood", "firstName": "Fred", -"lastName": "TEST API", -"email": "test@test.com", +"lastName": "Test API", +"email": "Test@Test.com", "address1": "Simwood House", "address2": "Cube m4 Business Park", "city": "Bristol", @@ -491,9 +491,9 @@ HTTP/1.1 201 Created "accountType": "BUSINESS", "company": "Simwood", "firstName": "Fred", - "lastName": "TEST API", + "lastName": "Test API", "telephone": "03301229999", - "email": "test@test.com", + "email": "Test@Test.com", "address1": "Simwood House", "address2": "Cube m4 Business Park", "city": "Bristol", @@ -549,7 +549,7 @@ The phonebook sub-resource allows users to read and organize an account's shared "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", - "email": "email@test.com", + "email": "email@Test.com", "speedDial": 123, "priority": 0 } @@ -598,7 +598,7 @@ HTTP/1.1 200 OK "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", - "email": "email@test.com", + "email": "email@Test.com", "speedDial": 123, "priority": -50 }, @@ -608,7 +608,7 @@ HTTP/1.1 200 OK "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2023-05-04T09:13:08Z", - "name": "Fred test 3", + "name": "Fred Test 3", "phoneNumber": "256761303030", "priority": 0 } @@ -642,7 +642,7 @@ HTTP/1.1 200 OK "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", - "email": "email@test.com", + "email": "email@Test.com", "speedDial": 123, "priority": -50 } @@ -1822,7 +1822,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2023-05-15T19:43:10Z", "shortNumber": "102", - "name": "fred", + "name": "Fred", "timeout": 30, "callWaiting": false, "callRecording": "OFF", @@ -1858,7 +1858,7 @@ PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 Json body {"type":"ivr", "id":"83066", -"name":"fred-lab-ivr2", +"name":"Fred-lab-ivr2", "timeout":5, "shortNumber":500 } @@ -1875,7 +1875,7 @@ HTTP/1.1 200 OK "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2023-01-24T16:43:22Z", "shortNumber": "500", - "name": "fred-lab-ivr2", + "name": "Fred-lab-ivr2", "timeout": 5, "items": [] } @@ -1893,7 +1893,7 @@ example request: POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints Body -{"callRecording":"OFF","timeout":30,"name":"fred","shortNumber":"102","type":"phone"} +{"callRecording":"OFF","timeout":30,"name":"Fred","shortNumber":"102","type":"phone"} ``` @@ -1908,7 +1908,7 @@ HTTP/1.1 200 OK "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2023-05-15T19:43:10Z", "shortNumber": "102", - "name": "fred", + "name": "Fred", "timeout": 30, "callWaiting": false, "callRecording": "OFF", @@ -2037,7 +2037,7 @@ HTTP/1.1 200 OK "identifier" : "Main", "smsEnabled" : true, "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@fredbloggs.com", + "smsNotificationEmail" : "contact@Fredbloggs.com", "smsNotificationUrl" : "https://example.com/sms", "faxEnabled" : false }, { @@ -2094,7 +2094,7 @@ HTTP/1.1 200 OK "identifier" : "Main", "smsEnabled" : true, "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@fredbloggs.com", + "smsNotificationEmail" : "contact@Fredbloggs.com", "smsNotificationUrl" : "https://example.com/sms", "faxEnabled" : false } @@ -3239,7 +3239,7 @@ The Linked Users sub-resource returns the users that are linked to an account, "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", - "email": "fred.muteesa+test@simwood.com", + "email": "Fred.muteesa+Test@simwood.com", "username": "fmuteesa", "accessLevel": "CUSTOMER", "enabled": true, @@ -3292,7 +3292,7 @@ HTTP/1.1 200 OK "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", - "email": "fred.muteesa+test@simwood.com", + "email": "Fred.muteesa+Test@simwood.com", "username": "fmuteesa", "accessLevel": "CUSTOMER", "enabled": true, @@ -3324,7 +3324,7 @@ HTTP/1.1 200 OK "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", - "email": "fred.muteesa+test@simwood.com", + "email": "Fred.muteesa+Test@simwood.com", "username": "fmuteesa", "accessLevel": "CUSTOMER", "enabled": true, @@ -3353,8 +3353,8 @@ HTTP/1.1 200 OK "userId" : "27062", "firstName" : "Fred", "lastName" : "Muteesa", - "email" : "fred.muteesa@simwood.com", - "username" : "fred@sipcentric", + "email" : "Fred.muteesa@simwood.com", + "username" : "Fred@sipcentric", "accessLevel" : "ADMIN", "enabled" : true, "pending" : false, @@ -3655,7 +3655,7 @@ HTTP/1.1 200 OK ], "rows": [ [ - "Charles Chance <102>", + "Fred Test <102>", 0.0, 55.0 ], @@ -3679,7 +3679,7 @@ HTTP/1.1 200 OK ``` **Explanation:** In the above example, we see that this week has had three exentions making or receiving calls. -charles, Ivan, Jared +Fred, Ivan, Jared @@ -3718,7 +3718,7 @@ HTTP/1.1 200 OK ], "rows": [ [ - "Charles Chance <102>", + "Fred Test <102>", 1.0, 5.0 ], @@ -3741,7 +3741,7 @@ HTTP/1.1 200 OK ``` **Explantion** -The above result shows us that we have received 5 calls and made 6 calls. You can also see that charles received 1 call and made 5 calls. +The above result shows us that we have received 5 calls and made 6 calls. You can also see that Fred received 1 call and made 5 calls. #### Get Calls Outcome From 2601911878f45e2f41fe2365dd2d026045bc7a3b Mon Sep 17 00:00:00 2001 From: Fred Date: Mon, 12 Jun 2023 11:49:03 +0300 Subject: [PATCH 07/15] added tabs and syntax highliting to code blocks --- docs/direct/api/v1.md | 752 +++++++++++++++++++++++++++++++++--------- 1 file changed, 592 insertions(+), 160 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index 2cae99d..4dbd08e 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -2,6 +2,8 @@ id: v1 title: Version 1 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; ## Overview @@ -172,13 +174,18 @@ contain the following information: | nextPage | A link to the next page (again, if it exists). | -Example request: + + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&page=2 ``` + + -```response +```bash HTTP/1.1 200 OK { @@ -217,6 +224,8 @@ HTTP/1.1 200 OK } ``` + + #### Query Parameters @@ -260,7 +269,7 @@ All dates and times are formatted according to the ISO 8601 profile. For example The customers resource is the starting point for most account-level operations. Each customer instance represents an account on the Sipcentric platform - it encapsulates a single company/PBX and all of its sub-resources. -```exampleRepresentation +```bash exampleRepresentation { "type": "customer", @@ -335,14 +344,20 @@ The customers resource is the starting point for most account-level operations. Lists all customer accounts to which the authenticating user has access. When authenticated as an extension user or a company admin, this will only return their own account. However, when authenticated as a reseller, all customer accounts owned by that reseller will be returned. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers ``` -```response + + + +```bash + HTTP/1.1 200 OK { @@ -392,7 +407,8 @@ HTTP/1.1 200 OK ] } ``` - + + #### Get customer @@ -400,14 +416,19 @@ HTTP/1.1 200 OK Returns a single customer instance, providing the user is allowed access to that customer. In the case of company admin/extension users, the special ID of `me` can also be used to return the account to which the current user belongs. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/me ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -445,16 +466,19 @@ HTTP/1.1 200 OK "userEmailUpdatable": false } ``` - + + #### Create a Customer `POST /customers/{customerId}/customers/` To create a new customer, a representation of a `customer` must be POSTed to the `customers` resource. The newly created `Customer` ID will then be included in the body of the response. -Example request: + + -``` + +```bash POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook { @@ -479,7 +503,10 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook } ``` -```response + + + +```bash HTTP/1.1 201 Created @@ -524,7 +551,8 @@ HTTP/1.1 201 Created } ``` - + + ### Phone Book @@ -540,7 +568,7 @@ HTTP/1.1 201 Created The phonebook sub-resource allows users to read and organize an account's shared phone book entries. Each entry is represented by a `phonebookentry`. -```exampleRepresentation +```bash exampleRepresentation { "type": "phonebookentry", "id": "84033", @@ -576,13 +604,18 @@ The phonebook sub-resource allows users to read and organize an account's shared Return a list of every `phonebookentry` on the customer account. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -616,7 +649,8 @@ HTTP/1.1 200 OK "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" } ``` - + + #### Read phone book entry @@ -624,14 +658,19 @@ HTTP/1.1 200 OK Returns the instance of an individual `phonebookentry`. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -648,7 +687,8 @@ HTTP/1.1 200 OK } ``` - + + #### Create phone book entry @@ -656,9 +696,11 @@ HTTP/1.1 200 OK To create a new phone book entry, a representation of a `phonebookentry` must be POSTed to the `phonebook` resource. The newly created `phonebookentry` representation will then be included in the body of the response. -Example request: + + -``` + +```bash POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook { @@ -669,7 +711,10 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook } ``` -```response + + + +```bash HTTP/1.1 201 Created { @@ -683,7 +728,8 @@ HTTP/1.1 201 Created "priority": 0 } ``` - + + #### Update phone book entry @@ -691,9 +737,12 @@ HTTP/1.1 201 Created To update a `phonebookentry`, a representation of the updated `phonebookentry` must be PUT to that instance resource. The updated `phonebookentry` representation will then be returned in the body of the response. -Example request: + + + + +```bash -``` PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 { @@ -704,7 +753,11 @@ PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 } ``` -```response + + + +```bash + HTTP/1.1 200 OK { @@ -715,8 +768,10 @@ HTTP/1.1 200 OK "phoneNumber": "07825000000", "speedDial": 12 } -``` +``` + + #### Delete phone book entry @@ -724,13 +779,21 @@ HTTP/1.1 200 OK To delete a `phonebookentry`, a DELETE request must be made to the instance resource. + + + ``` DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 ``` -```response + + + +```bash HTTP/1.1 204 No Content ``` + + ### SMS @@ -747,7 +810,7 @@ HTTP/1.1 204 No Content The SMS sub-resource contains a record of every SMS message sent or received on the account, each item represented by a single `smsmessage`. -``` +```bash { "type": "smsmessage", "id": "31408968", @@ -787,11 +850,17 @@ The SMS sub-resource contains a record of every SMS message sent or received on Returns a list of every `smsmessage` on the account. + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { "totalItems": 3, @@ -832,6 +901,8 @@ HTTP/1.1 200 OK "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" } ``` + + #### Get SMS Message @@ -839,11 +910,17 @@ HTTP/1.1 200 OK Returns the instance of a specific `smsmessage`. + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -862,7 +939,8 @@ HTTP/1.1 200 OK "creditsUsed": 1 } ``` - + + #### Send SMS `POST /customers/{customerId}/sms` @@ -871,7 +949,10 @@ To send a new SMS, simply POST a representation of a new `smsmessage` to the lis **NB** the From number has to be a number configured in your account. -``` + + + +```bash POST https://pbx.sipcentric.com/api/v1/customers/25/sms { @@ -882,7 +963,10 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/sms } ``` -```response + + + +```bash HTTP/1.1 201 Created { @@ -899,6 +983,8 @@ HTTP/1.1 201 Created "creditsUsed": 1 } ``` + + ### Calls @@ -921,7 +1007,7 @@ The scope of a call can be: - External - to/from an external number on the PSTN. -``` +```bash { "type": "call", "id": "209925287", @@ -989,11 +1075,17 @@ Making a GET request to the list resource will return a history of the calls mad | endpointId | Integer | Only include calls involving a specific endpoint ID. | + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1043,6 +1135,8 @@ HTTP/1.1 200 OK "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2" } ``` + + #### Originate call @@ -1050,7 +1144,9 @@ HTTP/1.1 200 OK To originate a new call, you should POST a new `call` representation containing the properties shown below, to the calls list resource. -Example request: + + + ``` POST https://pbx.sipcentric.com/api/v1/customers/25/calls @@ -1063,9 +1159,14 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/calls ``` -```response + + + +```bash HTTP/1.1 200 OK ``` + + In the above example, a connection will first be established with the specified local endpoint ("endpoint"). We will then attempt to place a call to the remote destination ("to") and finally bridge the two together. @@ -1076,13 +1177,18 @@ In the above example, a connection will first be established with the specified To check the current status of an endpoint, run the above - dndActive is a boolean that will confirm whether the endpoint is happy to accept calls. NB: Regardless of how many devices are connected to an endpoint, if Do Not Disturb (dnd) is set, then no calls will be presented to the endpoint. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus ``` -```response + + + +```bash { "type": "phonestatus", "id": "94", @@ -1091,13 +1197,17 @@ GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus "dndActive": false } ``` + + `PUT /customers/{customerId}/endpoints/{endpointId}/phonestatus` To change the current status of an endpoint, please use a PUT as per the below. -Example request: + + + ``` PUT https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus @@ -1107,9 +1217,14 @@ PUT https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus "dndActive": true } ``` -```response + + + +```bash HTTP/1.1 200 OK ``` + + ### Sounds @@ -1171,13 +1286,18 @@ Returns all sounds, optionally filtered by the following query parameters: |:------------------------|:-------|:----------------------------------------------------------| | type | String | Include only a specific type of sound file (prompt/music) | -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1204,6 +1324,8 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" } ``` + + #### Get sound @@ -1211,13 +1333,18 @@ HTTP/1.1 200 OK Returns the instance of a specific sound file. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1229,6 +1356,8 @@ HTTP/1.1 200 OK "size" : 69426 } ``` + + It is also possible to fetch a copy of the audio file itself, by including the `Accept` header: @@ -1251,7 +1380,7 @@ See [Response Formats](#response-formats) for more information. The recordings sub-resource provides a way to retrieve and manage the call recordings which are currently stored on an account. Each `recording` representation contains a set of properties which allow for easy indexing/searching based on the local endpoint, remote party ID, time of recording etc. -```exampleRepresentation +```bash exampleRepresentation { "type": "recording", "id": "1358371", @@ -1298,13 +1427,18 @@ Returns a list of recordings, optionally filtered by the following query paramet | callId | String | Include only recordings relating to a specific call leg. | | linkedId | String | Include only recordings relating to calls with the same linked ID. | -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1343,19 +1477,27 @@ HTTP/1.1 200 OK } ``` + + + #### Get recording `GET /customers/{customerId}/recordings/{recordingId}` Fetches the instance of a specific recording. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1373,6 +1515,8 @@ HTTP/1.1 200 OK "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" } ``` + + It is also possible to fetch a copy of the audio file itself, by including the `Accept` header: @@ -1395,7 +1539,7 @@ See [Response Formats](#response-formats) for more information. A time interval (`timeinterval`) defines the single or set of time periods which together, constitute a recurring weekly/yearly event or work pattern - for example, "Out of Hours", "Public Holidays" or "My Cat's Birthday". Time intervals are used for matching against when defining time-based routing or access rules elsewhere on the system. -```exampleRepresentation +```bash exampleRepresentation { "type": "timeinterval", "id": "431", @@ -1452,13 +1596,18 @@ A time interval (`timeinterval`) defines the single or set of time periods which Returns a list of previously defined time intervals on an account. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1512,6 +1661,9 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" } ``` + + + #### Get time interval @@ -1519,14 +1671,19 @@ HTTP/1.1 200 OK Returns the instance of a specific time interval. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1561,6 +1718,9 @@ HTTP/1.1 200 OK } ``` + + + ### Endpoints | Resource Information | | @@ -1697,13 +1857,18 @@ The properties of each endpoint type are listed below. `GET /customers/{customerId}/endpoints` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1739,18 +1904,26 @@ HTTP/1.1 200 OK "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=1&page=2" } ``` + + + #### Get endpoint `GET /customers/{customerId}/endpoints/{endpointID}` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -1772,6 +1945,8 @@ HTTP/1.1 200 OK } } ``` + + #### List endpoints filterd by type. @@ -1779,11 +1954,17 @@ HTTP/1.1 200 OK you might want to get all extensions or all ivrs that are on the account. In this case you send a GET request with a type parameter as shown below. + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone ``` -```response + + + +```bash { "totalItems": 2, @@ -1844,13 +2025,18 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone ``` + + + #### Updating an endpoint. `PUT /customers/{customerId}/endpoints/{endpointId} ` Depending on what property of the end point you want to update, you will need to send a PUT request to the following resrouce. You have to know the endpointID and the endpoint type. Depending on the endpoint type you are updating, some fields are required in the body, hence if you miss difinition of one of the parameters, your request will fail. In the example below I am updating the name of the IVR, but the rest of the fields I have included must be provided for the request to work. -Example Request: + + + ``` PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 @@ -1865,7 +2051,10 @@ Json body ``` -```Response + + + +```bash HTTP/1.1 200 OK { @@ -1881,13 +2070,17 @@ HTTP/1.1 200 OK } ``` + + #### Add an extension endpoint To add an extention or phone type endpoint to an account, you need to send a POST request as shown below. Please not that some short numbers are reserved and can not be added as extensions. an example is **101**. the system will automatically return an error in case you try to add these numbers. -example request: + + + ``` POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints @@ -1897,7 +2090,10 @@ Body ``` -```Response + + + +```bash HTTP/1.1 200 OK @@ -1926,6 +2122,8 @@ HTTP/1.1 200 OK } } ``` + + #### Delete Endpoint @@ -1958,7 +2156,7 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 Phone numbers provide a route into the system from outside - they can support calls and optionally SMS messages, where available. Each inbound number is represented by a `did`. -```exampleRepresentation +```bash exampleRepresentation { "type" : "did", "id": "50", @@ -2014,13 +2212,18 @@ Phone numbers provide a route into the system from outside - they can support ca Returns a list of all phone numbers on a customer account. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=1 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2068,6 +2271,8 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" } ``` + + #### Get phone number @@ -2075,13 +2280,18 @@ HTTP/1.1 200 OK Retrieves the instance of a specific phone number. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2099,6 +2309,8 @@ HTTP/1.1 200 OK "faxEnabled" : false } ``` + + #### Add a new Phone Number @@ -2107,7 +2319,9 @@ HTTP/1.1 200 OK To add an availablenumber to a customer account please use a POST as per the below. NB: This number should be available in the simwood inventory. you can check Available numbers api , to see available numbers. -Example request: + + + ``` POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers @@ -2118,7 +2332,10 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers } ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2136,6 +2353,9 @@ HTTP/1.1 200 OK } } ``` + + + #### Linking Phone Number to extension @@ -2146,9 +2366,11 @@ To link a phonenumber in a customer's account to an extension inside the custome NB: This phone number should already be added to the account. Please see , adding Phone numbers. -Example request: + + -``` + +```bash PUT https://pbx.sipcentric.com/api/v1/customers/{customerId}/phonenumbers/{phonenumberId}/ Body { @@ -2168,7 +2390,10 @@ Body { } ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2188,6 +2413,9 @@ HTTP/1.1 200 OK } ``` + + + #### UN-Linking Phone Number and extension @@ -2196,9 +2424,11 @@ HTTP/1.1 200 OK To un-link or remove the link between a phonenumber and an extension, you need to send another PUT request without detination in the body. -Example Request + + -``` + +```bash PUT https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 Body @@ -2218,7 +2448,10 @@ Body } ``` -```Response + + + +```bash HTTP/1.1 200 OK { @@ -2237,6 +2470,8 @@ HTTP/1.1 200 OK } } ``` + + #### Delete Phone Number `DELETE /customers/{customerId}/phonenumbers/{phonenumberId}` @@ -2267,7 +2502,7 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 The Available Numbers sub-resource returns a list of available numbers that can be added to a customer account, represented by a `availablenumber` instance. After listing the available numbers you can add a number to your account see. -```exampleRepresentation +```bash exampleRepresentation { "type": "availablenumber", "id": "4-44-113-4037921", @@ -2300,13 +2535,18 @@ The Available Numbers sub-resource returns a list of available numbers that can `GET /availablenumbers?areaCode=113&country=44&pageSize=100` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/availablenumbers?areaCode=113&country=44&pageSize=100&location=GB ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2336,18 +2576,25 @@ HTTP/1.1 200 OK ] } ``` + + #### Get an available number `GET /availablenumber/{availablenumberId}` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2360,6 +2607,8 @@ HTTP/1.1 200 OK "formatted": "0113 403 7921" } ``` + + @@ -2377,7 +2626,7 @@ HTTP/1.1 200 OK Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. -```exampleRepresentation +```bash exampleRepresentation { "type": "outgoingcallerid", "id": "114", @@ -2409,13 +2658,18 @@ Usually, when making calls or sending SMS messages from an account, the outgoing Lists the IDs which have been approved for use on the account. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2446,6 +2700,8 @@ HTTP/1.1 200 OK ] } ``` + + #### Get outgoing caller id @@ -2453,13 +2709,18 @@ HTTP/1.1 200 OK Get the instance of a specific caller ID. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2473,6 +2734,8 @@ HTTP/1.1 200 OK "allowSms": true } ``` + + ### Credit Status @@ -2488,7 +2751,7 @@ HTTP/1.1 200 OK The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "creditstatus", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", @@ -2510,13 +2773,18 @@ The credit status sub-resource returns the current call credit status of an acco `GET /customers/{customerId}/creditstatus` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/creditstatus ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2526,6 +2794,8 @@ HTTP/1.1 200 OK "balance": 19.571 } ``` + + ### Call Bundles @@ -2541,7 +2811,7 @@ HTTP/1.1 200 OK The call bundles sub-resource contains all bundles which have been added to an account - each is represented by a `customerbundle` and includes the current status, as well as used and remaining minutes. -```exampleRepresentation +```bash exampleRepresentation { type: "customerbundle", id: "1040" @@ -2584,13 +2854,18 @@ The call bundles sub-resource contains all bundles which have been added to an a List all bundles added to an account. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2617,6 +2892,9 @@ HTTP/1.1 200 OK ] } ``` + + + #### Get call bundle @@ -2624,13 +2902,18 @@ HTTP/1.1 200 OK Fetches the instance of a specific customer bundle. -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2650,7 +2933,8 @@ HTTP/1.1 200 OK "status": "ACTIVE" } ``` - + + ### Call Charging @@ -2666,7 +2950,7 @@ HTTP/1.1 200 OK The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "customercallcharging", "id": "25", @@ -2695,13 +2979,18 @@ The call charging sub-resource returns the current call charging plan for an ac `GET /customers/{customerId}/callcharging` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/callcharging ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2715,7 +3004,8 @@ HTTP/1.1 200 OK "warningThreshold": 0.00 } ``` - + + ### Permissions @@ -2731,7 +3021,7 @@ HTTP/1.1 200 OK The Permissions sub-resource returns the current customer permissions for an account, represented by a `permissions` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "customerpermissions", "id": "25", @@ -2764,13 +3054,18 @@ The Permissions sub-resource returns the current customer permissions for an a `GET /customers/{customerId}/permissions` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/permissions ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2786,6 +3081,9 @@ HTTP/1.1 200 OK "enableRecording": true } ``` + + + ### billing @@ -2801,7 +3099,7 @@ HTTP/1.1 200 OK The billing sub-resource returns the current billing configuration and pricing plan for an different features, represented by a `billing` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "billingaccount", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", @@ -2850,13 +3148,18 @@ The billing sub-resource returns the current billing configuration and pricing `GET /customers/{customerId}/billing` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/billing ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -2888,6 +3191,9 @@ HTTP/1.1 200 OK } } ``` + + + ### Estimates @@ -2906,7 +3212,7 @@ This resource is used to set customers price plans. -```exampleRepresentation +```bash exampleRepresentation { "type" : "invoice", "id" : "E5", @@ -2961,13 +3267,18 @@ This resource is used to set customers price plans. `GET /customers/{customerId}/billing/estimates/` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3046,7 +3357,8 @@ HTTP/1.1 200 OK ``` - + + @@ -3065,7 +3377,7 @@ HTTP/1.1 200 OK The limits sub-resource returns the current limits on different features for an account , represented by a `limits` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "customerlimits", "id": "25", @@ -3101,13 +3413,18 @@ The limits sub-resource returns the current limits on different features for an `GET /customers/{customerId}/limits` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/limits ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3125,6 +3442,9 @@ HTTP/1.1 200 OK "channel": 5 } ``` + + + ### pricing @@ -3140,7 +3460,7 @@ HTTP/1.1 200 OK The pricing sub-resource returns the current pricing or cost of different services for an account, represented by a `pricing` instance. -```exampleRepresentation +```bash exampleRepresentation { "type" : "customerpricing", "id" : "25", @@ -3175,13 +3495,18 @@ The pricing sub-resource returns the current pricing or cost of different servi `GET /customers/{customerId}/pricing` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/pricing ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3198,12 +3523,16 @@ HTTP/1.1 200 OK "did" : 3.00 } ``` + + `PUT /customers/{customerId}/pricing` To change the current pricing, please use a PUT as per the below. -Example request: + + + ``` PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing @@ -3214,9 +3543,14 @@ PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing } ``` -```response + + + +```bash HTTP/1.1 200 OK ``` + + ### linkedusers @@ -3232,7 +3566,7 @@ HTTP/1.1 200 OK The Linked Users sub-resource returns the users that are linked to an account, represented by a `linkedusers` instance. -```exampleRepresentation +```bash exampleRepresentation { "type": "linkeduser", "id": "35180", @@ -3272,13 +3606,18 @@ The Linked Users sub-resource returns the users that are linked to an account, `GET /customers/{customerId}/linkedusers` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3304,18 +3643,25 @@ HTTP/1.1 200 OK ] } ``` + + #### Get a linkeduser `GET /customers/{customerId}/linkedusers/{linkeduserId}` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3334,17 +3680,24 @@ HTTP/1.1 200 OK "recordingAccess": "ALL" } ``` + + #### Get self linkeduser details `GET /customers/{customerId}/linkedusers/me` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/me ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3362,6 +3715,8 @@ HTTP/1.1 200 OK "recordingAccess" : "NONE" } ``` + + ## Charging Plans @@ -3380,7 +3735,7 @@ This resource is used to set customers price plans. -```exampleRepresentation +```bash exampleRepresentation { "type": "chargingplan", "id": "1", @@ -3414,13 +3769,18 @@ This resource is used to set customers price plans. `GET /chargingplans/` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/chargingplans/ ``` -```response + + + +```bash HTTP/1.1 200 OK "totalItems": 10, @@ -3453,18 +3813,25 @@ HTTP/1.1 200 OK ] } ``` + + #### Get a charging plan `GET /chargingplans/{chargingplanId}` -Example request: + + + ``` GET https://pbx.sipcentric.com/api/v1/chargingplans/8 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3479,7 +3846,8 @@ HTTP/1.1 200 OK "minCharge": 0.000 } ``` - + + ## Analytics @@ -3501,7 +3869,9 @@ Below are examples of requests we can send. I will be explaining the meaning of `GET customers/{customerId}/calls/stats?` -Example request: + + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration @@ -3512,7 +3882,10 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```response + + + +```bash HTTP/1.1 200 OK { @@ -3534,6 +3907,8 @@ HTTP/1.1 200 OK } } ``` + + **Explanation:** From the above results we see that the total Duration for account 5 is 108.0 seconds. on the Web ui this will be represented as *1 minute and 48 seconds* @@ -3541,7 +3916,8 @@ From the above results we see that the total Duration for account 5 is 108.0 sec #### Total cost -Example + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost @@ -3549,7 +3925,10 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 ``` -```response + + + +```bash HTTP/1.1 200 OK @@ -3573,6 +3952,8 @@ HTTP/1.1 200 OK } ``` + + **Explanation:** This request has returned the current total cost as £0.00 @@ -3581,13 +3962,17 @@ This request has returned the current total cost as £0.00 #### Inbound Vs Outbound Duration -Example + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3619,6 +4004,9 @@ HTTP/1.1 200 OK } ``` + + + **Explanation:** From the above response we can see that inbound has 0 seconds and Outbound has 108.0 which gives us a total of 108.0 seconds @@ -3626,14 +4014,18 @@ From the above response we can see that inbound has 0 seconds and Outbound has 1 #### Get Duration by Extension This example will show us the total number of seconds consumed by exach extension. This is further categorized by inbound and outbound duration. -Example + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3677,6 +4069,8 @@ HTTP/1.1 200 OK } ``` + + **Explanation:** In the above example, we see that this week has had three exentions making or receiving calls. Fred, Ivan, Jared @@ -3687,7 +4081,8 @@ Fred, Ivan, Jared The request would give us the number of calls made or received by each extension in the account. -Example + + ``` GET @@ -3695,7 +4090,10 @@ https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21 ``` -```response + + + +```bash HTTP/1.1 200 OK @@ -3739,6 +4137,9 @@ HTTP/1.1 200 OK } } ``` + + + **Explantion** The above result shows us that we have received 5 calls and made 6 calls. You can also see that Fred received 1 call and made 5 calls. @@ -3748,14 +4149,19 @@ The above result shows us that we have received 5 calls and made 6 calls. You c This request gives you visibility into Call dispositions. That is, what happened to the call, was it answered or not? You are able to see the number Unanswered calls -Example + + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3784,12 +4190,16 @@ HTTP/1.1 200 OK ``` + + #### Get Top Callers You can use the exmaple below to see which number calls your DID's the most. -Example + + + ``` GET @@ -3797,7 +4207,10 @@ https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21 ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3826,19 +4239,25 @@ HTTP/1.1 200 OK ``` - + + #### Get Average Wait Time -Example + + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue ``` -```response + + + +```bash HTTP/1.1 200 OK @@ -3891,20 +4310,26 @@ HTTP/1.1 200 OK } ``` - + + #### Get Daily Calls You can also see total calls per day of the week. -Example + + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out ``` -```response + + + +```bash HTTP/1.1 200 OK { @@ -3967,20 +4392,26 @@ HTTP/1.1 200 OK } } ``` - + + #### Get Daily Cost You can also get information about how much you spend per day. -Example + + + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost ``` -```response + + + +```bash HTTP/1.1 200 OK @@ -4032,7 +4463,8 @@ HTTP/1.1 200 OK } } ``` - + + ## Global Resources @@ -4046,7 +4478,7 @@ you would normally have to authenticate for. #### Get token -``` +```bash GET https://pbx.sipcentric.com/api/v1/tokengenerator { @@ -4081,7 +4513,7 @@ Currently the following is available via the streaming API: Example object: -``` +```bash { "event": "incomingcall", "location": null, @@ -4107,7 +4539,7 @@ Most HTTP client libraries let you handle the connection as a stream. Which allo All of the event objects are in a standard format: -``` +```bash { "event": ..., "location": ..., From ff311f355ab1692e827c1c9c05d1c2cfbfb129ac Mon Sep 17 00:00:00 2001 From: Fred Date: Thu, 7 Sep 2023 20:10:57 +0300 Subject: [PATCH 08/15] more documentation regarding linked users --- docs/direct/api/v1.md | 51 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index 4dbd08e..040a4e6 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -468,6 +468,7 @@ HTTP/1.1 200 OK ``` + #### Create a Customer `POST /customers/{customerId}/customers/` @@ -554,6 +555,8 @@ HTTP/1.1 201 Created + + ### Phone Book | Resource Information | | @@ -3007,6 +3010,40 @@ HTTP/1.1 200 OK + +#### Updating callcharging plan for a customer + +`PUT /customers/{customerId}/callcharging` + + + + + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/25/callcharging +``` + + + + +```bash +HTTP/1.1 200 OK + +{ + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + + + + ### Permissions | Resource Information | | @@ -3097,7 +3134,7 @@ HTTP/1.1 200 OK | JSON Representation(s) | billing | | Additional Formats | None | -The billing sub-resource returns the current billing configuration and pricing plan for an different features, represented by a `billing` instance. +The billing sub-resource returns the current billing configuration and pricing plan for different features, represented by a `billing` instance. ```bash exampleRepresentation { @@ -3560,7 +3597,7 @@ HTTP/1.1 200 OK | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | +| HTTP Method(s) | [GET](#get), [DELETE](#delete) | | JSON Representation(s) | linkedusers | | Additional Formats | None | @@ -3718,6 +3755,16 @@ HTTP/1.1 200 OK +#### Delete Linked User + +``` +DELETE /customers/{customerId}/linkedusers/{linkeduserId}?removeUser=true +``` + +There are 2 kinds of user: Web User (which is a single user-login) and Linked User (which is an association between Web User and an Account). So you can have a user on multiple accounts - e.g an IT Technician who supports 3 schools with their own accounts may have a single Web User but then will have Linked Users across 3 separate accounts.
+With the above in mind, when you **DELETE** a Linked User you only delete that association rather than the Web User too. You can still link the existing Web User to a new account in this scenario if you wish. +However, if you'd like to fully remove a user, when you submit your Linked User delete, add in an additional query parameter of *removeUser* with a value of true: "removeUser" : true + ## Charging Plans | Resource Information | | From 51105995b469c2b13054fbbe6935f54080911d80 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Mon, 9 Oct 2023 15:15:59 +0100 Subject: [PATCH 09/15] formatting fixes wholesale --- docs/wholesale/api/v3.md | 872 ++++++++++++++++++++------------------- 1 file changed, 452 insertions(+), 420 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index ff78ae8..6307458 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -428,13 +428,10 @@ The differences between these account types can be found in the [Simwood Account - -| Method | Description | + +| Method | Description | | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | Get your current account type, and limitations Account type will be one of the following; developer, startup, virtual_interconnect, managed_interconnect | -| PUT | Upgrade or downgrade your account. This option is only available to customers of account_type developer or startup | -| :-- | *account_type* | -| :-- | *startup* upgrade to startup (if developer) | @@ -523,11 +520,12 @@ The current status of all invoices on your account is available through the API. -| Method | Description | + +| Method | Description | | :----- | :------------------------------------------------------------------------------------------------------------------------------------------- | | POST | Requests a report of Summary of account movements. If the optional from_date and to_date parameters are not specified will default to today. | -| :-- | *from_date* Start date of report (in form YYYY-MM-DD) | -| :-- | *to_date* End date of report (in form YYYY-MM-DD) | +| | *from_date* Start date of report (in form YYYY-MM-DD) | +| | *to_date* End date of report (in form YYYY-MM-DD) | @@ -594,21 +592,20 @@ The API provides tools for checking and protecting your pre-paid balance(s) -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Return balance of account.| + +| Method | Description | +| :----- | :------------------------- | +| GET | Return balance of account. | ```json -[ - { - "balance": "168.06100", - "currency": "GBP" - } -] +{ + "balance": "168.06100", + "currency": "GBP" +} ``` @@ -624,22 +621,23 @@ You can set an amount at which you will receive a notification (configured via t -| Method | Description | -| :----- | :---------------------------------------------------- | -| GET | Returns the current level of alert. | -| PUT | Sets the alert balance to the specified alert_balance | + + | Method | Description | + | :----- | :---------------------------------------------------- | + | GET | Returns the current level of alert. | + | PUT | Sets the alert balance to the specified alert_balance | ```json -[ - { - "account": ACCOUNT, - "alert_balance": 90 - } -] +{ + "account": ACCOUNT, + "alert_balance": 90 +} + + ``` @@ -660,19 +658,25 @@ You can set alerts based on the *available* balance (i.e. balance-locked balance -| Method | Description | -| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | -| PUT | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent. | -| :-- | *balance* The amount to be protected. | -| DELETE | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | + + | Method | Description | + | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | + | GET | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | + | PUT | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent. | + | | *balance* The amount to be protected. | + | DELETE | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | ```json -[{"account":ACCOUNT,"balance":10.4688,"locked":5,"available":5.4688}] +{ + "account":ACCOUNT, + "balance":10.4688, + "locked":5, + "available":5.4688 +} ``` @@ -699,9 +703,10 @@ Some account types have more than one available tariff or rate deck, these can b -| Method | Description| -| :----- |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck) | + + | Method | Description| + | :----- |:--------------------------------------------------------------------------------------------------------------------------------------------------- | + | GET | Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck) | @@ -711,20 +716,20 @@ Some account types have more than one available tariff or rate deck, these can b { "success": true, "data": [ - { - "description": "Legacy GBP Platinum", - "servicelevel": 1, - "quality": "Platinum", - "prefix": 999001, - "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Platinum.csv" - }, { - "description": "Legacy GBP Gold", - "servicelevel": 2, - "quality": "Gold", - "prefix": 999002, - "default": true, - "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Gold.csv" - } + { + "description": "Legacy GBP Platinum", + "servicelevel": 1, + "quality": "Platinum", + "prefix": 999001, + "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Platinum.csv" + }, { + "description": "Legacy GBP Gold", + "servicelevel": 2, + "quality": "Gold", + "prefix": 999002, + "default": true, + "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Gold.csv" + } ] } ``` @@ -741,11 +746,10 @@ Our latest termination rates are also always available in CSV and Excel (XLSX) f -| Method | Description | -| :----- | :---------------------------------------- | -| GET | Request the latest ratecard in CSV Format | - + | Method | Description | + | :-- | :---| + | GET | Request the latest ratecard in CSV Format | @@ -770,9 +774,10 @@ Effective: 2023-03-10 -| Method | Description | -| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge. | + + | Method | Description | + | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | GET | Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge. | @@ -850,16 +855,17 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon -| Method | Description | + +| Method | Description | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET / POST | Request an inbound or outbound summary report by {KEY} (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | +| GET / POST | Request an inbound or outbound summary report by KEY (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | | | *date_start* [Optional] specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | | | *limit* [Optional] specify limit of results to return, default 9999 | | | *sort* [Optional] Key to sort by | | | *filter* Array of "search_key" to "value" | - + | Key | Description | | :----- | :-------------------------------------------------- | @@ -904,10 +910,10 @@ Some notifications can now (as of v3.15) be received via Webhooks, for more info -| Method | Description | -| :----- | :-------------------------------------------- | -| GET | List available notifications on your account. | + | Method | Description | + | :----- | :-------------------------------------------- | + | GET | List available notifications on your account. | @@ -981,9 +987,10 @@ NB **SMS** notification requires credit balance, sent messages will be deducted ``` -| Method | Description | -| :----- | :------------------------------------------------------------------------ | -| GET | Shows limits in effect on an account including any Dynamic Channel Limits | + + | Method | Description | + | :----- | :------------------------------------------------------------------------ | + | GET | Shows limits in effect on an account including any Dynamic Channel Limits | @@ -991,22 +998,23 @@ NB **SMS** notification requires credit balance, sent messages will be deducted ```json { - "channel_allocation": 30, - "channel_allocation_global_numbers": 10, - "channel_allocation_adjustable": false, - "limit_concurrent_in": 10, - "limit_concurrent_out": 20, - "limit_concurrent_out_per_number": 10, - "limit_concurrent_out_international": 3, - "limit_concurrent_out_hotspot": 2, - "limit_rate_out": "10/1s", - "limit_rate_out_international": null, - "limit_rate_out_hotspot": "2/12h", - "dynamic": { - "balance": "15.52680", - "limit_concurrent_out": 3, - "limit_rate_out": "30/10s" -} } + "channel_allocation": 30, + "channel_allocation_global_numbers": 10, + "channel_allocation_adjustable": false, + "limit_concurrent_in": 10, + "limit_concurrent_out": 20, + "limit_concurrent_out_per_number": 10, + "limit_concurrent_out_international": 3, + "limit_concurrent_out_hotspot": 2, + "limit_rate_out": "10/1s", + "limit_rate_out_international": null, + "limit_rate_out_hotspot": "2/12h", + "dynamic": { + "balance": "15.52680", + "limit_concurrent_out": 3, + "limit/_rate_out": "30/10s" + } +} ``` @@ -1044,12 +1052,13 @@ Customers with a dedicated channel allocation can manage this allocation, splitt -| Method | Description | -| :----- | :----------------------------------------------------------------- | -| PUT | Update channel limits | -| | *limit_concurrent_in* inbound channel limit | -| | *limit_concurrent_out* outbound channel limit | -| | NB the above must, together, total the value of channel_allocation | + + | Method | Description | + | :----- | :----------------------------------------------------------------- | + | PUT | Update channel limits | + | | *limit_concurrent_in* inbound channel limit | + | | *limit_concurrent_out* outbound channel limit | + | | NB the above must, together, total the value of channel_allocation | @@ -1075,10 +1084,11 @@ Customers with a dedicated channel allocation can manage this allocation, splitt -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------------- | -| GET | Current channel utilisation | -| | NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below | + + | Method | Description | + | :----- | :---------------------------------------------------------------------------------------------------------------------- | + | GET | Current channel utilisation | + | | NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below | @@ -1342,6 +1352,7 @@ These rejections are notified using the notification endpoint you have configure + | Method | Description | | :----- | :----------------------------------------- | | GET | Get all available recently rejected calls. | @@ -1353,18 +1364,18 @@ These rejections are notified using the notification endpoint you have configure ```json { - "success": true, - "data": [ - { - "calldate": "2016-02-08 07:00:04", - "reason": "maxcost", - "from": "441632496000", - "to": "447700900123", - "message": "Call to 447700900123 will exceed 0.1 ( 0.25450 )", - "source_ip": "10.0.0.0", - "trunk": "9XXXXX-L001", - "notified": false - } + "success": true, + "data": [ + { + "calldate": "2016-02-08 07:00:04", + "reason": "maxcost", + "from": "441632496000", + "to": "447700900123", + "message": "Call to 447700900123 will exceed 0.1 ( 0.25450 )", + "source_ip": "10.0.0.0", + "trunk": "9XXXXX-L001", + "notified": false + } ] } ``` @@ -1380,10 +1391,10 @@ These rejections are notified using the notification endpoint you have configure -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------- | -| GET | As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli"). | + | Method | Description | + | :----- | :--------------------------------------------------------------------- | + | GET | As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli"). | @@ -1530,10 +1541,9 @@ As with your account you can also view realtime "in progress" information on a p -| Method | Description | -| :----- | :----------------------------------------------------------------------------- | -| GET | Provides information on the calls currently in progress on the specified TRUNK | - + | Method | Description | + | :----- | :-------------------------------------- | + | GET | Provides information on the calls currently in progress on the specified TRUNK | @@ -1635,7 +1645,12 @@ The ACL is specified in a JSON-encoded object as follows; This would be encoded in JSON as follows; ```json -{"allow":[441,442,443,448],"deny":[44870]} +{ + "allow": + [441,442,443,448], + "deny": + [44870] +} ``` @@ -2003,12 +2018,12 @@ An example (annotated) configuration is below, and the full list of options can ```json "rules": { - "mon__fri_0700__1700": [ - { - "dow": [1,2,3,4,5], - "time": ["0700","1700"] - } - ] + "mon__fri_0700__1700": [ + { + "dow": [1,2,3,4,5], + "time": ["0700","1700"] + } + ] }, ``` @@ -2018,16 +2033,16 @@ Rules define times of day that routing blocks (below) apply, outwith the rules g ```json "routing": { - "mon__fri_0700__1700": [ - [ - { - "type": "reg", - "user": "939998-FREDTEST", - "timeout": 30, - "sdes": "optional", - "opus": "default" - } - ], + "mon__fri_0700__1700": [ + [ + { + "type": "reg", + "user": "939998-FREDTEST", + "timeout": 30, + "sdes": "optional", + "opus": "default" + } + ], ``` This block will run during the *officehours* time block defined above (Mon-Fri 9am-5pm) @@ -2035,35 +2050,35 @@ and will call the SIP endpoint shown and the user on the registration proxy simu ```json [ - { - "type": "sip", - "endpoint": "%e164@pbx.mycompany.com", - "timeout": 30, - "sdes": "none", - "opus": "default" - } - ], - [ - { - "type": "pstn", - "number": "447405644486" - } + { + "type": "sip", + "endpoint": "%e164@pbx.mycompany.com", + "timeout": 30, + "sdes": "none", + "opus": "default" + } + ], + [ + { + "type": "pstn", + "number": "447405644486" + } ] -], + ], ``` After the timeout above (30s) we will try the PSTN number provided ```json - "default": [ - [ - { - "type": "pstn", - "timeout": 30, - "number": "447405644486", - "trunk": "939998-ALAUTHTEST" - } - ] + "default": [ + [ + { + "type": "pstn", + "timeout": 30, + "number": "447405644486", + "trunk": "939998-ALAUTHTEST" + } ] + ] }, ``` The *default* routing block will be used outwith the office hours specified above. @@ -2096,7 +2111,7 @@ The *meta* block contains arbitrary metadata that you want to associate with the The following options can be set on a per-number basis, they apply to the entire configuration at all times |Option|Parameters|Description|Default| -|:-|:-|:-|-| +|:--|:--|:--|:--| |*enabled*|[true\|false]|Allows number to be disabled [false] without removing the configuration.|Default [true]| |*block_payphone* | [true\|false] | Prevents inbound calls originating from payphones |Default [false]| |*acr*|[true\|false]|Apply ACR to this number. ACR Prevents calls originating from Withheld numbers reaching this number. Withheld callers will be diverted to a recorded announcement.|Default [false]| @@ -2112,7 +2127,7 @@ Please see https://simwood.com/rates for full information The ‘rules’ parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters; |Parameter|Format|Description| -|:-|:-|:-| +|:--|:--|:--| |*dow*|Array of values [1..7]|The days of week this rule is active (according to ISO 8601) e.g. **1 = Monday, 7 = Sunday.**
**NB if one day must still be an array. e.g. [3] not 3**| |*time*|Array [start,end]|Array of two values, denoting the start and end time this rule applies in 24h format (e.g. [0900,1700] would represent 9am - 5pm. The leading 0 can be omitted)| |day|Array of values [1..31]|The days of month this rule is active **NB if one day must still be an array. e.g. [25] not 25**| @@ -2121,37 +2136,50 @@ The ‘rules’ parameter in the JSON object should be an array of named objects **Example** -|Office Hours|Mon - Fri 0900-1700 | ```json
"rules":
"officehours": [
{
"dow": [1,2,3,4,5],
"time": [900,1700]
} ]
}
``` -| Weekends | -Sat/Sun (All Day) | +Office Hours - Mon - Fri 0900-1700 +```json +{ + "rules":{ + "officehours": [ + { + "dow": [1,2,3,4,5], + "time": [900,1700] + } + ] + } +} +``` + + +Weekends - Sat/Sun (All Day) ```json { -"rules": { + "rules": { "weekend": [ - { - "dow": [6,7] -} ] + { + "dow": [6,7] + } + ] + } } ``` -| Christmas / New Year | -Dec 25th -December 26th -January 1st -January 2nd -| -```bash +Christmas / New Year - Dec 25th , December 26th, January 1st, January 2nd + +```json "rules": { - "christmasholiday": [ -{ -"month": [12], - "day": [25,26] - },{ - "month": [1], - "day": [1,2] - } -] } -```| + "christmasholiday": [ + { + "month": [12], + "day": [25,26] + },{ + "month": [1], + "day": [1,2] + } + ] +} + +``` #### "routing" @@ -2166,49 +2194,41 @@ combination of both as shown below; **Ring A & B simultaneously, Then C** ```json "routing": { - "officehours": [ -[ -{ -BLOCK A }, -{ -BLOCK B -} ], -[ -{ -BLOCK C } -] ] + "officehours": [ + [ + { BLOCK A }, + { BLOCK B } + ],[ + { BLOCK C } + ] + ] } ``` **Ring A, B and C simultaneously** ```json "routing": { - "officehours": [ -[ -{ -BLOCK A }, -{ -BLOCK B -}, { -BLOCK C } -] ] + "officehours": [ + [ + { BLOCK A }, + { BLOCK B }, + { BLOCK C } + ] + ] } ``` **Ring A, then B, then C** ```json "routing": { - "officehours": [ -[ -{ -BLOCK A }, -], [ -{ -BLOCK B -} ], -[ -{ -BLOCK C } -] ] + "officehours": [ + [ + { BLOCK A }, + ],[ + { BLOCK B } + ],[ + { BLOCK C } + ] + ] } ``` @@ -2218,10 +2238,12 @@ The ‘meta’ parameter in the JSON object allows you to store your own arbitra The **key** parameter can be used to search for number(s) matching a specified key, the rest of the object is freeform up to a size limit of around 512 bytes. -|||| -|:-|-|-| -|key|String[40 chars]| A (non-unique) key for this number which you can use to search for matching numbers, most commonly customers use this to store a representation of their own customer account ID or username.
**NB Keys are treated as case-insensitive**| -| .. | .. |The rest of the **meta** parameter can be composed of ANY valid JSON structure, some example uses are given below.| + +|key|String[40 chars]| +|:--|:--| +| | A (non-unique) key for this number which you can use to search for matching numbers, most commonly customers use this to store a representation of their own customer account ID or username.
**NB Keys are treated as case-insensitive**| + +The rest of the **meta** parameter can be composed of ANY valid JSON structure, some example uses are given below. #### Examples @@ -2232,12 +2254,13 @@ The friendlyName is used to allow the customer to assign a memorable name to the The lastUpdated parameter is used to show when a number was last updated. @@ -2247,10 +2270,12 @@ The lastUpdated parameter is used to show when a number was last updated. @@ -2259,12 +2284,15 @@ The lastUpdated parameter is used to show when a number was last updated.
- - "meta": { - "key": "403010", - "friendlyName": "Main office number", - "lastUpdated": "2014-02-30 01:20:30" - } +```json +"meta": { + "key": "403010", + "friendlyName": "Main office number", + "lastUpdated": "2014-02-30 01:20:30" +} +```
- "meta": { - "key": "customer@example.com", - "pass": "secretWord" - } +```json +"meta": { + "key": "customer@example.com", + "pass": "secretWord" +} +```
- "meta": { - "notes": "This is reserved for Brian at - Example Corp and is not yet in use", +```json +{ + "meta": { + "notes": "This is reserved for Brian at + Example Corp and is not yet in use", "reserved": true - } - + } +} +```
@@ -2359,14 +2387,16 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th ```json { - "routing": { - "default": [ - [ - { - "type": "pstn", - "number": "447700900123" -} ] -] } + "routing": { + "default": [ + [ + { + "type": "pstn", + "number": "447700900123" + } + ] + ] + } } ``` @@ -2385,14 +2415,16 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th ```json { - "routing": { - "default": [ - [ - { - "type": "sip", - "endpoint": "%did@sip.mycompany.com" -} ] -] } + "routing": { + "default": [ + [ + { + "type": "sip", + "endpoint": "%did@sip.mycompany.com" + } + ] + ] + } } ``` @@ -2512,10 +2544,11 @@ Get the trunk currently associated with this number ```json { - "success": true, - "data": { - "trunk": "930XXX-ACMEPRODUCTS" -} } + "success": true, + "data": { + "trunk": "930XXX-ACMEPRODUCTS" + } +} ``` @@ -2548,11 +2581,11 @@ Request current inbound SMS configuration for the provided number ```json { - "success": true, - "data": { - "mode": "http", - "endpoint": "http://api.yourdomain.com/path/to/mtsms.cgi" - } + "success": true, + "data": { + "mode": "http", + "endpoint": "http://api.yourdomain.com/path/to/mtsms.cgi" + } } ``` @@ -2610,8 +2643,8 @@ SMS sent to this number.
```json { - "mode": "http_json", - "endpoint": "https://secure.api.yourdomain.com/path/to/mt" + "mode": "http_json", + "endpoint": "https://secure.api.yourdomain.com/path/to/mt" } ``` @@ -2623,7 +2656,7 @@ SMS sent to this number.
```json { - "success": true + "success": true } ``` @@ -2780,7 +2813,8 @@ be obtained from a GET request to /v3/numbers/{ACCOUNT}/validate/44330 "rh": "Simwood eSMS Limited", "date": "2010-07-20", "valid_cli": true -} } + } + } } ``` @@ -2809,13 +2843,14 @@ Lookup information on the number provided (number should in e.164 format) ```json { - "success": true, - "formatted": "+44(0)330 1223000", - "data": { - "code": "3301", - "prefix": "330122", - "rh": "Simwood eSMS Limited" -} } + "success": true, + "formatted": "+44(0)330 1223000", + "data": { + "code": "3301", + "prefix": "330122", + "rh": "Simwood eSMS Limited" + } +} ``` @@ -3050,40 +3085,36 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **JSON of example porting request** ```json { - - - "mbn": "01632960100", - "contact_email": "simwood.customer@example.com", - "lcp": "BT", - "lcp_cupid": "001", - "account_number": "NA1234B32", - "billing_postcode": "A12 3BC", - "type": "multi", - "lines": 1, - "channels": 30, - "customer": { - "title": "Mr", - "forename": "John", - "name": "Doe", - "loa_initial": "J", - "loa_surname": "Doe", - "premises": "123", - "thoroughfare": "Some Street", - "locality": "Sometown", - "postcode": "A12 3BC" - }, - "numbers": [ - {"number": "01632960100", "type": "mbn", "action": "port"}, - {"number": "01632960101", "type": "associated", "action": "port"}, - {"number": "01632960102", "type": "associated", "action": "port"}, - {"number": "01632960103", "type": "associated", "action": "port"}, - {"number": "01632960104", "type": "associated", "action": "port"}, - {"number": "01632960105", "type": "associated", "action": "port"}, - {"number": "01632960106", "type": "associated", "action": "port"}, - {"number": "01632960290", "type": "other", "action": "retain"} - - ] - + "mbn": "01632960100", + "contact_email": "simwood.customer@example.com", + "lcp": "BT", + "lcp_cupid": "001", + "account_number": "NA1234B32", + "billing_postcode": "A12 3BC", + "type": "multi", + "lines": 1, + "channels": 30, + "customer": { + "title": "Mr", + "forename": "John", + "name": "Doe", + "loa_initial": "J", + "loa_surname": "Doe", + "premises": "123", + "thoroughfare": "Some Street", + "locality": "Sometown", + "postcode": "A12 3BC" + }, + "numbers": [ + {"number": "01632960100", "type": "mbn", "action": "port"}, + {"number": "01632960101", "type": "associated", "action": "port"}, + {"number": "01632960102", "type": "associated", "action": "port"}, + {"number": "01632960103", "type": "associated", "action": "port"}, + {"number": "01632960104", "type": "associated", "action": "port"}, + {"number": "01632960105", "type": "associated", "action": "port"}, + {"number": "01632960106", "type": "associated", "action": "port"}, + {"number": "01632960290", "type": "other", "action": "retain"} + ] } ``` @@ -3092,19 +3123,19 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **Response** The response will be a JSON similar to the following; ```json - { - "success": true, - "ref": 12345, - "url": "/v3/porting/{ACCOUNT}/ports/12345" +{ + "success": true, + "ref": 12345, + "url": "/v3/porting/{ACCOUNT}/ports/12345" } ``` The *"ref"* value corresponds to the ticket that will be used to track the progress of the porting request. If any error(s) occurred whilst validating the configuration these will be returned as follows; ```json - { - "success": false, - "errors": [ "Message #1", "Message #2" ] +{ + "success": false, + "errors": [ "Message #1", "Message #2" ] } ``` @@ -3130,17 +3161,19 @@ Get a list of currently outstanding, or recently completed (within the last 90 d ```json { - "success": true, -"data": [ { - "ref": "54721" - "mbn": "01632960100", - "date": "2015-02-29", - "crd": "2015-03-14", - "status_code": "submitted_rh" - "status": "Submitted to RH" -}, { + "success": true, + "data": [ + { + "ref": "54721", + "mbn": "01632960100", + "date": "2015-02-29", + "crd": "2015-03-14", + "status_code": "submitted_rh", + "status": "Submitted to RH" + }, { ... } -] } + ] +} ``` @@ -3165,37 +3198,36 @@ The events element contains a chronological history of the port. { "success": true, "data": { - "mbn": "01632960100", - "status": "Porting Request Received", - "status_code": "rcvd", - "contact_email": "your.name@example.com", - "lcp": "BT", - "rh": "BT", - "account_number": "NA1234B32", - "billing_postcode": "A12 3BC", - "type": "multi", - "lines": "1", - "channels": "1", - "customer": { ... }, - "numbers": [ ... ], - "events": [ - { - "date": "2015-02-29 13:33:51", - "status_code": "submitted_lcp", - "status": "Submitted to LCP", - }, { - "date": "2015-02-29 14:23:51", - "status_code": "accepted", - "status": "Porting Request Accepted", - }, - { - "date": "2015-02-29 13:33:51", - "status_code": "rcvd", - "status": "Porting Request Received", - "info": "Order Submitted by API" - } - ] - } + "mbn": "01632960100", + "status": "Porting Request Received", + "status_code": "rcvd", + "contact_email": "your.name@example.com", + "lcp": "BT", + "rh": "BT", + "account_number": "NA1234B32", + "billing_postcode": "A12 3BC", + "type": "multi", + "lines": "1", + "channels": "1", + "customer": { ... }, + "numbers": [ ... ], + "events": [ + { + "date": "2015-02-29 13:33:51", + "status_code": "submitted_lcp", + "status": "Submitted to LCP", + },{ + "date": "2015-02-29 14:23:51", + "status_code": "accepted", + "status": "Porting Request Accepted", + },{ + "date": "2015-02-29 13:33:51", + "status_code": "rcvd", + "status": "Porting Request Received", + "info": "Order Submitted by API" + } + ] + } } @@ -3222,21 +3254,19 @@ Get list of LCP (Losing Communications Providers) we can port from and the corre ```json { - "success": true, - "cps": [ - { - "cpName": "BT", - "cupid": "1" - }, - { + "success": true, + "cps": [ + { + "cpName": "BT", + "cupid": "1" + },{ "cpName": "Telephony Services", "cupid": "93" - }, - { + },{ "cpName": "Gamma Telecom", "cupid": "31" -} ] - + } + ] } ``` @@ -3283,13 +3313,14 @@ Submit a new Mobile Number port. ```json { - "success": true, - "data": { - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_port": "2016-12-16", - "ref": 43001 -} } + "success": true, + "data": { + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_port": "2016-12-16", + "ref": 43001 + } +} ``` @@ -3317,21 +3348,20 @@ Get a list of currently outstanding, or recently completed mobile number ports ```json { - "success": true, - "data": [ - { - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_added": "2016-12-06", - "date_updated": "2016-12-06", - "date_port": "2016-12-08", - "status_code": "pending" - "status": "Pending" - "ref": 43001 - }, - { - ... - } + "success": true, + "data": [ + { + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_added": "2016-12-06", + "date_updated": "2016-12-06", + "date_port": "2016-12-08", + "status_code": "pending" + "status": "Pending" + "ref": 43001 + },{ + ... + } ] } ``` @@ -3354,17 +3384,16 @@ Get details of an MNP porting request ```json { "success": true, -"data": { - - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_added": "2016-12-06", - "date_updated": "2016-12-06", - "date_port": "2016-12-08", - "status_code": "pending" - "status": "Pending" - "ref": 43001 - } + "data": { + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_added": "2016-12-06", + "date_updated": "2016-12-06", + "date_port": "2016-12-08", + "status_code": "pending", + "status": "Pending", + "ref": 43001 + } } ``` @@ -3395,16 +3424,17 @@ Lists las secen days of inbound faxes (optionally filtered by NUMBER) { "success": true, "data": [ - { - "hash": "7e2bb7bb87300ff83c657b04b07b8261" - "time": "2015-02-30 12;34:56", - "originator": "07700900123", - "destination": "443301223000", - "station": "MYFAX", - "duration": 31, - "pages": 1, - "url": "/v3/..../7e2bb7bb87300ff83c657b04b07b8261.pdf" -} ] + { + "hash": "7e2bb7bb87300ff83c657b04b07b8261", + "time": "2015-02-30 12;34:56", + "originator": "07700900123", + "destination": "443301223000", + "station": "MYFAX", + "duration": 31, + "pages": 1, + "url": "/v3/..../7e2bb7bb87300ff83c657b04b07b8261.pdf" + } + ] } ``` @@ -3504,14 +3534,14 @@ If the extended parameter is included, additional information will be included i ```json { - "success":true, - "data":{ - "id":"1f40b0ac384cab838acf39a0e3e38bba", - "desc":"SMS - United Kingdom", - "parts":1, - "charge":0.02, - "currency":"GBP" - } + "success":true, + "data": { + "id":"1f40b0ac384cab838acf39a0e3e38bba", + "desc":"SMS - United Kingdom", + "parts":1, + "charge":0.02, + "currency":"GBP" + } } ``` @@ -3582,9 +3612,11 @@ The following placeholders can be used; If submission is successful, the fax will be queued immediately and response returned as an array containing the number and corresponding id of the submitted fax for each destination number; -``` -[{"number":"441632000123","id":"b902e8e46b91900af276f52995a3082e"}, -{"number":"447700900123","id":"71cea3179fdd13271a2ac14a366941f8"}] +```json +[ + {"number":"441632000123","id":"b902e8e46b91900af276f52995a3082e"}, + {"number":"447700900123","id":"71cea3179fdd13271a2ac14a366941f8"} +] ``` #### Fax Content Types @@ -3892,14 +3924,14 @@ Please note that SSLv3 and TLSv1 are not supported by this service. An example full message is shown below ```json { -"app": "sms_inbound", -"id": "si_422296075c882529362765a39aa75b19", -"data": { - "originator": "447700900321", - "destination": "447700900123", - "length": 12, - "message": "Hello World." -} + "app": "sms_inbound", + "id": "si_422296075c882529362765a39aa75b19", + "data": { + "originator": "447700900321", + "destination": "447700900123", + "length": 12, + "message": "Hello World." + } } ``` From de9e8b50918029d05a60e6596f3e62428c4a453e Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Mon, 9 Oct 2023 16:39:25 +0100 Subject: [PATCH 10/15] Formatting changes --- docs/direct/api/v1.md | 3098 ++++++++++++++++++++--------------------- 1 file changed, 1541 insertions(+), 1557 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index 040a4e6..c37727c 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -102,7 +102,7 @@ Finally, where supported, resources may be *removed* using the DELETE method. Pl #### Method Overloading -Not all HTTP libraries support the PUT and DELETE methods. However, it is possible to achieve the same outcome by using POST and including a `_method` query parameter in the request URL, with a value of either PUT or DELETE. For example, take the following DELETE request: +Not all HTTP libraries support the PUT and DELETE methods. However, it is possible to achieve the same outcome by using POST and including a `_method` query parameter in the request URL, with a value of either PUT or DELETE. For example, take the following DELETE Request ``` DELETE /customers/8425/numbers/44675 @@ -175,7 +175,7 @@ contain the following information: - + @@ -185,9 +185,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&pag -```bash -HTTP/1.1 200 OK - +```json { "totalItems": 21, "pageSize": 5, @@ -269,8 +267,7 @@ All dates and times are formatted according to the ISO 8601 profile. For example The customers resource is the starting point for most account-level operations. Each customer instance represents an account on the Sipcentric platform - it encapsulates a single company/PBX and all of its sub-resources. -```bash exampleRepresentation - +```json exampleRepresentation { "type": "customer", "id": "5", @@ -282,29 +279,29 @@ The customers resource is the starting point for most account-level operations. "lastName": "Test", "telephone": "07557000000", "email": "support@sipcentric.com", - "address1": "The Oaks", - "address2": "Ribbesford", - "city": "Bewdley", + "address1": "Test", + "address2": "Test 2", + "city": "Test 3", "postcode": "98999", "country": "US", "properties": {}, "enabled": true, "currency": "GBP", "links": { - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/5/outgoingcallerids", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints", - "preferences": "https://pbx.sipcentric.com/api/v1/customers/5/preferences", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/5/timeintervals", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/5/creditstatus", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/5/phonenumbers", - "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/5/bargegroups", - "callBundles": "https://pbx.sipcentric.com/api/v1/customers/5/callbundles", - "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/5/sounds", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/5/phonebook", - "calls": "https://pbx.sipcentric.com/api/v1/customers/5/calls", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", - "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/5/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/5/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/5/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/5/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/5/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/5/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/5/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/5/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/5/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/5/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" }, "partnerId": "1", "partnerCompany": "Nimvelo", @@ -313,7 +310,7 @@ The customers resource is the starting point for most account-level operations. ``` | Type: *customer* | | -| :----------------------------- | :--------------------------------------------------------------------------------------------- | +|:----------------------------- |:--------------------------------------------------------------------------------------------- | | **Property** | **Description** | | type
*required* | The resource type ("customer").
*String* | | id
*required* | The unique id ("5").
*String* | @@ -345,7 +342,7 @@ The customers resource is the starting point for most account-level operations. Lists all customer accounts to which the authenticating user has access. When authenticated as an extension user or a company admin, this will only return their own account. However, when authenticated as a reseller, all customer accounts owned by that reseller will be returned. - + ``` @@ -356,35 +353,33 @@ GET https://pbx.sipcentric.com/api/v1/customers -```bash - -HTTP/1.1 200 OK +```json { "totalItems": 1, "pageSize": 1, "page": 1, "items": [ - { - "type": "customer", - "id": "5", - "uri": "https://pbx.sipcentric.com/api/v1/customers/5", - "created": "2010-12-21T08:30:31Z", - "accountType": "BUSINESS", - "company": "Sipcentric Ltd.", - "firstName": "Fred", - "lastName": "Test", - "telephone": "07557000000", - "email": "support@sipcentric.com", - "address1": "The Oaks", - "address2": "Ribbesford", - "city": "Bewdley", - "postcode": "98999", - "country": "US", - "properties": {}, - "enabled": true, - "currency": "GBP", - "links": { + { + "type": "customer", + "id": "5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5", + "created": "2010-12-21T08:30:31Z", + "accountType": "BUSINESS", + "company": "Sipcentric Ltd.", + "firstName": "Fred", + "lastName": "Test", + "telephone": "07557000000", + "email": "support@sipcentric.com", + "address1": "Test", + "address2": "Test 2", + "city": "Test 3", + "postcode": "98999", + "country": "US", + "properties": {}, + "enabled": true, + "currency": "GBP", + "links": { "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/5/outgoingcallerids", "endpoints": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints", "preferences": "https://pbx.sipcentric.com/api/v1/customers/5/preferences", @@ -399,12 +394,12 @@ HTTP/1.1 200 OK "calls": "https://pbx.sipcentric.com/api/v1/customers/5/calls", "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" - }, - "partnerId": "1", - "partnerCompany": "Nimvelo", - "userEmailUpdatable": false - } -] + }, + "partnerId": "1", + "partnerCompany": "Nimvelo", + "userEmailUpdatable": false + } + ] } ``` @@ -417,7 +412,7 @@ HTTP/1.1 200 OK Returns a single customer instance, providing the user is allowed access to that customer. In the case of company admin/extension users, the special ID of `me` can also be used to return the account to which the current user belongs. - + ``` @@ -428,42 +423,41 @@ GET https://pbx.sipcentric.com/api/v1/customers/me -```bash -HTTP/1.1 200 OK +```json { - "type": "customer", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-01-24T13:00:35Z", - "accountType": "BUSINESS", - "company": "Fred Test", - "firstName": "Fred", - "lastName": "Muteesa", - "email": "Test@simwood.com", - "country": "GB", - "properties": {}, - "enabled": true, - "currency": "GBP", - "links": { - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", - "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" - }, - "partnerId": "41", - "partnerCompany": "Ops Team Test", - "userEmailUpdatable": false + "type": "customer", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-01-24T13:00:35Z", + "accountType": "BUSINESS", + "company": "Fred Test", + "firstName": "Fred", + "lastName": "Muteesa", + "email": "Test@simwood.com", + "country": "GB", + "properties": {}, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + }, + "partnerId": "41", + "partnerCompany": "Ops Team Test", + "userEmailUpdatable": false } ``` @@ -476,79 +470,79 @@ HTTP/1.1 200 OK To create a new customer, a representation of a `customer` must be POSTed to the `customers` resource. The newly created `Customer` ID will then be included in the body of the response. - + -```bash +```json POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook { -"type": "customer", -"telephone":"03301229999", -"accountType": "BUSINESS", -"company": "Simwood", -"firstName": "Fred", -"lastName": "Test API", -"email": "Test@Test.com", -"address1": "Simwood House", -"address2": "Cube m4 Business Park", -"city": "Bristol", -"postcode": "BS16 1FX", -"country": "GB", -"properties": { -"customid" : "abc123" -}, -"enabled": true, -"currency": "GBP", -"userEmailUpdatable": false + "type": "customer", + "telephone":"03301229999", + "accountType": "BUSINESS", + "company": "Simwood", + "firstName": "Fred", + "lastName": "Test API", + "email": "Test@Test.com", + "address1": "Simwood House", + "address2": "Cube m4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": { + "customid": "abc123" + }, + "enabled": true, + "currency": "GBP", + "userEmailUpdatable": false } ``` -```bash +```json HTTP/1.1 201 Created { - "type": "customer", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-24T11:18:36Z", - "accountType": "BUSINESS", - "company": "Simwood", - "firstName": "Fred", - "lastName": "Test API", - "telephone": "03301229999", - "email": "Test@Test.com", - "address1": "Simwood House", - "address2": "Cube m4 Business Park", - "city": "Bristol", - "postcode": "BS16 1FX", - "country": "GB", - "properties": { - "customid": "abc123" - }, - "enabled": true, - "currency": "GBP", - "links": { - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", - "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" - }, - "userEmailUpdatable": false + "type": "customer", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Simwood", + "firstName": "Fred", + "lastName": "Test API", + "telephone": "03301229999", + "email": "Test@Test.com", + "address1": "Simwood House", + "address2": "Cube m4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": { + "customid": "abc123" + }, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + }, + "userEmailUpdatable": false } ``` @@ -571,19 +565,19 @@ HTTP/1.1 201 Created The phonebook sub-resource allows users to read and organize an account's shared phone book entries. Each entry is represented by a `phonebookentry`. -```bash exampleRepresentation - { - "type": "phonebookentry", - "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-03T17:21:14Z", - "name": "Test Contact", - "phoneNumber": "256754999999", - "email": "email@Test.com", - "speedDial": 123, - "priority": 0 - } +```json +{ + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@Test.com", + "speedDial": 123, + "priority": 0 +} ``` | Type: *phonebookentry* | | @@ -608,7 +602,7 @@ The phonebook sub-resource allows users to read and organize an account's shared Return a list of every `phonebookentry` on the customer account. - + ``` @@ -618,38 +612,38 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=1 -```bash +```json HTTP/1.1 200 OK { - "totalItems": 5, - "pageSize": 2, - "page": 1, - "items": [ - { - "type": "phonebookentry", - "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-03T17:21:14Z", - "name": "Test Contact", - "phoneNumber": "256754999999", - "email": "email@Test.com", - "speedDial": 123, - "priority": -50 - }, - { - "type": "phonebookentry", - "id": "84039", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-04T09:13:08Z", - "name": "Fred Test 3", - "phoneNumber": "256761303030", - "priority": 0 - } - ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" + "totalItems": 5, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@Test.com", + "speedDial": 123, + "priority": -50 + }, + { + "type": "phonebookentry", + "id": "84039", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-04T09:13:08Z", + "name": "Fred Test 3", + "phoneNumber": "256761303030", + "priority": 0 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" } ``` @@ -662,7 +656,7 @@ HTTP/1.1 200 OK Returns the instance of an individual `phonebookentry`. - + ``` @@ -673,20 +667,20 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773 -```bash +```json HTTP/1.1 200 OK { - "type": "phonebookentry", - "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-03T17:21:14Z", - "name": "Test Contact", - "phoneNumber": "256754999999", - "email": "email@Test.com", - "speedDial": 123, - "priority": -50 + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@Test.com", + "speedDial": 123, + "priority": -50 } ``` @@ -700,35 +694,35 @@ HTTP/1.1 200 OK To create a new phone book entry, a representation of a `phonebookentry` must be POSTed to the `phonebook` resource. The newly created `phonebookentry` representation will then be included in the body of the response. - + -```bash +```json POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook { - "type" : "phonebookentry", - "name" : "Fred Mobile", - "phoneNumber" : "07902000000", - "priority" : 0 + "type": "phonebookentry", + "name": "Fred Mobile", + "phoneNumber": "07902000000", + "priority": 0 } ``` -```bash +```json HTTP/1.1 201 Created { - "type": "phonebookentry", - "id": "84072", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84072", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-05T10:30:15Z", - "name": "Fred Mobile", - "phoneNumber": "07902000000", - "priority": 0 + "type": "phonebookentry", + "id": "84072", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84072", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:30:15Z", + "name": "Fred Mobile", + "phoneNumber": "07902000000", + "priority": 0 } ``` @@ -741,32 +735,32 @@ HTTP/1.1 201 Created To update a `phonebookentry`, a representation of the updated `phonebookentry` must be PUT to that instance resource. The updated `phonebookentry` representation will then be returned in the body of the response. - + -```bash +```json PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 { - "type" : "phonebookentry", - "name" : "Fred Mobile", - "phoneNumber" : "07825000000", - "speedDial" : 12 + "type": "phonebookentry", + "name": "Fred Mobile", + "phoneNumber": "07825000000", + "speedDial": 12 } ``` -```bash +```json HTTP/1.1 200 OK { "type": "phonebookentry", "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716", - "created" : "2014-03-10T13:38:00.000+0000", + "created": "2014-03-10T13:38:00.000+0000", "name": "Fred Mobile", "phoneNumber": "07825000000", "speedDial": 12 @@ -783,7 +777,7 @@ HTTP/1.1 200 OK To delete a `phonebookentry`, a DELETE request must be made to the instance resource. - + ``` DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 @@ -792,7 +786,7 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 -```bash +```json HTTP/1.1 204 No Content ``` @@ -813,21 +807,21 @@ HTTP/1.1 204 No Content The SMS sub-resource contains a record of every SMS message sent or received on the account, each item represented by a single `smsmessage`. -```bash +```json { - "type": "smsmessage", - "id": "31408968", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-03T17:27:59Z", - "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hello M. confirm receipt of this sms", - "sendStatus": "SENT", - "deliveryStatus": 1, - "cost": 0.080, - "creditsUsed": 1 + "type": "smsmessage", + "id": "31408968", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hello M. confirm receipt of this sms", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 } ``` @@ -854,7 +848,7 @@ The SMS sub-resource contains a record of every SMS message sent or received on Returns a list of every `smsmessage` on the account. - + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1 @@ -863,45 +857,44 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1 -```bash +```json HTTP/1.1 200 OK { - "totalItems": 3, - "pageSize": 2, - "page": 1, - "items": [ - { - "type": "smsmessage", - "id": "31414341", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-05T10:48:45Z", - "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hey, this API is awesome!", - "sendStatus": "SENT", - "deliveryStatus": 1, - "cost": 0.080, - "creditsUsed": 1 - }, - { - "type": "smsmessage", - "id": "31414338", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414338", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-05T10:45:07Z", - "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "second check on you", - "sendStatus": "SENT", - "deliveryStatus": 1, - "cost": 0.080, - "creditsUsed": 1 - } - ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" + "totalItems": 3, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "smsmessage", + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:48:45Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hey, this API is awesome!", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 + },{ + "type": "smsmessage", + "id": "31414338", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414338", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-05T10:45:07Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "second check on you", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" } ``` @@ -914,7 +907,7 @@ HTTP/1.1 200 OK Returns the instance of a specific `smsmessage`. - + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 @@ -923,23 +916,23 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 -```bash +```json HTTP/1.1 200 OK { - "type": "smsmessage", - "id": "31408968", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-03T17:27:59Z", - "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hello M. confirm receipt of this sms", - "sendStatus": "SENT", - "deliveryStatus": 1, - "cost": 0.080, - "creditsUsed": 1 + "type": "smsmessage", + "id": "31408968", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "02031371636", + "to": "07902000000", + "body": "Hello M. confirm receipt of this sms", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 } ``` @@ -953,9 +946,9 @@ To send a new SMS, simply POST a representation of a new `smsmessage` to the lis **NB** the From number has to be a number configured in your account. - + -```bash +```json POST https://pbx.sipcentric.com/api/v1/customers/25/sms { @@ -969,21 +962,21 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/sms -```bash +```json HTTP/1.1 201 Created { - "type": "smsmessage", - "id": "31414341", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "direction": "OUT", - "from": "07902000000", - "to": "01212854400", - "body": "Hey, this API is awesome!", - "sendStatus": "SENT", - "cost": 0.080, - "creditsUsed": 1 + "type": "smsmessage", + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "direction": "OUT", + "from": "07902000000", + "to": "01212854400", + "body": "Hey, this API is awesome!", + "sendStatus": "SENT", + "cost": 0.080, + "creditsUsed": 1 } ``` @@ -1010,30 +1003,30 @@ The scope of a call can be: - External - to/from an external number on the PSTN. -```bash - { - "type": "call", - "id": "209925287", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/209925287", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-04-05T12:59:05Z", - "scope": "EXTERNAL", - "direction": "OUT", - "from": "Fred Muteesa <100>", - "to": "01912058750", - "callerId": "02031371636", - "callStarted": "2023-04-05T12:58:55Z", - "outcome": "ANSWERED", - "duration": 7, - "cost": 0.010, - "callId": "366e05e5-1680699535.1182575", - "linkedId": "366e05e5-1680699535.1182575", - "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", - "final": true, - "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=366e05e5-1680699535.1182575" - }, - } +```json +{ + "type": "call", + "id": "209925287", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/209925287", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-04-05T12:59:05Z", + "scope": "EXTERNAL", + "direction": "OUT", + "from": "Fred Muteesa <100>", + "to": "01912058750", + "callerId": "02031371636", + "callStarted": "2023-04-05T12:58:55Z", + "outcome": "ANSWERED", + "duration": 7, + "cost": 0.010, + "callId": "366e05e5-1680699535.1182575", + "linkedId": "366e05e5-1680699535.1182575", + "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", + "final": true, + "links": { + "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=366e05e5-1680699535.1182575" + }, +} ``` | Type: *call* | | @@ -1079,7 +1072,7 @@ Making a GET request to the list resource will return a history of the calls mad - + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1 @@ -1088,7 +1081,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/calls?createdAfter=2014-03-10 -```bash +```json HTTP/1.1 200 OK { @@ -1101,7 +1094,7 @@ HTTP/1.1 200 OK "id": "7592432", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592432", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:47:05.000+0000", + "created": "2014-03-10T13:47:05.000+0000", "scope": "EXTERNAL", "direction": "IN", "from": "07557000000", @@ -1115,12 +1108,12 @@ HTTP/1.1 200 OK "links": { "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723" } - }, { + },{ "type": "call", "id": "7592434", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592434", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "scope": "EXTERNAL", "direction": "OUT", "from": "Greg Sanderson <103>", @@ -1134,7 +1127,8 @@ HTTP/1.1 200 OK "links": { "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1401721105.2847099" } - } ], + } + ], "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2" } ``` @@ -1148,7 +1142,7 @@ HTTP/1.1 200 OK To originate a new call, you should POST a new `call` representation containing the properties shown below, to the calls list resource. - + ``` @@ -1165,7 +1159,7 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/calls -```bash +```json HTTP/1.1 200 OK ``` @@ -1181,7 +1175,7 @@ To check the current status of an endpoint, run the above - dndActive is a boole NB: Regardless of how many devices are connected to an endpoint, if Do Not Disturb (dnd) is set, then no calls will be presented to the endpoint. - + ``` @@ -1191,7 +1185,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus -```bash +```json { "type": "phonestatus", "id": "94", @@ -1209,7 +1203,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus To change the current status of an endpoint, please use a PUT as per the below. - + ``` @@ -1223,7 +1217,7 @@ PUT https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus -```bash +```json HTTP/1.1 200 OK ``` @@ -1290,7 +1284,7 @@ Returns all sounds, optionally filtered by the following query parameters: | type | String | Include only a specific type of sound file (prompt/music) | - + ``` @@ -1300,31 +1294,33 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=1 -```bash +```json HTTP/1.1 200 OK { - "totalItems" : 6, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "prompt", - "id": "1046", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:38:00.0000+0000", - "name" : "thank-you-for-calling", - "size" : 129612 - }, { - "type" : "prompt", - "id": "1035", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.0000+0000", - "name" : "calls-may-be-recorded", - "size" : 69426 - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" + "totalItems": 6, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "prompt", + "id": "1046", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:38:00.0000+0000", + "name": "thank-you-for-calling", + "size": 129612 + },{ + "type": "prompt", + "id": "1035", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:37:00.0000+0000", + "name": "calls-may-be-recorded", + "size": 69426 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" } ``` @@ -1337,7 +1333,7 @@ HTTP/1.1 200 OK Returns the instance of a specific sound file. - + ``` @@ -1347,16 +1343,16 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035 -```bash +```json HTTP/1.1 200 OK { - "type" : "prompt", + "type": "prompt", "id": "1035", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", - "created" : "2014-03-10T13:37:00.0000+0000", - "name" : "calls-may-be-recorded", - "size" : 69426 + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", + "created": "2014-03-10T13:37:00.0000+0000", + "name": "calls-may-be-recorded", + "size": 69426 } ``` @@ -1383,13 +1379,13 @@ See [Response Formats](#response-formats) for more information. The recordings sub-resource provides a way to retrieve and manage the call recordings which are currently stored on an account. Each `recording` representation contains a set of properties which allow for easy indexing/searching based on the local endpoint, remote party ID, time of recording etc. -```bash exampleRepresentation +```json exampleRepresentation { "type": "recording", "id": "1358371", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "direction": "IN", "partyId": "106", "started": "2014-05-14T15:41:25.000+0000", @@ -1431,7 +1427,7 @@ Returns a list of recordings, optionally filtered by the following query paramet | linkedId | String | Include only recordings relating to calls with the same linked ID. | - + ``` @@ -1441,42 +1437,43 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=1 -```bash +```json HTTP/1.1 200 OK { - "totalItems" : 5788, - "pageSize" : 2, - "page" : 1, - "items" : [ + "totalItems": 5788, + "pageSize": 2, + "page": 1, + "items": [ { - "type" : "recording", + "type": "recording", "id": "1358372", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T14:09:00.0000+0000", - "direction" : "OUT", - "partyId" : "07557000000", - "started" : "2014-03-10T14:07:00.0000+0000", - "size" : 97365, - "callId" : "ast01-1401721105.2847099", - "linkedId" : "ast01-1401721105.2847099", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928" - }, { - "type" : "recording", + "created": "2014-03-10T14:09:00.0000+0000", + "direction": "OUT", + "partyId": "07557000000", + "started": "2014-03-10T14:07:00.0000+0000", + "size": 97365, + "callId": "ast01-1401721105.2847099", + "linkedId": "ast01-1401721105.2847099", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928" + },{ + "type": "recording", "id": "1358371", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:42:00.0000+0000", - "direction" : "IN", - "partyId" : "07557000000", - "started" : "2014-03-10T13:37:00.0000+0000", - "size" : 9615, - "callId" : "ast01-1400082083.1542464", - "linkedId" : "ast01-1400082083.1542464", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=2" + "created": "2014-03-10T13:42:00.0000+0000", + "direction": "IN", + "partyId": "07557000000", + "started": "2014-03-10T13:37:00.0000+0000", + "size": 9615, + "callId": "ast01-1400082083.1542464", + "linkedId": "ast01-1400082083.1542464", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=2" } ``` @@ -1490,7 +1487,7 @@ HTTP/1.1 200 OK Fetches the instance of a specific recording. - + ``` @@ -1500,7 +1497,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371 -```bash +```json HTTP/1.1 200 OK { @@ -1508,14 +1505,14 @@ HTTP/1.1 200 OK "id": "1358371", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:42:00.0000+0000", - "direction" : "IN", - "partyId" : "07557000000", - "started" : "2014-03-10T13:37:00.0000+0000", - "size" : 9615, - "callId" : "ast01-1400082083.1542464", - "linkedId" : "ast01-1400082083.1542464", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "created": "2014-03-10T13:42:00.0000+0000", + "direction": "IN", + "partyId": "07557000000", + "started": "2014-03-10T13:37:00.0000+0000", + "size": 9615, + "callId": "ast01-1400082083.1542464", + "linkedId": "ast01-1400082083.1542464", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" } ``` @@ -1542,36 +1539,38 @@ See [Response Formats](#response-formats) for more information. A time interval (`timeinterval`) defines the single or set of time periods which together, constitute a recurring weekly/yearly event or work pattern - for example, "Out of Hours", "Public Holidays" or "My Cat's Birthday". Time intervals are used for matching against when defining time-based routing or access rules elsewhere on the system. -```bash exampleRepresentation +```json exampleRepresentation { "type": "timeinterval", "id": "431", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "12:15", - "endTime" : "13:14" - } ] + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "TUE", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "WED", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "THU", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "FRI", + "startTime": "12:15", + "endTime": "13:14" + } + ] } ``` @@ -1600,7 +1599,7 @@ A time interval (`timeinterval`) defines the single or set of time periods which Returns a list of previously defined time intervals on an account. - + ``` @@ -1610,58 +1609,64 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page -```bash +```json HTTP/1.1 200 OK { - "totalItems" : 5, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "timeinterval", - "id": "32", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "name" : "Christmas Day", - "repeat" : "YEARLY", - "includedTimes" : [ { - "month" : "DEC", - "dayOfMonth" : 25, - "startTime" : "00:00", - "endTime" : "23:59" - } ] - }, { - "type" : "timeinterval", - "id": "8675", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:27:00.000+0000", - "name" : "Office Hours", - "repeat" : "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "09:00", - "endTime" : "16:59" - } ] - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" + "totalItems": 5, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "timeinterval", + "id": "32", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:37:00.000+0000", + "name": "Christmas Day", + "repeat": "YEARLY", + "includedTimes": [ + { + "month": "DEC", + "dayOfMonth": 25, + "startTime": "00:00", + "endTime": "23:59" + } + ] + },{ + "type": "timeinterval", + "id": "8675", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:27:00.000+0000", + "name": "Office Hours", + "repeat": "WEEKLY", + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "TUE", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "WED", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "THU", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "FRI", + "startTime": "09:00", + "endTime": "16:59" + } + ] + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" } ``` @@ -1675,7 +1680,7 @@ HTTP/1.1 200 OK Returns the instance of a specific time interval. - + ``` @@ -1686,38 +1691,40 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431 -```bash +```json HTTP/1.1 200 OK { "type": "timeinterval", - "id": "431", + "id": "431", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "12:15", - "endTime" : "13:14" - } ] + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "TUE", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "WED", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "THU", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "FRI", + "startTime": "12:15", + "endTime": "13:14" + } + ] } ``` @@ -1861,7 +1868,7 @@ The properties of each endpoint type are listed below. `GET /customers/{customerId}/endpoints` - + ``` @@ -1871,7 +1878,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=2&page=1 -```bash +```json HTTP/1.1 200 OK { @@ -1879,12 +1886,12 @@ HTTP/1.1 200 OK "pageSize": 2, "page": 1, "items": [ - { + { "type": "ivr", "id": "83066", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:38:00.000+0000", + "created": "2014-03-10T13:38:00.000+0000", "shortNumber": "001", "name": "Main IVR", "timeout": 4 @@ -1894,14 +1901,14 @@ HTTP/1.1 200 OK "id": "101", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "shortNumber" : "102", - "name" : "John Simmonds", - "email" : "john@sipcentric.com", - "timeout" : 30, - "callWaiting" : true, - "callRecording" : "ALWAYS", - "voicemailEnabled" : true + "created": "2014-03-10T13:37:00.000+0000", + "shortNumber": "102", + "name": "John Simmonds", + "email": "john@sipcentric.com", + "timeout": 30, + "callWaiting": true, + "callRecording": "ALWAYS", + "voicemailEnabled": true } ], "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=1&page=2" @@ -1916,7 +1923,7 @@ HTTP/1.1 200 OK `GET /customers/{customerId}/endpoints/{endpointID}` - + ``` @@ -1926,7 +1933,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101 -```bash +```json HTTP/1.1 200 OK { @@ -1934,17 +1941,17 @@ HTTP/1.1 200 OK "id": "101", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "shortNumber" : "102", - "name" : "John Simmonds", - "email" : "john@sipcentric.com", - "timeout" : 30, - "callWaiting" : true, - "callRecording" : "ALWAYS", - "voicemailEnabled" : true, - "links" : { - "sip" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/sip", - "voicemail" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/voicemail" + "created": "2014-03-10T13:37:00.000+0000", + "shortNumber": "102", + "name": "John Simmonds", + "email": "john@sipcentric.com", + "timeout": 30, + "callWaiting": true, + "callRecording": "ALWAYS", + "voicemailEnabled": true, + "links": { + "sip": "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/sip", + "voicemail": "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/voicemail" } } ``` @@ -1958,7 +1965,7 @@ HTTP/1.1 200 OK you might want to get all extensions or all ivrs that are on the account. In this case you send a GET request with a type parameter as shown below. - + ``` GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone @@ -1967,63 +1974,63 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone -```bash +```json { - "totalItems": 2, - "pageSize": 20, - "page": 1, - "items": [ - { - "type": "phone", - "id": "83069", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-01-24T17:12:05Z", - "shortNumber": "100", - "name": "Fred Muteesa", - "timeout": 30, - "callWaiting": false, - "callRecording": "OFF", - "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/49610", - "voicemailSettings": { - "autoAnswer": false, - "pin": "0000", - "playEnvelope": false, - "playCallerId": false, - "allowReview": false - }, - "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/phonestatus" - } - }, - { - "type": "phone", - "id": "89937", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-15T19:43:10Z", - "shortNumber": "102", - "name": "Fred", - "timeout": 30, - "callWaiting": false, - "callRecording": "OFF", - "voicemailSettings": { - "autoAnswer": false, - "pin": "0000", - "playEnvelope": false, - "playCallerId": false, - "allowReview": false - }, - "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" - } - } - ] + "totalItems": 2, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "phone", + "id": "83069", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-01-24T17:12:05Z", + "shortNumber": "100", + "name": "Fred Muteesa", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/49610", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/phonestatus" + } + }, + { + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-15T19:43:10Z", + "shortNumber": "102", + "name": "Fred", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + } + } + ] } ``` @@ -2038,18 +2045,19 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone Depending on what property of the end point you want to update, you will need to send a PUT request to the following resrouce. You have to know the endpointID and the endpoint type. Depending on the endpoint type you are updating, some fields are required in the body, hence if you miss difinition of one of the parameters, your request will fail. In the example below I am updating the name of the IVR, but the rest of the fields I have included must be provided for the request to work. - + -``` +```json PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 -Json body -{"type":"ivr", -"id":"83066", -"name":"Fred-lab-ivr2", -"timeout":5, -"shortNumber":500 + +{ + "type":"ivr", + "id":"83066", + "name":"Fred-lab-ivr2", + "timeout":5, + "shortNumber":500 } ``` @@ -2057,7 +2065,7 @@ Json body -```bash +```json HTTP/1.1 200 OK { @@ -2082,47 +2090,52 @@ To add an extention or phone type endpoint to an account, you need to send a POS - + -``` +```json POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints -Body -{"callRecording":"OFF","timeout":30,"name":"Fred","shortNumber":"102","type":"phone"} +{ + "callRecording":"OFF", + "timeout":30, + "name":"Fred", + "shortNumber":"102", + "type":"phone" +} ``` -```bash +```json HTTP/1.1 200 OK { - "type": "phone", - "id": "89937", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-15T19:43:10Z", - "shortNumber": "102", - "name": "Fred", - "timeout": 30, - "callWaiting": false, - "callRecording": "OFF", - "voicemailSettings": { - "autoAnswer": false, - "pin": "0000", - "playEnvelope": false, - "playCallerId": false, - "allowReview": false - }, - "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" - } + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-15T19:43:10Z", + "shortNumber": "102", + "name": "Fred", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + } } ``` @@ -2159,31 +2172,33 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 Phone numbers provide a route into the system from outside - they can support calls and optionally SMS messages, where available. Each inbound number is represented by a `did`. -```bash exampleRepresentation +```json exampleRepresentation { - "type" : "did", + "type": "did", "id": "50", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "support@sipcentric.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false, - "routingRules" : [ { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - } ] + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "support@sipcentric.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false, + "routingRules": [ + { + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + } + ] } ``` @@ -2216,7 +2231,7 @@ Phone numbers provide a route into the system from outside - they can support ca Returns a list of all phone numbers on a customer account. - + ``` @@ -2226,52 +2241,56 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page= -```bash +```json HTTP/1.1 200 OK { - "totalItems" : 15, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "did", - "id": "47", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "Main", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@Fredbloggs.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false - }, { - "type" : "did", - "id": "50", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854411", - "identifier" : "", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "support@sipcentric.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false, - "routingRules" : [ { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - } ] - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" + "totalItems": 15, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "did", + "id": "47", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "Main", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "contact@Fredbloggs.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false + },{ + "type": "did", + "id": "50", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "identifier": "", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "support@sipcentric.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false, + "routingRules": [ + { + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + } + ] + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" } ``` @@ -2284,7 +2303,7 @@ HTTP/1.1 200 OK Retrieves the instance of a specific phone number. - + ``` @@ -2294,22 +2313,22 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47 -```bash +```json HTTP/1.1 200 OK { - "type" : "did", + "type": "did", "id": "47", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "Main", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@Fredbloggs.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "Main", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "contact@Fredbloggs.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false } ``` @@ -2323,13 +2342,13 @@ To add an availablenumber to a customer account please use a POST as per the bel NB: This number should be available in the simwood inventory. you can check Available numbers api , to see available numbers. - + ``` POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers - { +{ "createFrom":"4-44-113-4037921", "type":"did" } @@ -2338,22 +2357,22 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers -```bash +```json HTTP/1.1 200 OK { - "type": "did", - "id": "94854", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-12T14:11:06Z", - "number": "01134037921", - "formatted": "0113 403 7921", - "smsCapable": false, - "faxEnabled": false, - "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" - } + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + } } ``` @@ -2370,33 +2389,33 @@ To link a phonenumber in a customer's account to an extension inside the custome NB: This phone number should already be added to the account. Please see , adding Phone numbers. - + -```bash +```json PUT https://pbx.sipcentric.com/api/v1/customers/{customerId}/phonenumbers/{phonenumberId}/ -Body { -"type": "did", -"id": "73224", -"uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}", -"parent": "https://pbx.sipcentric.com/api/v1/customers/25", -"created": "2022-01-06T11:12:46Z", -"number": "01134031453", -"formatted": "0113 403 1453", -"smsCapable": false, -"faxEnabled": false, -"links": { -"routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}/routingrules" -}, -"destination":"89937" +{ + "type": "did", + "id": "73224", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2022-01-06T11:12:46Z", + "number": "01134031453", + "formatted": "0113 403 1453", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}/routingrules" + }, + "destination":"89937" } ``` -```bash +```json HTTP/1.1 200 OK { @@ -2428,10 +2447,10 @@ To un-link or remove the link between a phonenumber and an extension, you need t - + -```bash +```json PUT https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 Body @@ -2454,23 +2473,23 @@ Body -```bash +```json HTTP/1.1 200 OK { - "type": "did", - "id": "94854", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-05-12T14:11:06Z", - "number": "01134037921", - "formatted": "0113 403 7921", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", - "smsCapable": false, - "faxEnabled": false, - "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" - } + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + } } ``` @@ -2486,7 +2505,6 @@ To delete a number from an accouont, a DELETE request must be made to the instan Example ``` DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 - ``` @@ -2505,7 +2523,7 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 The Available Numbers sub-resource returns a list of available numbers that can be added to a customer account, represented by a `availablenumber` instance. After listing the available numbers you can add a number to your account see. -```bash exampleRepresentation +```json exampleRepresentation { "type": "availablenumber", "id": "4-44-113-4037921", @@ -2539,7 +2557,7 @@ The Available Numbers sub-resource returns a list of available numbers that can - + ``` @@ -2549,34 +2567,33 @@ GET https://pbx.sipcentric.com/api/v1/availablenumbers?areaCode=113&country=44&p -```bash +```json HTTP/1.1 200 OK { "totalItems": 21, - "pageSize": 100, - "page": 1, - "items": [ - { - "type": "availablenumber", - "id": "4-44-113-4037921", - "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", - "country": "44", - "areaCode": "113", - "number": "4037921", - "formatted": "0113 403 7921" - }, - { - "type": "availablenumber", - "id": "4-44-113-4037924", - "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037924", - "country": "44", - "areaCode": "113", - "number": "4037924", - "formatted": "0113 403 7924" - }, - ...... - ] + "pageSize": 100, + "page": 1, + "items": [ + { + "type": "availablenumber", + "id": "4-44-113-4037921", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", + "country": "44", + "areaCode": "113", + "number": "4037921", + "formatted": "0113 403 7921" + },{ + "type": "availablenumber", + "id": "4-44-113-4037924", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037924", + "country": "44", + "areaCode": "113", + "number": "4037924", + "formatted": "0113 403 7924" + }, + ...... + ] } ``` @@ -2587,7 +2604,7 @@ HTTP/1.1 200 OK `GET /availablenumber/{availablenumberId}` - + ``` @@ -2597,7 +2614,7 @@ GET https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921 -```bash +```json HTTP/1.1 200 OK { @@ -2629,13 +2646,13 @@ HTTP/1.1 200 OK Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. -```bash exampleRepresentation +```json exampleRepresentation { "type": "outgoingcallerid", "id": "114", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "number": "07932000000", "allowCalls": false, "allowSms": true @@ -2662,7 +2679,7 @@ Usually, when making calls or sending SMS messages from an account, the outgoing Lists the IDs which have been approved for use on the account. - + ``` @@ -2672,7 +2689,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids -```bash +```json HTTP/1.1 200 OK { @@ -2685,17 +2702,16 @@ HTTP/1.1 200 OK "id": "115", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "number": "Sipcentric", "allowCalls": false, "allowSms": true - }, - { + },{ "type": "outgoingcallerid", "id": "114", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "number": "01212854411", "allowCalls": true, "allowSms": true @@ -2713,7 +2729,7 @@ HTTP/1.1 200 OK Get the instance of a specific caller ID. - + ``` @@ -2723,7 +2739,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 -```bash +```json HTTP/1.1 200 OK { @@ -2731,7 +2747,7 @@ HTTP/1.1 200 OK "id": "114", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", + "created": "2014-03-10T13:37:00.000+0000", "number": "01212854411", "allowCalls": true, "allowSms": true @@ -2754,7 +2770,7 @@ HTTP/1.1 200 OK The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. -```bash exampleRepresentation +```json exampleRepresentation { "type": "creditstatus", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", @@ -2777,7 +2793,7 @@ The credit status sub-resource returns the current call credit status of an acco `GET /customers/{customerId}/creditstatus` - + ``` @@ -2787,7 +2803,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/creditstatus -```bash +```json HTTP/1.1 200 OK { @@ -2814,23 +2830,23 @@ HTTP/1.1 200 OK The call bundles sub-resource contains all bundles which have been added to an account - each is represented by a `customerbundle` and includes the current status, as well as used and remaining minutes. -```bash exampleRepresentation - { - type: "customerbundle", - id: "1040" - uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - parent: "https://pbx.sipcentric.com/api/v1/customers/25", - created: "2014-03-01T00:00:00.000+0000", - name: "1000 Mins - UK Local/National", - inclusiveMins: 1000, - priceMonthly: 5, - validFrom: "2014-03-01T00:00:00.000+0000", - validTo: "2014-03-31T23:59:59.999+0000", - usedMins: 57, - availableMins: 943, - autoRenew: true, - status: "ACTIVE" - } +```json +{ + "type": "customerbundle", + "id": "1040", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-01T00:00:00.000+0000", + "name": "1000 Mins - UK Local/National", + "inclusiveMins": 1000, + "priceMonthly": 5, + "validFrom": "2014-03-01T00:00:00.000+0000", + "validTo": "2014-03-31T23:59:59.999+0000", + "usedMins": 57, + "availableMins": 943, + "autoRenew": true, + "status": "ACTIVE" +} ``` | Type: *customerbundle* | | @@ -2858,7 +2874,7 @@ The call bundles sub-resource contains all bundles which have been added to an a List all bundles added to an account. - + ``` @@ -2868,7 +2884,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles -```bash +```json HTTP/1.1 200 OK { @@ -2876,21 +2892,21 @@ HTTP/1.1 200 OK "pageSize": 20, "page": 1, "items": [ - { - type: "customerbundle", - id: "1040" - uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - parent: "https://pbx.sipcentric.com/api/v1/customers/25", - created: "2014-03-01T00:00:00.000+0000", - name: "1000 Mins - UK Local/National", - inclusiveMins: 1000, - priceMonthly: 5, - validFrom: "2014-03-01T00:00:00.000+0000", - validTo: "2014-03-31T23:59:59.999+0000", - usedMins: 57, - availableMins: 943, - autoRenew: true, - status: "ACTIVE" + { + "type": "customerbundle", + "id": "1040", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "created": "2014-03-01T00:00:00.000+0000", + "name": "1000 Mins - UK Local/National", + "inclusiveMins": 1000, + "priceMonthly": 5, + "validFrom": "2014-03-01T00:00:00.000+0000", + "validTo": "2014-03-31T23:59:59.999+0000", + "usedMins": 57, + "availableMins": 943, + "autoRenew": true, + "status": "ACTIVE" } ] } @@ -2906,7 +2922,7 @@ HTTP/1.1 200 OK Fetches the instance of a specific customer bundle. - + ``` @@ -2916,12 +2932,12 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040 -```bash +```json HTTP/1.1 200 OK { "type": "customerbundle", - "id": "1040" + "id": "1040", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", "parent": "https://pbx.sipcentric.com/api/v1/customers/25", "created": "2014-03-01T00:00:00.000+0000", @@ -2953,16 +2969,16 @@ HTTP/1.1 200 OK The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. -```bash exampleRepresentation +```json exampleRepresentation { - "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", - "postpaid": true, - "creditLimit": 50.00, - "warningThreshold": 0.00 + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 } ``` @@ -2983,7 +2999,7 @@ The call charging sub-resource returns the current call charging plan for an ac `GET /customers/{customerId}/callcharging` - + ``` @@ -2993,18 +3009,18 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/callcharging -```bash +```json HTTP/1.1 200 OK { - "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", - "postpaid": true, - "creditLimit": 50.00, - "warningThreshold": 0.00 + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 } ``` @@ -3016,7 +3032,7 @@ HTTP/1.1 200 OK `PUT /customers/{customerId}/callcharging` - + ``` @@ -3026,18 +3042,18 @@ PUT https://pbx.sipcentric.com/api/v1/customers/25/callcharging -```bash +```json HTTP/1.1 200 OK { - "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", - "postpaid": true, - "creditLimit": 50.00, - "warningThreshold": 0.00 + "type": "customercallcharging", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 } ``` @@ -3058,18 +3074,18 @@ HTTP/1.1 200 OK The Permissions sub-resource returns the current customer permissions for an account, represented by a `permissions` instance. -```bash exampleRepresentation +```json exampleRepresentation { - "type": "customerpermissions", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "incomingCalls": true, - "outgoingCalls": true, - "internationalCalls": false, - "addFeatures": true, - "removeFeatures": true, - "enableRecording": true + "type": "customerpermissions", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true } ``` @@ -3092,7 +3108,7 @@ The Permissions sub-resource returns the current customer permissions for an a `GET /customers/{customerId}/permissions` - + ``` @@ -3102,27 +3118,27 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/permissions -```bash +```json HTTP/1.1 200 OK { - "type": "customerpermissions", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "incomingCalls": true, - "outgoingCalls": true, - "internationalCalls": false, - "addFeatures": true, - "removeFeatures": true, - "enableRecording": true + "type": "customerpermissions", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true } ``` -### billing +### Billing | Resource Information | | |:-------------------------------|:-------------------------------------| @@ -3136,34 +3152,34 @@ HTTP/1.1 200 OK The billing sub-resource returns the current billing configuration and pricing plan for different features, represented by a `billing` instance. -```bash exampleRepresentation +```json exampleRepresentation { - "type": "billingaccount", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "paymentsEnabled": false, - "providersEnabled": [], - "upgradeAllowed": true, - "downgradeAllowed": true, - "paymentMethodRequired": false, - "currency": "GBP", - "frequency": "MONTHLY", - "nextBillingDate": "2023-06-01T01:00:00Z", - "featurePricing": { - "virtual": 0.00, - "mailbox": 1.00, - "ivr": 3.00, - "phone": 11.00, - "trunk": 8.50, - "did": 2.00, - "queue": 3.00, - "group": 2.00 - }, - "links": { - "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", - "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", - "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" - } + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "paymentsEnabled": false, + "providersEnabled": [], + "upgradeAllowed": true, + "downgradeAllowed": true, + "paymentMethodRequired": false, + "currency": "GBP", + "frequency": "MONTHLY", + "nextBillingDate": "2023-06-01T01:00:00Z", + "featurePricing": { + "virtual": 0.00, + "mailbox": 1.00, + "ivr": 3.00, + "phone": 11.00, + "trunk": 8.50, + "did": 2.00, + "queue": 3.00, + "group": 2.00 + }, + "links": { + "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + } } ``` @@ -3181,12 +3197,12 @@ The billing sub-resource returns the current billing configuration and pricing | frequency
*read-only* | billing frequence (Monthly)
*string* | | featurePricing
*read-only* | prices of the features
*string* | -#### Get billing +#### Get Billing `GET /customers/{customerId}/billing` - + ``` @@ -3196,36 +3212,36 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/billing -```bash +```json HTTP/1.1 200 OK { - "type": "billingaccount", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "paymentsEnabled": false, - "providersEnabled": [], - "upgradeAllowed": true, - "downgradeAllowed": true, - "paymentMethodRequired": false, - "currency": "GBP", - "frequency": "MONTHLY", - "nextBillingDate": "2023-06-01T01:00:00Z", - "featurePricing": { - "virtual": 0.00, - "mailbox": 1.00, - "ivr": 3.00, - "phone": 11.00, - "trunk": 8.50, - "did": 2.00, - "queue": 3.00, - "group": 2.00 - }, - "links": { - "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", - "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", - "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" - } + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "paymentsEnabled": false, + "providersEnabled": [], + "upgradeAllowed": true, + "downgradeAllowed": true, + "paymentMethodRequired": false, + "currency": "GBP", + "frequency": "MONTHLY", + "nextBillingDate": "2023-06-01T01:00:00Z", + "featurePricing": { + "virtual": 0.00, + "mailbox": 1.00, + "ivr": 3.00, + "phone": 11.00, + "trunk": 8.50, + "did": 2.00, + "queue": 3.00, + "group": 2.00 + }, + "links": { + "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + } } ``` @@ -3249,33 +3265,33 @@ This resource is used to set customers price plans. -```bash exampleRepresentation +```json exampleRepresentation { - "type" : "invoice", - "id" : "E5", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", - "created" : "2023-05-17T15:22:38Z", - "netAmount" : 133.00, - "vatAmount" : 26.60, - "total" : 159.60, - "lines" : [ { - "description" : "Phone Extension", - "unitPrice" : 3.00, - "quantity" : 31, - "lineTotal" : 93.00, - "usage" : false - }, { - "description" : "Virtual Extension", - "unitPrice" : 0.00, - "quantity" : 11, - "lineTotal" : 0.00, - "usage" : false + "type": "invoice", + "id": "E5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", + "created": "2023-05-17T15:22:38Z", + "netAmount": 133.00, + "vatAmount": 26.60, + "total": 159.60, + "lines": [ { + "description": "Phone Extension", + "unitPrice": 3.00, + "quantity": 31, + "lineTotal": 93.00, + "usage": false + },{ + "description": "Virtual Extension", + "unitPrice": 0.00, + "quantity": 11, + "lineTotal": 0.00, + "usage": false }, ...... ], - "date" : "2023-05-17T15:22:38Z", - "credit" : false, - "currency" : "GBP" + "date": "2023-05-17T15:22:38Z", + "credit": false, + "currency": "GBP" } ``` @@ -3300,12 +3316,12 @@ This resource is used to set customers price plans. | usage
*read-only* |whethere resource is usable or not
*boolean* | -#### Get estimates +#### Get Billing Estimate `GET /customers/{customerId}/billing/estimates/` - + ``` @@ -3315,81 +3331,83 @@ GET https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate -```bash +```json HTTP/1.1 200 OK { - "type" : "invoice", - "id" : "E5", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", - "created" : "2023-05-17T15:22:38Z", - "netAmount" : 133.00, - "vatAmount" : 26.60, - "total" : 159.60, - "lines" : [ { - "description" : "Phone Extension", - "unitPrice" : 3.00, - "quantity" : 31, - "lineTotal" : 93.00, - "usage" : false - }, { - "description" : "Virtual Extension", - "unitPrice" : 0.00, - "quantity" : 11, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "Additional Mailbox", - "unitPrice" : 0.00, - "quantity" : 3, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "Ring Group", - "unitPrice" : 0.00, - "quantity" : 5, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "Call Queue", - "unitPrice" : 0.00, - "quantity" : 7, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "Voice Menu/IVR", - "unitPrice" : 0.00, - "quantity" : 7, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "Public Number", - "unitPrice" : 0.00, - "quantity" : 34, - "lineTotal" : 0.00, - "usage" : false - }, { - "description" : "500 Mins - UK Mobile", - "unitPrice" : 25.00, - "quantity" : 1, - "lineTotal" : 25.00, - "usage" : false - }, { - "description" : "250 Mins - UK Mobile", - "unitPrice" : 15.00, - "quantity" : 1, - "lineTotal" : 15.00, - "usage" : false - }, { - "description" : "1000 Mins - Local/National (Free)", - "unitPrice" : 0.00, - "quantity" : 1, - "lineTotal" : 0.00, - "usage" : false - } ], - "date" : "2023-05-17T15:22:38Z", - "credit" : false, - "currency" : "GBP" + "type": "invoice", + "id": "E5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", + "created": "2023-05-17T15:22:38Z", + "netAmount": 133.00, + "vatAmount": 26.60, + "total": 159.60, + "lines": [ + { + "description": "Phone Extension", + "unitPrice": 3.00, + "quantity": 31, + "lineTotal": 93.00, + "usage": false + },{ + "description": "Virtual Extension", + "unitPrice": 0.00, + "quantity": 11, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Additional Mailbox", + "unitPrice": 0.00, + "quantity": 3, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Ring Group", + "unitPrice": 0.00, + "quantity": 5, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Call Queue", + "unitPrice": 0.00, + "quantity": 7, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Voice Menu/IVR", + "unitPrice": 0.00, + "quantity": 7, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Public Number", + "unitPrice": 0.00, + "quantity": 34, + "lineTotal": 0.00, + "usage": false + },{ + "description": "500 Mins - UK Mobile", + "unitPrice": 25.00, + "quantity": 1, + "lineTotal": 25.00, + "usage": false + },{ + "description": "250 Mins - UK Mobile", + "unitPrice": 15.00, + "quantity": 1, + "lineTotal": 15.00, + "usage": false + },{ + "description": "1000 Mins - Local/National (Free)", + "unitPrice": 0.00, + "quantity": 1, + "lineTotal": 0.00, + "usage": false + } + ], + "date": "2023-05-17T15:22:38Z", + "credit": false, + "currency": "GBP" } ``` @@ -3400,7 +3418,7 @@ HTTP/1.1 200 OK -### limits +### Limits | Resource Information | | |:-------------------------------|:-------------------------------------| @@ -3414,20 +3432,20 @@ HTTP/1.1 200 OK The limits sub-resource returns the current limits on different features for an account , represented by a `limits` instance. -```bash exampleRepresentation +```json { - "type": "customerlimits", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "phone": 50, - "group": 10, - "queue": 10, - "ivr": 10, - "mailbox": 10, - "trunk": 5, - "did": 20, - "channel": 5 + "type": "customerlimits", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 50, + "group": 10, + "queue": 10, + "ivr": 10, + "mailbox": 10, + "trunk": 5, + "did": 20, + "channel": 5 } ``` @@ -3446,12 +3464,12 @@ The limits sub-resource returns the current limits on different features for an | did
*read-only* | total DID's allowed
*integer* | | channel
*read-only* | total allowed channels
*integer* | -#### Get limits +#### Get Account Limits `GET /customers/{customerId}/limits` - + ``` @@ -3461,29 +3479,29 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/limits -```bash +```json HTTP/1.1 200 OK { - "type": "customerlimits", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "phone": 50, - "group": 10, - "queue": 10, - "ivr": 10, - "mailbox": 10, - "trunk": 5, - "did": 20, - "channel": 5 + "type": "customerlimits", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 50, + "group": 10, + "queue": 10, + "ivr": 10, + "mailbox": 10, + "trunk": 5, + "did": 20, + "channel": 5 } ``` -### pricing +### Pricing | Resource Information | | |:-------------------------------|:-------------------------------------| @@ -3497,19 +3515,19 @@ HTTP/1.1 200 OK The pricing sub-resource returns the current pricing or cost of different services for an account, represented by a `pricing` instance. -```bash exampleRepresentation +```json { - "type" : "customerpricing", - "id" : "25", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/pricing", - "parent" : "https://pbx.sipcentric.com/api/v1/customers/25", - "phone" : 2.00, - "virtual" : 0.10, - "group" : 4.00, - "queue" : 4.00, - "ivr" : 2.00, - "mailbox" : 2.00, - "did" : 3.00 + "type": "customerpricing", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 2.00, + "virtual": 0.10, + "group": 4.00, + "queue": 4.00, + "ivr": 2.00, + "mailbox": 2.00, + "did": 3.00 } ``` @@ -3528,12 +3546,12 @@ The pricing sub-resource returns the current pricing or cost of different servi | did
*read-only* | price per DID
*float* | -#### Get pricing +#### Get Pricing `GET /customers/{customerId}/pricing` - + ``` @@ -3543,21 +3561,21 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/pricing -```bash +```json HTTP/1.1 200 OK { - "type" : "customerpricing", - "id" : "25", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/pricing", - "parent" : "https://pbx.sipcentric.com/api/v1/customers/25", - "phone" : 2.00, - "virtual" : 0.10, - "group" : 4.00, - "queue" : 4.00, - "ivr" : 2.00, - "mailbox" : 2.00, - "did" : 3.00 + "type": "customerpricing", + "id": "25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "phone": 2.00, + "virtual": 0.10, + "group": 4.00, + "queue": 4.00, + "ivr": 2.00, + "mailbox": 2.00, + "did": 3.00 } ``` @@ -3568,28 +3586,28 @@ HTTP/1.1 200 OK To change the current pricing, please use a PUT as per the below. - + ``` PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing { - "type" : "customerpricing", - "phone" : 7 + "type": "customerpricing", + "phone": 7 } ``` -```bash +```json HTTP/1.1 200 OK ``` -### linkedusers +### Linkedusers (Web Users) | Resource Information | | |:-------------------------------|:-------------------------------------| @@ -3603,21 +3621,21 @@ HTTP/1.1 200 OK The Linked Users sub-resource returns the users that are linked to an account, represented by a `linkedusers` instance. -```bash exampleRepresentation +```json exampleRepresentation { - "type": "linkeduser", - "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", - "created": "2023-01-24T13:24:12Z", - "userId": "27068", - "email": "Fred.muteesa+Test@simwood.com", - "username": "fmuteesa", - "accessLevel": "CUSTOMER", - "enabled": true, - "pending": false, - "acceptedInvite": "2023-01-24T13:25:23Z", - "owner": true, - "recordingAccess": "ALL" + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "Fred.muteesa+Test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" } ``` @@ -3639,12 +3657,12 @@ The Linked Users sub-resource returns the users that are linked to an account, | recordingAccess
*read-only* | can access all records
*float* | -#### Get linkedusers +#### Get Linkedusers `GET /customers/{customerId}/linkedusers` - + ``` @@ -3654,41 +3672,41 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers -```bash +```json HTTP/1.1 200 OK { - "totalItems": 1, - "pageSize": 20, - "page": 1, - "items": [ - { - "type": "linkeduser", - "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", - "created": "2023-01-24T13:24:12Z", - "userId": "27068", - "email": "Fred.muteesa+Test@simwood.com", - "username": "fmuteesa", - "accessLevel": "CUSTOMER", - "enabled": true, - "pending": false, - "acceptedInvite": "2023-01-24T13:25:23Z", - "owner": true, - "recordingAccess": "ALL" - } - ] + "totalItems": 1, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "Fred.muteesa+Test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" + } + ] } ``` -#### Get a linkeduser +#### Get a Linkeduser `GET /customers/{customerId}/linkedusers/{linkeduserId}` - + ``` @@ -3698,33 +3716,33 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180 -```bash +```json HTTP/1.1 200 OK { - "type": "linkeduser", - "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", - "created": "2023-01-24T13:24:12Z", - "userId": "27068", - "email": "Fred.muteesa+Test@simwood.com", - "username": "fmuteesa", - "accessLevel": "CUSTOMER", - "enabled": true, - "pending": false, - "acceptedInvite": "2023-01-24T13:25:23Z", - "owner": true, - "recordingAccess": "ALL" + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "Fred.muteesa+Test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" } ``` -#### Get self linkeduser details +#### Get own linkeduser details `GET /customers/{customerId}/linkedusers/me` - + ``` @@ -3734,22 +3752,22 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/me -```bash +```json HTTP/1.1 200 OK { - "type" : "linkeduser", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers/me", - "userId" : "27062", - "firstName" : "Fred", - "lastName" : "Muteesa", - "email" : "Fred.muteesa@simwood.com", - "username" : "Fred@sipcentric", - "accessLevel" : "ADMIN", - "enabled" : true, - "pending" : false, - "owner" : false, - "recordingAccess" : "NONE" + "type": "linkeduser", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers/me", + "userId": "27062", + "firstName": "Fred", + "lastName": "Muteesa", + "email": "Fred.muteesa@simwood.com", + "username": "Fred@sipcentric", + "accessLevel": "ADMIN", + "enabled": true, + "pending": false, + "owner": false, + "recordingAccess": "NONE" } ``` @@ -3763,7 +3781,7 @@ DELETE /customers/{customerId}/linkedusers/{linkeduserId}?removeUser=true There are 2 kinds of user: Web User (which is a single user-login) and Linked User (which is an association between Web User and an Account). So you can have a user on multiple accounts - e.g an IT Technician who supports 3 schools with their own accounts may have a single Web User but then will have Linked Users across 3 separate accounts.
With the above in mind, when you **DELETE** a Linked User you only delete that association rather than the Web User too. You can still link the existing Web User to a new account in this scenario if you wish. -However, if you'd like to fully remove a user, when you submit your Linked User delete, add in an additional query parameter of *removeUser* with a value of true: "removeUser" : true +However, if you'd like to fully remove a user, when you submit your Linked User delete, add in an additional query parameter of *removeUser* with a value of true: "removeUser": true ## Charging Plans @@ -3782,17 +3800,17 @@ This resource is used to set customers price plans. -```bash exampleRepresentation +```json exampleRepresentation { - "type": "chargingplan", - "id": "1", - "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", - "name": "Standard", - "currency": "GBP", - "domainCostMinute": 0.000, - "roundSeconds": 1, - "minDuration": 20, - "minCharge": 0.000 + "type": "chargingplan", + "id": "1", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", + "name": "Standard", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 } ``` @@ -3817,7 +3835,7 @@ This resource is used to set customers price plans. `GET /chargingplans/` - + ``` @@ -3827,37 +3845,36 @@ GET https://pbx.sipcentric.com/api/v1/chargingplans/ -```bash +```json HTTP/1.1 200 OK - -"totalItems": 10, - "pageSize": 20, - "page": 1, - "items": [ - { - "type": "chargingplan", - "id": "1", - "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", - "name": "Standard", - "currency": "GBP", - "domainCostMinute": 0.000, - "roundSeconds": 1, - "minDuration": 20, - "minCharge": 0.000 - }, - { - "type": "chargingplan", - "id": "36", - "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/36", - "name": "Special - 4.5p Mobile / 0.5p Landline", - "currency": "GBP", - "domainCostMinute": 0.000, - "roundSeconds": 1, - "minDuration": 1, - "minCharge": 0.010 - }, - .... - ] +{ + "totalItems": 10, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "chargingplan", + "id": "1", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/1", + "name": "Standard", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 + },{ + "type": "chargingplan", + "id": "36", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/36", + "name": "Special - 4.5p Mobile / 0.5p Landline", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 1, + "minCharge": 0.010 + }, + .... + ] } ``` @@ -3868,7 +3885,7 @@ HTTP/1.1 200 OK `GET /chargingplans/{chargingplanId}` - + ``` @@ -3878,19 +3895,19 @@ GET https://pbx.sipcentric.com/api/v1/chargingplans/8 -```bash +```json HTTP/1.1 200 OK { - "type": "chargingplan", - "id": "8", - "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/8", - "name": "Partner L2", - "currency": "GBP", - "domainCostMinute": 0.000, - "roundSeconds": 1, - "minDuration": 20, - "minCharge": 0.000 + "type": "chargingplan", + "id": "8", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/8", + "name": "Partner L2", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 } ``` @@ -3917,7 +3934,7 @@ Below are examples of requests we can send. I will be explaining the meaning of - + ``` @@ -3932,26 +3949,26 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration", - "columnHeaders": [ - { - "name": "duration", - "columnType": "METRIC" - } - ], - "rows": [ - [ - 108.0 - ] - ], - "totals": { - "duration": 108.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration", + "columnHeaders": [ + { + "name": "duration", + "columnType": "METRIC" } + ], + "rows": [ + [ + 108.0 + ] + ], + "totals": { + "duration": 108.0 + } } ``` @@ -3964,7 +3981,7 @@ From the above results we see that the total Duration for account 5 is 108.0 sec #### Total cost - + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost @@ -3975,27 +3992,27 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost", - "columnHeaders": [ - { - "name": "cost", - "columnType": "METRIC" - } - ], - "rows": [ - [ - 0.0 - ] - ], - "totals": { - "cost": 0.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost", + "columnHeaders": [ + { + "name": "cost", + "columnType": "METRIC" } + ], + "rows": [ + [ + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } } ``` @@ -4010,7 +4027,7 @@ This request has returned the current total cost as £0.00 #### Inbound Vs Outbound Duration - + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration @@ -4019,35 +4036,34 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration", - "columnHeaders": [ - { - "name": "direction", - "columnType": "DIMENSION" - }, - { - "name": "duration", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "in", - 0.0 - ], - [ - "out", - 108.0 - ] - ], - "totals": { - "duration": 108.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration", + "columnHeaders": [ + { + "name": "direction", + "columnType": "DIMENSION" + },{ + "name": "duration", + "columnType": "METRIC" } + ], + "rows": [ + [ + "in", + 0.0 + ], + [ + "out", + 108.0 + ] + ], + "totals": { + "duration": 108.0 + } } ``` @@ -4062,7 +4078,7 @@ From the above response we can see that inbound has 0 seconds and Outbound has 1 This example will show us the total number of seconds consumed by exach extension. This is further categorized by inbound and outbound duration. - + ``` GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension @@ -4072,47 +4088,43 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension", - "columnHeaders": [ - { - "name": "endpoint", - "columnType": "DIMENSION" - }, - { - "name": "duration_in", - "columnType": "METRIC" - }, - { - "name": "duration_out", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "Fred Test <102>", - 0.0, - 55.0 - ], - [ - "Ivan Example <111>", - 0.0, - 0.0 - ], - [ - "Jared Example <215>", - 53.0, - 0.0 - ] - ], - "totals": { - "duration_in": 53.0, - "duration_out": 55.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension", + "columnHeaders": [ + { + "name": "endpoint", + "columnType": "DIMENSION" + },{ + "name": "duration_in", + "columnType": "METRIC" + },{ + "name": "duration_out", + "columnType": "METRIC" } + ], + "rows": [ + [ + "Fred Test <102>", + 0.0, + 55.0 + ],[ + "Ivan Example <111>", + 0.0, + 0.0 + ],[ + "Jared Example <215>", + 53.0, + 0.0 + ] + ], + "totals": { + "duration_in": 53.0, + "duration_out": 55.0 + } } ``` @@ -4129,7 +4141,7 @@ The request would give us the number of calls made or received by each extension - + ``` GET @@ -4140,48 +4152,44 @@ https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=count_in&metric=count_out&endpointType=extension", - "columnHeaders": [ - { - "name": "endpoint", - "columnType": "DIMENSION" - }, - { - "name": "count_in", - "columnType": "METRIC" - }, - { - "name": "count_out", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "Fred Test <102>", - 1.0, - 5.0 - ], - [ - "Ivan Example <111>", - 1.0, - 0.0 - ], - [ - "Jared Example <215>", - 3.0, - 1.0 - ] - ], - "totals": { - "count_in": 5.0, - "count_out": 6.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=count_in&metric=count_out&endpointType=extension", + "columnHeaders": [ + { + "name": "endpoint", + "columnType": "DIMENSION" + },{ + "name": "count_in", + "columnType": "METRIC" + },{ + "name": "count_out", + "columnType": "METRIC" } + ], + "rows": [ + [ + "Fred Test <102>", + 1.0, + 5.0 + ],[ + "Ivan Example <111>", + 1.0, + 0.0 + ],[ + "Jared Example <215>", + 3.0, + 1.0 + ] + ], + "totals": { + "count_in": 5.0, + "count_out": 6.0 + } } ``` @@ -4197,7 +4205,7 @@ This request gives you visibility into Call dispositions. That is, what happene You are able to see the number Unanswered calls - + ``` @@ -4208,31 +4216,30 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in", - "columnHeaders": [ - { - "name": "outcome", - "columnType": "DIMENSION" - }, - { - "name": "count", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "NO ANSWER", - 2.0 - ] - ], - "totals": { - "count": 2.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in", + "columnHeaders": [ + { + "name": "outcome", + "columnType": "DIMENSION" + },{ + "name": "count", + "columnType": "METRIC" } + ], + "rows": [ + [ + "NO ANSWER", + 2.0 + ] + ], + "totals": { + "count": 2.0 + } } ``` @@ -4245,7 +4252,7 @@ HTTP/1.1 200 OK You can use the exmaple below to see which number calls your DID's the most. - + ``` @@ -4257,31 +4264,30 @@ https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=callerid&metric=count&sort=-count&scope=external&direction=in&limit=10", - "columnHeaders": [ - { - "name": "callerid", - "columnType": "DIMENSION" - }, - { - "name": "count", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "07760431465", - 1.0 - ] - ], - "totals": { - "count": 1.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=callerid&metric=count&sort=-count&scope=external&direction=in&limit=10", + "columnHeaders": [ + { + "name": "callerid", + "columnType": "DIMENSION" + },{ + "name": "count", + "columnType": "METRIC" } +], +"rows": [ + [ + "07760431465", + 1.0 + ] + ], + "totals": { + "count": 1.0 + } } ``` @@ -4293,7 +4299,7 @@ HTTP/1.1 200 OK #### Get Average Wait Time - + ``` @@ -4304,56 +4310,49 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue", - "columnHeaders": [ - { - "name": "day", - "columnType": "DIMENSION" - }, - { - "name": "avg_duration", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "2023-05-22T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-23T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-24T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-25T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-26T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-27T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-28T00:00:00.000+03:00", - 0.0 - ] - ], - "totals": { - "avg_duration": "NaN" + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "avg_duration", + "columnType": "METRIC" } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "avg_duration": "NaN" + } } ``` @@ -4365,7 +4364,7 @@ HTTP/1.1 200 OK You can also see total calls per day of the week. - + ``` @@ -4376,67 +4375,59 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out", - "columnHeaders": [ - { - "name": "day", - "columnType": "DIMENSION" - }, - { - "name": "count_in", - "columnType": "METRIC" - }, - { - "name": "count_out", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "2023-05-22T00:00:00.000+03:00", - 0.0, - 0.0 - ], - [ - "2023-05-23T00:00:00.000+03:00", - 2.0, - 6.0 - ], - [ - "2023-05-24T00:00:00.000+03:00", - 0.0, - 0.0 - ], - [ - "2023-05-25T00:00:00.000+03:00", - 0.0, - 0.0 - ], - [ - "2023-05-26T00:00:00.000+03:00", - 0.0, - 0.0 - ], - [ - "2023-05-27T00:00:00.000+03:00", - 0.0, - 0.0 - ], - [ - "2023-05-28T00:00:00.000+03:00", - 0.0, - 0.0 - ] - ], - "totals": { - "count_in": 2.0, - "count_out": 6.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "count_in", + "columnType": "METRIC" + },{ + "name": "count_out", + "columnType": "METRIC" } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 2.0, + 6.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0, + 0.0 + ] + ], + "totals": { + "count_in": 2.0, + "count_out": 6.0 + } } ``` @@ -4447,7 +4438,7 @@ HTTP/1.1 200 OK You can also get information about how much you spend per day. - + ``` @@ -4458,56 +4449,49 @@ GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-2 -```bash +```json HTTP/1.1 200 OK { - "type": "datatable", - "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost", - "columnHeaders": [ - { - "name": "day", - "columnType": "DIMENSION" - }, - { - "name": "cost", - "columnType": "METRIC" - } - ], - "rows": [ - [ - "2023-05-22T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-23T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-24T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-25T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-26T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-27T00:00:00.000+03:00", - 0.0 - ], - [ - "2023-05-28T00:00:00.000+03:00", - 0.0 - ] - ], - "totals": { - "cost": 0.0 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "cost", + "columnType": "METRIC" } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } } ``` @@ -4525,7 +4509,7 @@ you would normally have to authenticate for. #### Get token -```bash +```json GET https://pbx.sipcentric.com/api/v1/tokengenerator { @@ -4536,7 +4520,7 @@ GET https://pbx.sipcentric.com/api/v1/tokengenerator } ``` -You can now use this token to get a call recording using the `tokenid` parameter in the GET request: +You can now use this token to get a call recording using the `tokenid` parameter in the GET Request ``` https://pbx.sipcentric.com/api/v1/customers/25/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16 @@ -4560,7 +4544,7 @@ Currently the following is available via the streaming API: Example object: -```bash +```json { "event": "incomingcall", "location": null, @@ -4586,7 +4570,7 @@ Most HTTP client libraries let you handle the connection as a stream. Which allo All of the event objects are in a standard format: -```bash +```json { "event": ..., "location": ..., From 1dd6344c8014eba8d279f10c3205e1b233d71fc1 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Mon, 9 Oct 2023 16:49:02 +0100 Subject: [PATCH 11/15] minor formatting fixes --- docs/direct/api/v1.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index c37727c..96af5ea 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -195,23 +195,19 @@ GET https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&pag "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2468", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/1365", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/4775", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2164", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/3647", ... @@ -631,8 +627,7 @@ HTTP/1.1 200 OK "email": "email@Test.com", "speedDial": 123, "priority": -50 - }, - { + },{ "type": "phonebookentry", "id": "84039", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", @@ -1025,7 +1020,7 @@ The scope of a call can be: "final": true, "links": { "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=366e05e5-1680699535.1182575" - }, + } } ``` @@ -2005,8 +2000,7 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/forwardingrules", "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/phonestatus" } - }, - { + },{ "type": "phone", "id": "89937", "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", From e319dc0154f26851aebe85d51b4e6fadae88d90a Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Mon, 9 Oct 2023 17:19:53 +0100 Subject: [PATCH 12/15] CS Improvements --- docs/wholesale/api/v3.md | 565 +++++++++++++++++++-------------------- 1 file changed, 282 insertions(+), 283 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 6307458..9c31b72 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -81,7 +81,7 @@ when developing it is often useful to see the output in a more human-friendly fo simply by appending `"?pretty=true"` to any endpoint e.g https://api.simwood.com/v3/tools/time?pretty=true would look like this; -``` +```json { "timestamp": 1388748052, "rfc": "Fri 03 Jan 2014 11:20:52 +0000" @@ -128,11 +128,11 @@ Which would return the following ``` Adding `?pretty=true` to the end of the URL would give you the same information in the following format; -``` +```json [ { - "balance": "12.32", - "currency":"GBP" + "balance": "12.32", + "currency":"GBP" } ] ``` @@ -209,10 +209,15 @@ requests. The output from such a POST request (which requests a report) will typically be small, i.e.: -``` -{"mode":"vsind","date":"2012-01-28","type":"voice_summary","account":"ACCOUNT","format" -:"json","hash":"4e591630fedf4aa149db9874fb33fe23","link":"\/v3\/files\/ACCOUNT\/ -4e591630fedf4aa149db9874fb33fe23"} +```json +{ + "mode": "vsind", + "date": "2012-01-28", + "type": "voice_summary", + "account": "ACCOUNT", + "format": "json", + "hash": "4e591630fedf4aa149db9874fb33fe23", + "link": "\/v3\/files\/ACCOUNT\/4e591630fedf4aa149db9874fb33fe23"} ``` @@ -271,8 +276,12 @@ should be POSTed as a variable called ‘callback’. The response to the reques on successful generation of the report we will make a POST to the URL provided. This will contain a single HTTP POST variable call ‘payload’ which will contain the report hash in JSON format, e.g.: -``` -{"app":"reports","id":"76e7a8102f93c636785ea8432c72e07a","data":null} +```json +{ + "app": "reports", + "id": "76e7a8102f93c636785ea8432c72e07a", + "data": null +} ``` The client should then GET the report as usual within a maximum of 5 minutes, after which it may expire. @@ -285,13 +294,13 @@ performance (this is discussed in more detail above) and some POST requests will containing a hash and ‘link’ to a file e.g. ```json { - "mode":"vsind", - "date":"2012-01-28", - "type":"voice_summary", - "account":"{ACCOUNT}", - "format":"json", - "hash":"4e591630fedf4aa149db9874fb33fe23", - "link":"/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23" + "mode": "vsind", + "date": "2012-01-28", + "type": "voice_summary", + "account": "{ACCOUNT}", + "format": "json", + "hash": "4e591630fedf4aa149db9874fb33fe23", + "link": "/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23" } ``` @@ -307,12 +316,12 @@ The functions below are used to retrieve these; ```json { -"ff98d8d8fdf9dfd178e72b6e6ba207ff" { -"name":"ff98d8d8fdf9dfd178e72b6e6ba207ff", -"content_type":"application/json", -"length":410, -"uri":"/v3/files/ACCOUNT/ff98d8d8fdf9dfd178e72b6e6ba207ff" -} + "ff98d8d8fdf9dfd178e72b6e6ba207ff" { + "name":"ff98d8d8fdf9dfd178e72b6e6ba207ff", + "content_type":"application/json", + "length":410, + "uri":"/v3/files/ACCOUNT/ff98d8d8fdf9dfd178e72b6e6ba207ff" + } } ``` @@ -438,13 +447,13 @@ The differences between these account types can be found in the [Simwood Account ```json { - "success": true, - "data": { - "account_type": "developer", - "number_limit": 5, - "channel_limit": 5, - "min_prepay": 50 - } + "success": true, + "data": { + "account_type": "developer", + "number_limit": 5, + "channel_limit": 5, + "min_prepay": 50 + } } ``` @@ -471,32 +480,33 @@ The current status of all invoices on your account is available through the API. | Method | Endpoint | Description | | :------ | :-------------------------------------------- | :--------------------------------------------------- | -| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/unpaid | List of unpaid invoices on account (since June 2010) | -| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/paid | List of paid invoices on account (since June 2010) | -| **GET** | /v3/accounts/{ACCOUNT}/credit/invoices/all | Upgrade or downgrade your account | +| GET | /v3/accounts/{ACCOUNT}/credit/invoices/unpaid | List of unpaid invoices on account (since June 2010) | +| GET | /v3/accounts/{ACCOUNT}/credit/invoices/paid | List of paid invoices on account (since June 2010) | +| GET | /v3/accounts/{ACCOUNT}/credit/invoices/all | Upgrade or downgrade your account | ```json { - "Invoices": [ - { - "InvoiceNumber": "I3010999999", - "Date": "2014-02-30", - "DueDate": "2014-02-30", - "Currency": "GBP", - "Net": "200.00", - "VAT": "40.00", - "Total": "240.00", - "AmountPaid": "240.00", - "AmountCredited": "0.00", - "AmountDue": "0.00" -} ], - "TotalDue": { - "GBP": 0 -}, - "TotalOverDue": null + "Invoices": [ + { + "InvoiceNumber": "I3010999999", + "Date": "2014-02-30", + "DueDate": "2014-02-30", + "Currency": "GBP", + "Net": "200.00", + "VAT": "40.00", + "Total": "240.00", + "AmountPaid": "240.00", + "AmountCredited": "0.00", + "AmountDue": "0.00" + } + ], + "TotalDue": { + "GBP": 0 + }, + "TotalOverDue": null } ``` @@ -533,14 +543,14 @@ The current status of all invoices on your account is available through the API. ```json { - "mode": null, - "from": "2023-03-15 00:00:00", - "to": "2023-03-15 23:59:59", - "type": "balance_summary", - "account": "000000", - "format": "json", - "hash": "d3ccc0eb54e65b63c0fea0e9235afbca", - "link": "/v3/files/000000/d3ccc0eb54e65b63c0fea0e9235afbca" + "mode": null, + "from": "2023-03-15 00:00:00", + "to": "2023-03-15 23:59:59", + "type": "balance_summary", + "account": "000000", + "format": "json", + "hash": "d3ccc0eb54e65b63c0fea0e9235afbca", + "link": "/v3/files/000000/d3ccc0eb54e65b63c0fea0e9235afbca" } ``` @@ -722,15 +732,16 @@ Some account types have more than one available tariff or rate deck, these can b "quality": "Platinum", "prefix": 999001, "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Platinum.csv" - }, { - "description": "Legacy GBP Gold", - "servicelevel": 2, - "quality": "Gold", - "prefix": 999002, - "default": true, + },{ + "description": "Legacy GBP Gold", + "servicelevel": 2, + "quality": "Gold", + "prefix": 999002, + "default": true, "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Gold.csv" } -] } + ] +} ``` @@ -880,20 +891,17 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon ```json [ { - "trunk": "930000-ACME", - "calls": 378, - "acd": 1.6, - "minutes": 603.32, - "charges": 8.32 - }, - { - - "trunk": "930000-WIDGETINC", - "calls": 2856, - "acd": 1.56, - "minutes": 4458.47, - "charges": 23.01 - + "trunk": "930000-ACME", + "calls": 378, + "acd": 1.6, + "minutes": 603.32, + "charges": 8.32 + },{ + "trunk": "930000-WIDGETINC", + "calls": 2856, + "acd": 1.56, + "minutes": 4458.47, + "charges": 23.01 } ] ``` @@ -918,8 +926,11 @@ Some notifications can now (as of v3.15) be received via Webhooks, for more info -``` -["blocked_calls","prepay_debit"] +```json +[ + "blocked_calls", + "prepay_debit" +] ``` @@ -1064,9 +1075,9 @@ Customers with a dedicated channel allocation can manage this allocation, splitt ```json - { - "limit_concurrent_in": 10, - "limit_concurrent_out": 20 +{ + "limit_concurrent_in": 10, + "limit_concurrent_out": 20 } ``` @@ -1113,13 +1124,14 @@ Customers with a dedicated channel allocation can manage this allocation, splitt ``` -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------------- | -| GET | Recent (around 24h) channel utilisation samples | -| | The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one. | -| | *1m* One minute | -| | *5m* (Default) Five Minutes | -| | *1h* One Hour | + + | Method | | + | :----- | :----------------------------------------------------------------------------------------------------------------------- | + | GET | Recent (around 24h) channel utilisation samples | + | | The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one. | + | | *1m* One minute | + | | *5m* (Default) Five Minutes | + | | *1h* One Hour | @@ -1127,30 +1139,27 @@ Customers with a dedicated channel allocation can manage this allocation, splitt ```json [ - { - "datetime": "2023-03-18 17:40:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - }, - { - "datetime": "2023-03-18 17:30:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - }, - { - "datetime": "2023-03-18 17:20:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - }, - { - "datetime": "2023-03-18 17:10:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - } + { + "datetime": "2023-03-18 17:40:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + },{ + "datetime": "2023-03-18 17:30:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + },{ + "datetime": "2023-03-18 17:20:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + },{ + "datetime": "2023-03-18 17:10:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + } ] ``` @@ -1165,9 +1174,10 @@ Customers with a dedicated channel allocation can manage this allocation, splitt -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------------- | -| GET | Number and value of calls in progress relative to account balance. Useful for fraud monitoring. | + + | Method | Description | + | :----- | :---------------------------------------------------------------------------------------------- | + | GET | Number and value of calls in progress relative to account balance. Useful for fraud monitoring. | @@ -1176,47 +1186,51 @@ Customers with a dedicated channel allocation can manage this allocation, splitt ```json { - "datetime": "2014-02-30 12:34:35", - "total": 1.164, - "callcount": 107, - "balance": 24.406, - "percent_available": 0.25, - "approx_seconds_remaining": 56838, - "calls": { - "1739": { - "location": "UK - Fixed", - "country": "GB", - "total": 0.85, - "callcount": 85 - }, "2303": { - "location": "UK - Mobile - T-Mobile", - "country": "GB", - "total": 0.244, - "callcount": 19 - }, "277": { - "location": "Mexico - Mexico City", - "country": "MX", - "total": 0.04, - "callcount": 2 -}, "2761": { - "location": "Spain - Mobile - Telefonica", - "country": "ES", - "total": 0.02, - "callcount": 1 -} }, - "countries": { - "MX": { - "total": 0.04, - "callcount": 2 + "datetime": "2014-02-30 12:34:35", + "total": 1.164, + "callcount": 107, + "balance": 24.406, + "percent_available": 0.25, + "approx_seconds_remaining": 56838, + "calls": { + "1739": { + "location": "UK - Fixed", + "country": "GB", + "total": 0.85, + "callcount": 85 }, - "ES": { - "total": 0.02, - "callcount": 1 + "2303": { + "location": "UK - Mobile - T-Mobile", + "country": "GB", + "total": 0.244, + "callcount": 19 }, - "GB": { - "total": 1.094, - "callcount": 104 - } + "277": { + "location": "Mexico - Mexico City", + "country": "MX", + "total": 0.04, + "callcount": 2 + }, + "2761": { + "location": "Spain - Mobile - Telefonica", + "country": "ES", + "total": 0.02, + "callcount": 1 + } + }, + "countries": { + "MX": { + "total": 0.04, + "callcount": 2 + }, + "ES": { + "total": 0.02, + "callcount": 1 + }, + "GB": { + "total": 1.094, + "callcount": 104 + } } } @@ -1238,13 +1252,14 @@ See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/* -| Method | Description | -| :----- | :------------------------------------------ | -| GET | Get information on current call in progress | -| DELETE | End a call in progress | + | Method | Description | + | :----- | :------------------------------------------ | + | GET | Get information on current call in progress | + | DELETE | End a call in progress | + ```json @@ -1258,9 +1273,8 @@ See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/* "destid": "2303" } } - ``` - + @@ -1280,37 +1294,11 @@ As this is a BETA endpoint, the information returned from the above may change a In addition to the CDR Reports (above) you can retrieve any CDRs from the last three months with a simple inline response (rather than polling for a report) - - -| Method | Description | -| :----- | :------------------------------------------ | -| GET | Get information on current call in progress | -| DELETE | End a call in progress | - - - - - -```json -{ - "success": true, - "data": { - "to": "447700900123", - "start": "2019-09-23 12:27:12", - "progress": "2019-09-23 12:27:17", - "answered": "2019-09-23 12:27:21", - "destid": "2303" - } - } - -``` - - | Method | Description | | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET/POST | Both GET and POST are supported. The request can either be made as a GET query string or JSON POST body. At present, the filter attribute is only supported where requested by POST with a JSON body. | -| | date_start Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | +| | *date_start* Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | | | *date_end* Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_end, otherwise defaults to now. | | | *limit* Optionally specify limit of results to return, default 500 | | | *start* Optional offset to start from (for pagination) | @@ -1551,12 +1539,12 @@ As with your account you can also view realtime "in progress" information on a p ```json { - "datetime": "2014-02-30 12:34:35", - "total": 1.164, - "callcount": 107, - "balance": 24.406, - "percent_available": 0.25, - "approx_seconds_remaining": 56838, + "datetime": "2014-02-30 12:34:35", + "total": 1.164, + "callcount": 107, + "balance": 24.406, + "percent_available": 0.25, + "approx_seconds_remaining": 56838, } ``` @@ -1727,8 +1715,13 @@ As detailed below, inbound numbers can be associated with a trunk either for bil ```json { - "success": true, "data": [ "443301223000", "443301223001", "443301223002" ] - } + "success": true, + "data": [ + "443301223000", + "443301223001", + "443301223002" + ] +} ``` @@ -1811,24 +1804,23 @@ Virtual Interconnect - Inbound customers using their own IDA codes should not us ```json { - "success": true, - "data": [ - { - "id": "03dd542cafcecf43fc06024ee6099311424c71cf", - "prefix": "113403", - "sabc": "1134", - "description": "Geographic - Leeds", - "chargeband": "geo" - }, - { - "id": "3d80bd92a9ba2ca31c646881127d322a", - "prefix": "113499", - "sabc": "1134", - "description": "Geographic - Leeds", - "chargeband": "geo" - }, - ... - ] + "success": true, + "data": [ + { + "id": "03dd542cafcecf43fc06024ee6099311424c71cf", + "prefix": "113403", + "sabc": "1134", + "description": "Geographic - Leeds", + "chargeband": "geo" + },{ + "id": "3d80bd92a9ba2ca31c646881127d322a", + "prefix": "113499", + "sabc": "1134", + "description": "Geographic - Leeds", + "chargeband": "geo" + }, + ... + ] } ``` @@ -1917,14 +1909,15 @@ Please note the above options (e.g. 1|10|100) are the only options, arbitrary va ```json { - "success":true, - "data": { - "calldate":"2017-05-01 12:34:01", - "cli":"07700900123", - "disposition":"NORMAL_CLEARING", - "billsec":"64", - "duration":"68" -} } + "success":true, + "data": { + "calldate":"2017-05-01 12:34:01", + "cli":"07700900123", + "disposition":"NORMAL_CLEARING", + "billsec":"64", + "duration":"68" + } +} ``` @@ -1956,26 +1949,24 @@ When a new configuration is provided this will take precedence over any existing { "routing": { - "default": [ - [ - { - "type": "sip", - "endpoint": "441632960000@pbx.simwood.com" - }, - { - "type": "reg", - "user": "930XXX-SIPUSER" - } - ], - [ - { - "type": "pstn", - "number": "447700900123" - } - ] - ] - } - } + "default": [ + [ + { + "type": "sip", + "endpoint": "441632960000@pbx.simwood.com" + },{ + "type": "reg", + "user": "930XXX-SIPUSER" + } + ],[ + { + "type": "pstn", + "number": "447700900123" + } + ] + ] + } +} ``` @@ -2057,8 +2048,7 @@ and will call the SIP endpoint shown and the user on the registration proxy simu "sdes": "none", "opus": "default" } - ], - [ + ],[ { "type": "pstn", "number": "447405644486" @@ -2256,9 +2246,9 @@ The lastUpdated parameter is used to show when a number was last updated. ```json "meta": { - "key": "403010", - "friendlyName": "Main office number", - "lastUpdated": "2014-02-30 01:20:30" + "key": "403010", + "friendlyName": "Main office number", + "lastUpdated": "2014-02-30 01:20:30" } ``` @@ -2360,10 +2350,18 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th "routing": { "default": [ [ - { "type": "sip","endpoint": "user@host.com","timeout": 20 } - ], - [ - { "type": "pstn","number": "447700900123","cli": "442921202120","maxcpm": 0.02} + { + "type": "sip", + "endpoint": "user@host.com", + "timeout": 20 + } + ],[ + { + "type": "pstn", + "number": "447700900123", + "cli": "442921202120", + "maxcpm": 0.02 + } ] ] } @@ -2514,9 +2512,8 @@ Get the trunk currently associated with this number { "success": true, "data": { - "trunk": "930XXX-ACMEPRODUCTS" + "trunk": "930XXX-ACMEPRODUCTS" } - } ``` @@ -2643,8 +2640,8 @@ SMS sent to this number.
```json { - "mode": "http_json", - "endpoint": "https://secure.api.yourdomain.com/path/to/mt" + "mode": "http_json", + "endpoint": "https://secure.api.yourdomain.com/path/to/mt" } ``` @@ -2791,23 +2788,24 @@ be obtained from a GET request to /v3/numbers/{ACCOUNT}/validate/44330 { "success": true, "data": { - "valid": true, - "country_code": "44", - "iso": "gb", - "national_number": "3301229999", - "type": "uan", - "carrier": "Simwood", - "timezones": [ - "Europe\/Guernsey", - "Europe\/Isle_of_Man", - "Europe\/Jersey", - "Europe\/London" - ], - "formatted": { - "e164": "+443301229999", - "national": "0330 122 9999", - "international": "+44 330 122 9999" - }, "ofcom": { + "valid": true, + "country_code": "44", + "iso": "gb", + "national_number": "3301229999", + "type": "uan", + "carrier": "Simwood", + "timezones": [ + "Europe\/Guernsey", + "Europe\/Isle_of_Man", + "Europe\/Jersey", + "Europe\/London" + ], + "formatted": { + "e164": "+443301229999", + "national": "0330 122 9999", + "international": "+44 330 122 9999" + }, + "ofcom": { "status": "allocated", "use": "national non-geographic", "rh": "Simwood eSMS Limited", @@ -3163,15 +3161,16 @@ Get a list of currently outstanding, or recently completed (within the last 90 d { "success": true, "data": [ - { - "ref": "54721", - "mbn": "01632960100", - "date": "2015-02-29", - "crd": "2015-03-14", - "status_code": "submitted_rh", - "status": "Submitted to RH" - }, { -... } + { + "ref": "54721", + "mbn": "01632960100", + "date": "2015-02-29", + "crd": "2015-03-14", + "status_code": "submitted_rh", + "status": "Submitted to RH" + },{ + ... + } ] } ``` From e31b24931a70be49d9bc0e9597c65b558d940903 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Tue, 10 Oct 2023 14:51:04 +0100 Subject: [PATCH 13/15] Further fixes as per requested changes --- docs/direct/api/v1.md | 980 ++++++++++++++++++++------------------- docs/wholesale/api/v3.md | 279 +++++------ 2 files changed, 633 insertions(+), 626 deletions(-) diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index 96af5ea..8306fde 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -40,7 +40,7 @@ Instead of defining its own, arbitrary methods, the Sipcentric API utilizes four #### GET -*Retrieving* a representation of a resource is as easy as GETting its URI. A simple way to Test this is to type the URI of the desired resource into the address bar of your web browser. +*Retrieving* a representation of a resource is as easy as GETting its URI. A simple way to test this is to type the URI of the desired resource into the address bar of your web browser. ##### Response Codes @@ -102,7 +102,7 @@ Finally, where supported, resources may be *removed* using the DELETE method. Pl #### Method Overloading -Not all HTTP libraries support the PUT and DELETE methods. However, it is possible to achieve the same outcome by using POST and including a `_method` query parameter in the request URL, with a value of either PUT or DELETE. For example, take the following DELETE Request +Not all HTTP libraries support the PUT and DELETE methods. However, it is possible to achieve the same outcome by using POST and including a `_method` query parameter in the request URL, with a value of either PUT or DELETE. For example, take the following DELETE request: ``` DELETE /customers/8425/numbers/44675 @@ -263,23 +263,23 @@ All dates and times are formatted according to the ISO 8601 profile. For example The customers resource is the starting point for most account-level operations. Each customer instance represents an account on the Sipcentric platform - it encapsulates a single company/PBX and all of its sub-resources. -```json exampleRepresentation +```json { "type": "customer", - "id": "5", - "uri": "https://pbx.sipcentric.com/api/v1/customers/5", - "created": "2010-12-21T08:30:31Z", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", "accountType": "BUSINESS", - "company": "Sipcentric Ltd.", - "firstName": "Fred", - "lastName": "Test", - "telephone": "07557000000", - "email": "support@sipcentric.com", - "address1": "Test", - "address2": "Test 2", - "city": "Test 3", - "postcode": "98999", - "country": "US", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", "properties": {}, "enabled": true, "currency": "GBP", @@ -299,8 +299,8 @@ The customers resource is the starting point for most account-level operations. "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" }, - "partnerId": "1", - "partnerCompany": "Nimvelo", + "partnerId": "999", + "partnerCompany": "Test Partner", "userEmailUpdatable": false } ``` @@ -309,7 +309,7 @@ The customers resource is the starting point for most account-level operations. |:----------------------------- |:--------------------------------------------------------------------------------------------- | | **Property** | **Description** | | type
*required* | The resource type ("customer").
*String* | -| id
*required* | The unique id ("5").
*String* | +| id
*required* | The unique customer id ("5").
*String* | | uri
*read-only* | URI of this instance.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | accountType
*read-only* | The account types are:
Business (**business**) - full hosted PBX with all the usual business features (call queues, IVRs etc)
Residential Plus (**residential**) - a cut down version aimed at home users, but still having the concept of extensions and ring groups to enable everyone in the home to have their own extension/number and use the mobile app etc.
Residential (**wlr**) - a basic PSTN replacement service, having just a phone number and voicemail. No concept of extensions or mobile apps.| @@ -324,11 +324,11 @@ The customers resource is the starting point for most account-level operations. | postcode
*required* | Primary location postcode.
*String* | | country
*required* | Primary location country.
*String* | | properties[]
*optional* | A collection of customisable properties that could be used to store varying ids
*Array* | -| enabled
*required* | enabled or not.
*Boolean* | +| enabled
*required* | Enabled or not.
*Boolean* | | links[]
*read-only* | A collection of links to related sub-resources.
*Array* | -| partnerId
*required* | partner id ("1")
*string* | -| partnerCompany
*required* | The Partner Company
*string* | -| userEmailUpdatable
*required* | Can the users receive Email updates
*Boolean* | +| partnerId
*required* | Partner id ("1").
*string* | +| partnerCompany
*required* | The Partner Company.
*string* | +| userEmailUpdatable
*required* | Can the users receive Email updates.
*Boolean* | #### List customers @@ -358,20 +358,20 @@ GET https://pbx.sipcentric.com/api/v1/customers "items": [ { "type": "customer", - "id": "5", - "uri": "https://pbx.sipcentric.com/api/v1/customers/5", - "created": "2010-12-21T08:30:31Z", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", "accountType": "BUSINESS", - "company": "Sipcentric Ltd.", - "firstName": "Fred", - "lastName": "Test", - "telephone": "07557000000", - "email": "support@sipcentric.com", - "address1": "Test", - "address2": "Test 2", - "city": "Test 3", - "postcode": "98999", - "country": "US", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", "properties": {}, "enabled": true, "currency": "GBP", @@ -391,8 +391,8 @@ GET https://pbx.sipcentric.com/api/v1/customers "recordings": "https://pbx.sipcentric.com/api/v1/customers/5/recordings", "sms": "https://pbx.sipcentric.com/api/v1/customers/5/sms" }, - "partnerId": "1", - "partnerCompany": "Nimvelo", + "partnerId": "999", + "partnerCompany": "Test Partner", "userEmailUpdatable": false } ] @@ -423,36 +423,36 @@ GET https://pbx.sipcentric.com/api/v1/customers/me { "type": "customer", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created": "2023-01-24T13:00:35Z", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", "accountType": "BUSINESS", - "company": "Fred Test", - "firstName": "Fred", - "lastName": "Muteesa", - "email": "Test@simwood.com", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "email": "Test@test.com", "country": "GB", "properties": {}, "enabled": true, "currency": "GBP", "links": { - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", - "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/99999/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/99999/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/99999/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/99999/sms" }, - "partnerId": "41", - "partnerCompany": "Ops Team Test", + "partnerId": "999", + "partnerCompany": "Test Partner", "userEmailUpdatable": false } ``` @@ -469,19 +469,21 @@ To create a new customer, a representation of a `customer` must be POSTed to the -```json -POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook +``` +POST https://pbx.sipcentric.com/api/v1/customers +``` +```json { "type": "customer", - "telephone":"03301229999", "accountType": "BUSINESS", - "company": "Simwood", - "firstName": "Fred", - "lastName": "Test API", - "email": "Test@Test.com", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", "address1": "Simwood House", - "address2": "Cube m4 Business Park", + "address2": "Cube M4 Business Park", "city": "Bristol", "postcode": "BS16 1FX", "country": "GB", @@ -503,17 +505,17 @@ HTTP/1.1 201 Created { "type": "customer", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", "created": "2023-05-24T11:18:36Z", "accountType": "BUSINESS", - "company": "Simwood", - "firstName": "Fred", - "lastName": "Test API", - "telephone": "03301229999", - "email": "Test@Test.com", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", "address1": "Simwood House", - "address2": "Cube m4 Business Park", + "address2": "Cube M4 Business Park", "city": "Bristol", "postcode": "BS16 1FX", "country": "GB", @@ -523,20 +525,20 @@ HTTP/1.1 201 Created "enabled": true, "currency": "GBP", "links": { - "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids", - "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints", - "preferences": "https://pbx.sipcentric.com/api/v1/customers/25/preferences", - "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals", - "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers", - "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/25/bargegroups", - "callBundles": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles", - "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers", - "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds", - "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook", - "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls", - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings", - "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms" + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/99999/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/99999/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/99999/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/99999/sms" }, "userEmailUpdatable": false } @@ -565,8 +567,8 @@ The phonebook sub-resource allows users to read and organize an account's shared { "type": "phonebookentry", "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", @@ -602,7 +604,7 @@ Return a list of every `phonebookentry` on the customer account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonebook?pageSize=2&page=1 ``` @@ -619,8 +621,8 @@ HTTP/1.1 200 OK { "type": "phonebookentry", "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", @@ -630,15 +632,15 @@ HTTP/1.1 200 OK },{ "type": "phonebookentry", "id": "84039", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84039", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84039", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-04T09:13:08Z", "name": "Fred Test 3", "phoneNumber": "256761303030", "priority": 0 } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook?pageSize=2&page=2" } ``` @@ -655,7 +657,7 @@ Returns the instance of an individual `phonebookentry`. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/773 ``` @@ -668,8 +670,8 @@ HTTP/1.1 200 OK { "type": "phonebookentry", "id": "84033", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84033", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-03T17:21:14Z", "name": "Test Contact", "phoneNumber": "256754999999", @@ -692,9 +694,11 @@ To create a new phone book entry, a representation of a `phonebookentry` must be -```json -POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook +``` +POST https://pbx.sipcentric.com/api/v1/customers/99999/phonebook +``` +```json { "type": "phonebookentry", "name": "Fred Mobile", @@ -712,8 +716,8 @@ HTTP/1.1 201 Created { "type": "phonebookentry", "id": "84072", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/84072", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84072", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-05T10:30:15Z", "name": "Fred Mobile", "phoneNumber": "07902000000", @@ -733,10 +737,11 @@ To update a `phonebookentry`, a representation of the updated `phonebookentry` m -```json - -PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 +``` +PUT https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716 +``` +```json { "type": "phonebookentry", "name": "Fred Mobile", @@ -754,7 +759,7 @@ HTTP/1.1 200 OK { "type": "phonebookentry", - "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716", + "uri": "http://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716", "created": "2014-03-10T13:38:00.000+0000", "name": "Fred Mobile", "phoneNumber": "07825000000", @@ -775,7 +780,7 @@ To delete a `phonebookentry`, a DELETE request must be made to the instance reso ``` -DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 +DELETE https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716 ``` @@ -806,13 +811,13 @@ The SMS sub-resource contains a record of every SMS message sent or received on { "type": "smsmessage", "id": "31408968", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-03T17:27:59Z", "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hello M. confirm receipt of this sms", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", "sendStatus": "SENT", "deliveryStatus": 1, "cost": 0.080, @@ -846,7 +851,7 @@ Returns a list of every `smsmessage` on the account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sms?pageSize=2&page=1 ``` @@ -862,13 +867,13 @@ HTTP/1.1 200 OK { "type": "smsmessage", "id": "31414341", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-05T10:48:45Z", "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hey, this API is awesome!", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", "sendStatus": "SENT", "deliveryStatus": 1, "cost": 0.080, @@ -876,12 +881,12 @@ HTTP/1.1 200 OK },{ "type": "smsmessage", "id": "31414338", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414338", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414338", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-05T10:45:07Z", "direction": "OUT", - "from": "02031371636", - "to": "07902000000", + "from": "012345678901", + "to": "012345678901", "body": "second check on you", "sendStatus": "SENT", "deliveryStatus": 1, @@ -889,7 +894,7 @@ HTTP/1.1 200 OK "creditsUsed": 1 } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" } ``` @@ -905,7 +910,7 @@ Returns the instance of a specific `smsmessage`. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sms/999993368 ``` @@ -917,13 +922,13 @@ HTTP/1.1 200 OK { "type": "smsmessage", "id": "31408968", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31408968", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-03T17:27:59Z", "direction": "OUT", - "from": "02031371636", - "to": "07902000000", - "body": "Hello M. confirm receipt of this sms", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", "sendStatus": "SENT", "deliveryStatus": 1, "cost": 0.080, @@ -943,14 +948,16 @@ To send a new SMS, simply POST a representation of a new `smsmessage` to the lis -```json -POST https://pbx.sipcentric.com/api/v1/customers/25/sms +``` +POST https://pbx.sipcentric.com/api/v1/customers/99999/sms +``` +```json { "type": "smsmessage", - "to": "07902000000", - "from": "01212854400", - "body": "Hey, this API is awesome!" + "to": "012345678901", + "from": "012345678901", + "body": "This is a test sms" } ``` @@ -963,12 +970,12 @@ HTTP/1.1 201 Created { "type": "smsmessage", "id": "31414341", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/31414341", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "direction": "OUT", - "from": "07902000000", - "to": "01212854400", - "body": "Hey, this API is awesome!", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", "sendStatus": "SENT", "cost": 0.080, "creditsUsed": 1 @@ -1002,24 +1009,24 @@ The scope of a call can be: { "type": "call", "id": "209925287", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/209925287", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/209925287", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-04-05T12:59:05Z", "scope": "EXTERNAL", "direction": "OUT", - "from": "Fred Muteesa <100>", - "to": "01912058750", - "callerId": "02031371636", + "from": "Test User <123>", + "to": "012345678901", + "callerId": "012345678901", "callStarted": "2023-04-05T12:58:55Z", "outcome": "ANSWERED", "duration": 7, "cost": 0.010, "callId": "366e05e5-1680699535.1182575", "linkedId": "366e05e5-1680699535.1182575", - "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", + "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069", "final": true, "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=366e05e5-1680699535.1182575" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=366e05e5-1680699535.1182575" } } ``` @@ -1070,7 +1077,7 @@ Making a GET request to the list resource will return a history of the calls mad ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1 ``` @@ -1087,13 +1094,13 @@ HTTP/1.1 200 OK { "type": "call", "id": "7592432", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592432", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/7592432", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:47:05.000+0000", "scope": "EXTERNAL", "direction": "IN", - "from": "07557000000", - "to": "Sales Group <500>", + "from": "012345678901", + "to": "Test Group <123>", "callStarted": "2014-03-10T13:46:35.000+0000", "outcome": "NO_ANSWER", "duration": 0, @@ -1101,18 +1108,18 @@ HTTP/1.1 200 OK "callId": "ast01-1400142051.1562723", "linkedId": "ast01-1400142051.1562723", "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=ast01-1400142051.1562723" } },{ "type": "call", "id": "7592434", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592434", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/7592434", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "scope": "EXTERNAL", "direction": "OUT", - "from": "Greg Sanderson <103>", - "to": "07557000000", + "from": "Test User <123>", + "to": "012345678901", "callStarted": "2014-03-10T13:35:51.000+0000", "outcome": "ANSWERED", "duration": 60, @@ -1120,11 +1127,11 @@ HTTP/1.1 200 OK "callId": "ast01-1401721105.2847099", "linkedId": "ast01-1401721105.2847099", "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1401721105.2847099" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=ast01-1401721105.2847099" } } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/calls?pageSize=2&page=2" } ``` @@ -1141,12 +1148,14 @@ To originate a new call, you should POST a new `call` representation containing ``` -POST https://pbx.sipcentric.com/api/v1/customers/25/calls +POST https://pbx.sipcentric.com/api/v1/customers/99999/calls +``` +```json { "type": "call", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1234", - "to": "07902000000" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/1234", + "to": "012345678901" } ``` @@ -1203,7 +1212,9 @@ To change the current status of an endpoint, please use a PUT as per the below. ``` PUT https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus +``` +```json { "type": "phonestatus", "dndActive": true @@ -1283,7 +1294,7 @@ Returns all sounds, optionally filtered by the following query parameters: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sounds?pageSize=2&page=1 ``` @@ -1300,22 +1311,22 @@ HTTP/1.1 200 OK { "type": "prompt", "id": "1046", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1046", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:38:00.0000+0000", "name": "thank-you-for-calling", "size": 129612 },{ "type": "prompt", "id": "1035", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.0000+0000", "name": "calls-may-be-recorded", "size": 69426 } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds?pageSize=2&page=2" } ``` @@ -1332,7 +1343,7 @@ Returns the instance of a specific sound file. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035 ``` @@ -1344,7 +1355,7 @@ HTTP/1.1 200 OK { "type": "prompt", "id": "1035", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035", "created": "2014-03-10T13:37:00.0000+0000", "name": "calls-may-be-recorded", "size": 69426 @@ -1374,12 +1385,12 @@ See [Response Formats](#response-formats) for more information. The recordings sub-resource provides a way to retrieve and manage the call recordings which are currently stored on an account. Each `recording` representation contains a set of properties which allow for easy indexing/searching based on the local endpoint, remote party ID, time of recording etc. -```json exampleRepresentation +```json { "type": "recording", "id": "1358371", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "direction": "IN", "partyId": "106", @@ -1387,7 +1398,7 @@ The recordings sub-resource provides a way to retrieve and manage the call recor "size": 9615, "callId": "ast01-1400082083.1542464", "linkedId": "ast01-1400082083.1542464", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" } ``` @@ -1426,7 +1437,7 @@ Returns a list of recordings, optionally filtered by the following query paramet ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/recordings?pageSize=2&page=1 ``` @@ -1443,8 +1454,8 @@ HTTP/1.1 200 OK { "type": "recording", "id": "1358372", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358372", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T14:09:00.0000+0000", "direction": "OUT", "partyId": "07557000000", @@ -1452,12 +1463,12 @@ HTTP/1.1 200 OK "size": 97365, "callId": "ast01-1401721105.2847099", "linkedId": "ast01-1401721105.2847099", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/1928" },{ "type": "recording", "id": "1358371", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:42:00.0000+0000", "direction": "IN", "partyId": "07557000000", @@ -1465,10 +1476,10 @@ HTTP/1.1 200 OK "size": 9615, "callId": "ast01-1400082083.1542464", "linkedId": "ast01-1400082083.1542464", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?pageSize=2&page=2" } ``` @@ -1486,7 +1497,7 @@ Fetches the instance of a specific recording. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371 +GET https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371 ``` @@ -1498,8 +1509,8 @@ HTTP/1.1 200 OK { "type": "recording", "id": "1358371", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:42:00.0000+0000", "direction": "IN", "partyId": "07557000000", @@ -1507,7 +1518,7 @@ HTTP/1.1 200 OK "size": 9615, "callId": "ast01-1400082083.1542464", "linkedId": "ast01-1400082083.1542464", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" } ``` @@ -1534,12 +1545,12 @@ See [Response Formats](#response-formats) for more information. A time interval (`timeinterval`) defines the single or set of time periods which together, constitute a recurring weekly/yearly event or work pattern - for example, "Out of Hours", "Public Holidays" or "My Cat's Birthday". Time intervals are used for matching against when defining time-based routing or access rules elsewhere on the system. -```json exampleRepresentation +```json { "type": "timeinterval", "id": "431", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", @@ -1598,7 +1609,7 @@ Returns a list of previously defined time intervals on an account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals?pageSize=2&page=1 ``` @@ -1615,8 +1626,8 @@ HTTP/1.1 200 OK { "type": "timeinterval", "id": "32", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/32", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "name": "Christmas Day", "repeat": "YEARLY", @@ -1631,8 +1642,8 @@ HTTP/1.1 200 OK },{ "type": "timeinterval", "id": "8675", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/31", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:27:00.000+0000", "name": "Office Hours", "repeat": "WEEKLY", @@ -1661,7 +1672,7 @@ HTTP/1.1 200 OK ] } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals?pageSize=2&page=2" } ``` @@ -1679,7 +1690,7 @@ Returns the instance of a specific time interval. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431 +GET https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431 ``` @@ -1692,8 +1703,8 @@ HTTP/1.1 200 OK { "type": "timeinterval", "id": "431", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", @@ -1867,7 +1878,7 @@ The properties of each endpoint type are listed below. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints?pageSize=2&page=1 ``` @@ -1884,8 +1895,8 @@ HTTP/1.1 200 OK { "type": "ivr", "id": "83066", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:38:00.000+0000", "shortNumber": "001", "name": "Main IVR", @@ -1894,8 +1905,8 @@ HTTP/1.1 200 OK { "type": "phone", "id": "101", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "shortNumber": "102", "name": "John Simmonds", @@ -1906,7 +1917,7 @@ HTTP/1.1 200 OK "voicemailEnabled": true } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=1&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints?pageSize=1&page=2" } ``` @@ -1922,7 +1933,7 @@ HTTP/1.1 200 OK ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101 +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101 ``` @@ -1934,8 +1945,8 @@ HTTP/1.1 200 OK { "type": "phone", "id": "101", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "shortNumber": "102", "name": "John Simmonds", @@ -1945,8 +1956,8 @@ HTTP/1.1 200 OK "callRecording": "ALWAYS", "voicemailEnabled": true, "links": { - "sip": "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/sip", - "voicemail": "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/voicemail" + "sip": "http://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101/sip", + "voicemail": "http://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101/voicemail" } } ``` @@ -1963,7 +1974,7 @@ you might want to get all extensions or all ivrs that are on the account. In thi ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints?type=phone ``` @@ -1979,15 +1990,15 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone { "type": "phone", "id": "83069", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-01-24T17:12:05Z", "shortNumber": "100", "name": "Fred Muteesa", "timeout": 30, "callWaiting": false, "callRecording": "OFF", - "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/49610", + "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/49610", "voicemailSettings": { "autoAnswer": false, "pin": "0000", @@ -1996,15 +2007,15 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone "allowReview": false }, "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83069/phonestatus" + "sip": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/phonestatus" } },{ "type": "phone", "id": "89937", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-15T19:43:10Z", "shortNumber": "102", "name": "Fred", @@ -2019,9 +2030,9 @@ GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?type=phone "allowReview": false }, "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + "sip": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/phonestatus" } } ] @@ -2042,10 +2053,11 @@ Depending on what property of the end point you want to update, you will need to -```json -PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 - +``` +PUT https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83066 +``` +```json { "type":"ivr", "id":"83066", @@ -2053,7 +2065,6 @@ PUT https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 "timeout":5, "shortNumber":500 } - ``` @@ -2065,8 +2076,8 @@ HTTP/1.1 200 OK { "type": "ivr", "id": "83066", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83066", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-01-24T16:43:22Z", "shortNumber": "500", "name": "Fred-lab-ivr2", @@ -2087,9 +2098,11 @@ To add an extention or phone type endpoint to an account, you need to send a POS -```json +``` POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints +``` +```json { "callRecording":"OFF", "timeout":30, @@ -2097,7 +2110,6 @@ POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints "shortNumber":"102", "type":"phone" } - ``` @@ -2110,8 +2122,8 @@ HTTP/1.1 200 OK { "type": "phone", "id": "89937", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-15T19:43:10Z", "shortNumber": "102", "name": "Fred", @@ -2126,9 +2138,9 @@ HTTP/1.1 200 OK "allowReview": false }, "links": { - "sip": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/sip", - "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/forwardingrules", - "status": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937/phonestatus" + "sip": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/phonestatus" } } ``` @@ -2146,7 +2158,7 @@ see example below: Example Request ``` -DELETE https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 +DELETE https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83066 ``` @@ -2166,16 +2178,16 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/endpoints/83066 Phone numbers provide a route into the system from outside - they can support calls and optionally SMS messages, where available. Each inbound number is represented by a `did`. -```json exampleRepresentation +```json { "type": "did", "id": "50", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854400", "identifier": "", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", "smsEnabled": true, "smsAllowIncoming": true, "smsNotificationEmail": "support@sipcentric.com", @@ -2183,14 +2195,14 @@ Phone numbers provide a route into the system from outside - they can support ca "faxEnabled": false, "routingRules": [ { - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" },{ - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" },{ - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" } ] } @@ -2229,7 +2241,7 @@ Returns a list of all phone numbers on a customer account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=1 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers?pageSize=2&page=1 ``` @@ -2246,8 +2258,8 @@ HTTP/1.1 200 OK { "type": "did", "id": "47", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854400", "identifier": "Main", @@ -2259,12 +2271,12 @@ HTTP/1.1 200 OK },{ "type": "did", "id": "50", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854411", "identifier": "", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", "smsEnabled": true, "smsAllowIncoming": true, "smsNotificationEmail": "support@sipcentric.com", @@ -2272,19 +2284,19 @@ HTTP/1.1 200 OK "faxEnabled": false, "routingRules": [ { - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" },{ - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" },{ - "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" } ] } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers?pageSize=2&page=2" } ``` @@ -2301,7 +2313,7 @@ Retrieves the instance of a specific phone number. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47 ``` @@ -2313,8 +2325,8 @@ HTTP/1.1 200 OK { "type": "did", "id": "47", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854400", "identifier": "Main", @@ -2340,8 +2352,10 @@ NB: This number should be available in the simwood inventory. you can check Avai ``` -POST https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers +POST https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers +``` +```json { "createFrom":"4-44-113-4037921", "type":"did" @@ -2357,15 +2371,15 @@ HTTP/1.1 200 OK { "type": "did", "id": "94854", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-12T14:11:06Z", "number": "01134037921", "formatted": "0113 403 7921", "smsCapable": false, "faxEnabled": false, "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854/routingrules" } } ``` @@ -2386,21 +2400,23 @@ NB: This phone number should already be added to the account. Please see , addi -```json +``` PUT https://pbx.sipcentric.com/api/v1/customers/{customerId}/phonenumbers/{phonenumberId}/ +``` +```json { "type": "did", "id": "73224", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/{phonenumberId}", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2022-01-06T11:12:46Z", "number": "01134031453", "formatted": "0113 403 1453", "smsCapable": false, "faxEnabled": false, "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/{phonenumberId}/routingrules" + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/{phonenumberId}/routingrules" }, "destination":"89937" } @@ -2415,16 +2431,16 @@ HTTP/1.1 200 OK { "type": "did", "id": "94854", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-12T14:11:06Z", "number": "01134037921", "formatted": "0113 403 7921", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", "smsCapable": false, "faxEnabled": false, "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854/routingrules" } } ``` @@ -2444,22 +2460,23 @@ To un-link or remove the link between a phonenumber and an extension, you need t -```json -PUT https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 +``` +PUT https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854 +``` -Body +```json { "type":"did", "id":"94854", - "uri":"https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent":"https://pbx.sipcentric.com/api/v1/customers/25", + "uri":"https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent":"https://pbx.sipcentric.com/api/v1/customers/99999", "created":"2023-05-12T14:11:06.000Z", "number":"01134037921", "formatted":"0113 403 7921", "smsCapable":false, "faxEnabled":false, - "links":{ - "routingRules":"https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + "links": { + "routingRules":"https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854/routingrules" } } ``` @@ -2473,16 +2490,16 @@ HTTP/1.1 200 OK { "type": "did", "id": "94854", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2023-05-12T14:11:06Z", "number": "01134037921", "formatted": "0113 403 7921", - "destination": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/89937", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", "smsCapable": false, "faxEnabled": false, "links": { - "routingRules": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854/routingrules" + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854/routingrules" } } ``` @@ -2498,7 +2515,7 @@ To delete a number from an accouont, a DELETE request must be made to the instan Example ``` -DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 +DELETE https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854 ``` @@ -2517,7 +2534,7 @@ DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/94854 The Available Numbers sub-resource returns a list of available numbers that can be added to a customer account, represented by a `availablenumber` instance. After listing the available numbers you can add a number to your account see. -```json exampleRepresentation +```json { "type": "availablenumber", "id": "4-44-113-4037921", @@ -2640,12 +2657,12 @@ HTTP/1.1 200 OK Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. -```json exampleRepresentation +```json { "type": "outgoingcallerid", "id": "114", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "07932000000", "allowCalls": false, @@ -2677,7 +2694,7 @@ Lists the IDs which have been approved for use on the account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids +GET https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids ``` @@ -2694,8 +2711,8 @@ HTTP/1.1 200 OK { "type": "outgoingcallerid", "id": "115", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/115", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "Sipcentric", "allowCalls": false, @@ -2703,8 +2720,8 @@ HTTP/1.1 200 OK },{ "type": "outgoingcallerid", "id": "114", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854411", "allowCalls": true, @@ -2727,7 +2744,7 @@ Get the instance of a specific caller ID. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 +GET https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114 ``` @@ -2739,8 +2756,8 @@ HTTP/1.1 200 OK { "type": "outgoingcallerid", "id": "114", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-10T13:37:00.000+0000", "number": "01212854411", "allowCalls": true, @@ -2764,11 +2781,11 @@ HTTP/1.1 200 OK The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. -```json exampleRepresentation +```json { "type": "creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999", "accountType": "PREPAID", "creditRemaining": 19.571 } @@ -2791,7 +2808,7 @@ The credit status sub-resource returns the current call credit status of an acco ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/creditstatus +GET https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus ``` @@ -2802,7 +2819,7 @@ HTTP/1.1 200 OK { "type": "creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", "accountType": "PREPAID", "balance": 19.571 } @@ -2828,8 +2845,8 @@ The call bundles sub-resource contains all bundles which have been added to an a { "type": "customerbundle", "id": "1040", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-01T00:00:00.000+0000", "name": "1000 Mins - UK Local/National", "inclusiveMins": 1000, @@ -2872,7 +2889,7 @@ List all bundles added to an account. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles +GET https://pbx.sipcentric.com/api/v1/customers/99999/callbundles ``` @@ -2889,8 +2906,8 @@ HTTP/1.1 200 OK { "type": "customerbundle", "id": "1040", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-01T00:00:00.000+0000", "name": "1000 Mins - UK Local/National", "inclusiveMins": 1000, @@ -2920,7 +2937,7 @@ Fetches the instance of a specific customer bundle. ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040 +GET https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040 ``` @@ -2931,9 +2948,9 @@ HTTP/1.1 200 OK { "type": "customerbundle", - "id": "1040", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "999999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/999999", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "created": "2014-03-01T00:00:00.000+0000", "name": "1000 Mins - Local/National (Free)", "inclusiveMins": 1000, @@ -2963,13 +2980,13 @@ HTTP/1.1 200 OK The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. -```json exampleRepresentation +```json { "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/9999999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", "postpaid": true, "creditLimit": 50.00, "warningThreshold": 0.00 @@ -2997,7 +3014,7 @@ The call charging sub-resource returns the current call charging plan for an ac ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/callcharging +GET https://pbx.sipcentric.com/api/v1/customers/99999/callcharging ``` @@ -3008,10 +3025,10 @@ HTTP/1.1 200 OK { "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "id": "999999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", "postpaid": true, "creditLimit": 50.00, "warningThreshold": 0.00 @@ -3030,7 +3047,7 @@ HTTP/1.1 200 OK ``` -PUT https://pbx.sipcentric.com/api/v1/customers/25/callcharging +PUT https://pbx.sipcentric.com/api/v1/customers/99999/callcharging ``` @@ -3041,10 +3058,10 @@ HTTP/1.1 200 OK { "type": "customercallcharging", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callcharging", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", - "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/111", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/999999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", "postpaid": true, "creditLimit": 50.00, "warningThreshold": 0.00 @@ -3068,12 +3085,12 @@ HTTP/1.1 200 OK The Permissions sub-resource returns the current customer permissions for an account, represented by a `permissions` instance. -```json exampleRepresentation +```json { "type": "customerpermissions", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "incomingCalls": true, "outgoingCalls": true, "internationalCalls": false, @@ -3106,7 +3123,7 @@ The Permissions sub-resource returns the current customer permissions for an a ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/permissions +GET https://pbx.sipcentric.com/api/v1/customers/99999/permissions ``` @@ -3117,9 +3134,9 @@ HTTP/1.1 200 OK { "type": "customerpermissions", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/permissions", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "incomingCalls": true, "outgoingCalls": true, "internationalCalls": false, @@ -3146,11 +3163,11 @@ HTTP/1.1 200 OK The billing sub-resource returns the current billing configuration and pricing plan for different features, represented by a `billing` instance. -```json exampleRepresentation +```json { "type": "billingaccount", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "paymentsEnabled": false, "providersEnabled": [], "upgradeAllowed": true, @@ -3170,9 +3187,9 @@ The billing sub-resource returns the current billing configuration and pricing "group": 2.00 }, "links": { - "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", - "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", - "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + "invoices": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/estimate" } } ``` @@ -3200,7 +3217,7 @@ The billing sub-resource returns the current billing configuration and pricing ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/billing +GET https://pbx.sipcentric.com/api/v1/customers/99999/billing ``` @@ -3211,8 +3228,8 @@ HTTP/1.1 200 OK { "type": "billingaccount", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/billing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "paymentsEnabled": false, "providersEnabled": [], "upgradeAllowed": true, @@ -3232,9 +3249,9 @@ HTTP/1.1 200 OK "group": 2.00 }, "links": { - "invoices": "https://pbx.sipcentric.com/api/v1/customers/25/billing/invoices", - "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/25/billing/paymentmethods", - "estimate": "https://pbx.sipcentric.com/api/v1/customers/25/billing/estimate" + "invoices": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/estimate" } } ``` @@ -3244,22 +3261,22 @@ HTTP/1.1 200 OK ### Estimates -| Resource Information | | -|:-------------------------------|:-------------------------------------| -| Location | /estimates -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | estimates | -| Additional Formats | None | +| Resource Information | | +| :----------------------------- | :---------- | +| Location | /estimates | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | estimates | +| Additional Formats | None | The Available Charging Plans resource returns a list of charging plans that can be used, represented by a `estimates` instance. This resource is used to set customers price plans. -```json exampleRepresentation +```json { "type": "invoice", "id": "E5", @@ -3291,23 +3308,23 @@ This resource is used to set customers price plans. -| Type: *estimates* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("invoice")
*String* | -| id
*read-only* | The resource estimate id (E5)
*String* | -| uri
*read-only* | URI to get this estimate.
*String* | -| created
*required* | date when this estimate was created
*date* | -| netAmount
*required* | net amount
*float* | -| vatAmount
*requried* | vat charged
*float* | -| total
*read-only* | total charge
*float* | -| lines
*read-only* | array or billable resources
*float* | -| lines
*read-only* | array or billable resources
*array* | -| description
*read-only* | name of resource
*float* | -| unitPrice
*read-only* | the unit price of resrouce
*float* | -| quantity
*read-only* | number of resources
*integer* | -| lineTotal
*read-only* |
*float* | -| usage
*read-only* |whethere resource is usable or not
*boolean* | +| Type: *estimates* | | +| :----------------------------- | :---------------------------------------------------------- | +| **Property** | **Description** | +| type
*required* | The resource type ("invoice").
*String* | +| id
*read-only* | The resource estimate id. (E5)
*String* | +| uri
*read-only* | URI to get this estimate.
*String* | +| created
*required* | Date when this estimate was created.
*date* | +| netAmount
*required* | Net amount.
*float* | +| vatAmount
*requried* | VAT charged.
*float* | +| total
*read-only* | Total charge.
*float* | +| lines
*read-only* | Array or billable resources.
*float* | +| lines
*read-only* | Array or billable resources.
*array* | +| description
*read-only* | Name of resource.
*float* | +| unitPrice
*read-only* | Unit price of resource.
*float* | +| quantity
*read-only* | Number of resources.
*integer* | +| lineTotal
*read-only* | Total of quantity multiplied by unit price.
*float* | +| usage
*read-only* | If this is a usage charge.
*boolean* | #### Get Billing Estimate @@ -3414,24 +3431,24 @@ HTTP/1.1 200 OK ### Limits -| Resource Information | | -|:-------------------------------|:-------------------------------------| +| Resource Information | | +| :----------------------------- | :----------------------------- | | Location | /customers/{customerId}/limits | -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | | JSON Representation(s) | limits | -| Additional Formats | None | +| Additional Formats | None | The limits sub-resource returns the current limits on different features for an account , represented by a `limits` instance. ```json { "type": "customerlimits", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "phone": 50, "group": 10, "queue": 10, @@ -3443,20 +3460,20 @@ The limits sub-resource returns the current limits on different features for an } ``` -| Type: *limits* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*read-only* | The resource type ("customerlimits")
*String* | -| id
*required* | The resource customer id.
*String* | -| uri
*read-only* | URI to get customer limits.
*String* | -| parent
*read-only* | URI of this customer account.
*String* | -| phone
*read-only* | total numbers of phones
*integer* | -| group
*read-only* | total number of groups
*integer* | -| queue
*read-only* | total number of queues
*integer* | -| ivr
*read-only* | total allowed ivrs
*integer* | -| mailbox
*read-only* | totalk mailboxes allowed
*integer* | -| did
*read-only* | total DID's allowed
*integer* | -| channel
*read-only* | total allowed channels
*integer* | +| Type: *limits* | | +| :------------------------- | :--------------------------------------------------- | +| **Property** | **Description** | +| type
*read-only* | The resource type ("customerlimits")
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer limits.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| phone
*read-only* | Limit of extensions.
*integer* | +| group
*read-only* | Limit of groups.
*integer* | +| queue
*read-only* | Limit of queues.
*integer* | +| ivr
*read-only* | Limit of ivrs.
*integer* | +| mailbox
*read-only* | Limit of shared mailboxes.
*integer* | +| did
*read-only* | Limit of incoming numbers.
*integer* | +| channel
*read-only* | Channel limit.
*integer* | #### Get Account Limits @@ -3467,7 +3484,7 @@ The limits sub-resource returns the current limits on different features for an ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/limits +GET https://pbx.sipcentric.com/api/v1/customers/99999/limits ``` @@ -3478,9 +3495,9 @@ HTTP/1.1 200 OK { "type": "customerlimits", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/limits", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "phone": 50, "group": 10, "queue": 10, @@ -3503,18 +3520,18 @@ HTTP/1.1 200 OK | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get),[PUT](#put) | -| JSON Representation(s) | pricing | +| HTTP Method(s) | [GET](#get), [PUT](#put) | +| JSON Representation(s) | Pricing | | Additional Formats | None | -The pricing sub-resource returns the current pricing or cost of different services for an account, represented by a `pricing` instance. +The pricing sub-resource returns the current pricing or cost of different services for an account, represented by a `pricing` instance. ```json { "type": "customerpricing", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/pricing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "phone": 2.00, "virtual": 0.10, "group": 4.00, @@ -3525,19 +3542,19 @@ The pricing sub-resource returns the current pricing or cost of different servi } ``` -| Type: *pricing* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*read-only* | The resource type ("customerpricing")
*String* | -| id
*required* | The resource customer id.
*String* | -| uri
*read-only* | URI to get customer pricing.
*String* | -| parent
*read-only* | URI of this customer account.
*String* | -| phone
*read-only* | price of phone
*float* | -| group
*read-only* | price of groups
*float* | -| queue
*read-only* | price of queues
*float* | -| ivr
*read-only* | price of ivrs
*float* | -| mailbox
*read-only* | price of mailboex
*float* | -| did
*read-only* | price per DID
*float* | +| Type: *pricing* | | +| :------------------------- | :----------------------------------------------------- | +| **Property** | **Description** | +| type
*read-only* | The resource type ("customerpricing").
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer pricing.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| phone
*read-only* | Price per extension.
*float* | +| group
*read-only* | Price per ring group.
*float* | +| queue
*read-only* | Price per call queue.
*float* | +| ivr
*read-only* | Price per IVR.
*float* | +| mailbox
*read-only* | Price per shared mailbox.
*float* | +| did
*read-only* | Price per incoming number.
*float* | #### Get Pricing @@ -3549,7 +3566,7 @@ The pricing sub-resource returns the current pricing or cost of different servi ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/pricing +GET https://pbx.sipcentric.com/api/v1/customers/99999/pricing ``` @@ -3560,9 +3577,9 @@ HTTP/1.1 200 OK { "type": "customerpricing", - "id": "25", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/pricing", - "parent": "https://pbx.sipcentric.com/api/v1/customers/25", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "phone": 2.00, "virtual": 0.10, "group": 4.00, @@ -3585,7 +3602,9 @@ To change the current pricing, please use a PUT as per the below. ``` PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing +``` +```json { "type": "customerpricing", "phone": 7 @@ -3603,23 +3622,23 @@ HTTP/1.1 200 OK ### Linkedusers (Web Users) -| Resource Information | | -|:-------------------------------|:-------------------------------------| +| Resource Information | | +| :----------------------------- | :---------------------------------- | | Location | /customers/{customerId}/linkedusers | -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get), [DELETE](#delete) | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get), [DELETE](#delete) | | JSON Representation(s) | linkedusers | -| Additional Formats | None | +| Additional Formats | None | The Linked Users sub-resource returns the users that are linked to an account, represented by a `linkedusers` instance. -```json exampleRepresentation +```json { "type": "linkeduser", "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", "email": "Fred.muteesa+Test@simwood.com", @@ -3633,22 +3652,22 @@ The Linked Users sub-resource returns the users that are linked to an account, } ``` -| Type: *linkedusers* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("customerlinkedusers")
*String* | -| id
*read-only* | The resource linkeduser id
*String* | -| uri
*read-only* | URI to get this linkeduser.
*String* | -| created
*read-only* | date and timestamp when this user was created
*date* | -| userId
*read-only* | Id of this user
*string* | -| email
*read-only* | email of this user
*string* | -| username
*read-only* | username for this user
*string* | -| accessLevel
*read-only* | this user's access level
*string* | -| enabled
*read-only* | enabled or not
*bolean* | -| pending
*read-only* | price per DID
*float* | -| acceptedInvite
*read-only* | price per DID
*float* | -| owner
*read-only* | whether this user is the account owner or not
*float* | -| recordingAccess
*read-only* | can access all records
*float* | +| Type: *linkedusers* | | +| :--------------------------------- | :------------------------------------------------------------- | +| **Property** | **Description** | +| type
*required* | The resource type ("customerlinkedusers").
*String* | +| id
*read-only* | The resource linkeduser id.
*String* | +| uri
*read-only* | URI to get this linkeduser.
*String* | +| created
*read-only* | Timestamp for this user's creation.
*date* | +| userId
*read-only* | ID for this user.
*string* | +| email
*read-only* | Email for this user.
*string* | +| username
*read-only* | Username for this user.
*string* | +| accessLevel
*read-only* | This user's access level.
*string* | +| enabled
*read-only* | Whether the user is enabled or not.
*bolean* | +| pending
*read-only* | If the user is still pending activation.
*float* | +| acceptedInvite
*read-only* | If the user has accepted the invitation or not.
*float* | +| owner
*read-only* | Whether this user is the account owner.
*float* | +| recordingAccess
*read-only* | Level of call recording access.
*float* | #### Get Linkedusers @@ -3660,7 +3679,7 @@ The Linked Users sub-resource returns the users that are linked to an account, ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers +GET https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers ``` @@ -3677,7 +3696,7 @@ HTTP/1.1 200 OK { "type": "linkeduser", "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", "email": "Fred.muteesa+Test@simwood.com", @@ -3704,7 +3723,7 @@ HTTP/1.1 200 OK ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180 +GET https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180 ``` @@ -3716,7 +3735,7 @@ HTTP/1.1 200 OK { "type": "linkeduser", "id": "35180", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180", "created": "2023-01-24T13:24:12Z", "userId": "27068", "email": "Fred.muteesa+Test@simwood.com", @@ -3740,7 +3759,7 @@ HTTP/1.1 200 OK ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/me +GET https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/me ``` @@ -3794,7 +3813,7 @@ This resource is used to set customers price plans. -```json exampleRepresentation +```json { "type": "chargingplan", "id": "1", @@ -3810,17 +3829,17 @@ This resource is used to set customers price plans. -| Type: *chargingplans* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("chargingplans")
*String* | -| id
*read-only* | The resource chargingplans id
*String* | -| uri
*read-only* | URI to get this chargingplan.
*String* | -| currency
*required* | The currency for this charging plan("GBP")
*date* | -| domainCostMinute
*required* |
*float* | -| roundSeconds
*requried* |
*integer* | -| minDuration
*read-only* | minimum duration
*integer* | -| minCharge
*read-only* | what is the charge per minute
*float* | +| Type: *chargingplans* | | +| :--------------------------------- | :-------------------------------------------------------- | +| **Property** | **Description** | +| type
*required* | The resource type ("chargingplans").
*String* | +| id
*read-only* | The resource chargingplans id.
*String* | +| uri
*read-only* | URI to get this chargingplan.
*String* | +| currency
*required* | The currency for this charging plan("GBP").
*date* | +| domainCostMinute
*required* | Per minute cost for on-net calls.
*float* | +| roundSeconds
*requried* | How many seconds the call rounds to.
*integer* | +| minDuration
*read-only* | The minimum duration for calls.
*integer* | +| minCharge
*read-only* | Minimum call charge.
*float* | @@ -3894,9 +3913,9 @@ HTTP/1.1 200 OK { "type": "chargingplan", - "id": "8", - "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/8", - "name": "Partner L2", + "id": "999", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/999", + "name": "Test Chargingplan", "currency": "GBP", "domainCostMinute": 0.000, "roundSeconds": 1, @@ -3968,9 +3987,6 @@ HTTP/1.1 200 OK -**Explanation:** -From the above results we see that the total Duration for account 5 is 108.0 seconds. on the Web ui this will be represented as *1 minute and 48 seconds* - #### Total cost @@ -4013,10 +4029,6 @@ HTTP/1.1 200 OK -**Explanation:** -This request has returned the current total cost as £0.00 - - #### Inbound Vs Outbound Duration @@ -4064,9 +4076,6 @@ HTTP/1.1 200 OK -**Explanation:** -From the above response we can see that inbound has 0 seconds and Outbound has 108.0 which gives us a total of 108.0 seconds - #### Get Duration by Extension This example will show us the total number of seconds consumed by exach extension. This is further categorized by inbound and outbound duration. @@ -4124,11 +4133,6 @@ HTTP/1.1 200 OK ``` -**Explanation:** -In the above example, we see that this week has had three exentions making or receiving calls. -Fred, Ivan, Jared - - #### Get Calls by Extensions The request would give us the number of calls made or received by each extension in the account. @@ -4517,7 +4521,7 @@ GET https://pbx.sipcentric.com/api/v1/tokengenerator You can now use this token to get a call recording using the `tokenid` parameter in the GET Request ``` -https://pbx.sipcentric.com/api/v1/customers/25/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16 +https://pbx.sipcentric.com/api/v1/customers/99999/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16 ``` Anyone that tried to use the request again will get a 401 Unauthorized. This prevents replay attacks from getting any data. diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 9c31b72..69ac131 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -18,13 +18,13 @@ services. The API is the preferred way to configure your Simwood services. Everything in the portal can also be configured via the API (and in some cases the API offers some additional functionality) Our portal is based on the API, and everything you can do in the portal you can do through the API in your own -code. We’ve deliberately made it this way. The only exception to this is the authentication elements of the +code. We've deliberately made it this way. The only exception to this is the authentication elements of the portal, as using your API key to log in on the web would be cumbersome. ### Databases -As before, many queries are made against MySQL although we have dedicated servers for the API’s use. +As before, many queries are made against MySQL although we have dedicated servers for the API's use. These are built for queries and are slaves of masters. We can build additional query servers sideways as required. Writes are, of course, made against the masters. Increasingly, API requests are served directly from our underlying REDIS ram-based data stores where possible. @@ -32,7 +32,7 @@ our underlying REDIS ram-based data stores where possible. This API introduces multiple layers in between the above for performance and scale: #### Beanstalkd Queues We use Beanstalkd a lot for internal messaging. In this API where a request is non-trivial and involves -other processes, we’ll simply queue a job. +other processes, we'll simply queue a job. #### REDIS REDIS replaced memcached as our caching data store, and is used for much more as it supports a number of advanced data structures facilitating vastly improved monitoring and real-time @@ -48,7 +48,7 @@ release of a job to a daemon is sub-millisecond giving the queueing the performa requests. Most complicated jobs involve multiple daemons working through a sequence of queues. ## Basic Operations -The Simwood API can be found at the following URI; +The Simwood API can be found at the following URI: https://api.simwood.com/v3/ Please note that TLS v1.1 or Higher is Mandatory for all requests. @@ -64,14 +64,17 @@ https://api.simwood.com/v3/tools/myip - will return your IP address as seen by t https://api.simwood.com/v3/tools/time - will return a timestamp from the API ### JSON Output Format -You’ll see that in both above cases the output is JSON, e.g: +You'll see that in both above cases the output is JSON, e.g: -``` -{"timestamp":1388748052,"rfc":"Fri, 03 Jan 2014 11:20:52 +0000"} +```json +{ + "timestamp": 1388748052, + "rfc": "Fri, 03 Jan 2014 11:20:52 +0000" +} ``` -JSON ("JavaScript Object Notation") is used as it’s a lightweight format designed for exchange of data +JSON ("JavaScript Object Notation") is used as it's a lightweight format designed for exchange of data structures which has an additional advantage of being relatively human readable. All modern languages such as PHP, ASP, .net, Node, Perl etc can handle JSON structures and convert to/from their native objects or arrays easily making it the ideal choice for REST APIs. @@ -79,7 +82,7 @@ arrays easily making it the ideal choice for REST APIs. JSON is designed to be machine-readable and as such is sent with minimal whitespace by default however when developing it is often useful to see the output in a more human-friendly format, you can achieve this simply by appending `"?pretty=true"` to any endpoint e.g https://api.simwood.com/v3/tools/time?pretty=true -would look like this; +would look like this: ```json { @@ -93,9 +96,9 @@ Most commands are linked to an account and therefore require authentication. We use standard Basic Authentication, i.e. your client makes a request, we respond with a 401 response code, your client replies with the API username and password included. Your API username and password were provided at the time of creating your Simwood account, if you do not -have these please contact our support team and we’ll be happy to provide you with them. +have these please contact our support team and we'll be happy to provide you with them. -Note that, at present; +Note that, at present: - Your API username and password is not the same as your portal login details - Your API password is designed to be used programatically, and is typically not memorable @@ -103,15 +106,15 @@ Note that, at present; - You cannot, currently, change your API username or password - although our support team are happy to do so if required (e.g. if your details are lost or you have reason to believe they are compromised) -If you pull up an example URL in your browser it’ll do this for you. For your code, different development -languages will tackle this in different ways but most will ‘just deal with it’ automatically for you. +If you pull up an example URL in your browser it'll do this for you. For your code, different development +languages will tackle this in different ways but most will ‘just deal with it' automatically for you. cURL for example, will just take the username and password as parameters, e.g.: ``` curl --user name:password https://api.simwood.com/v3/… ``` -PHP’s cURL implementation is very similar in that you’d set CURLOPT_USERPWD with [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php). +PHP's cURL implementation is very similar in that you'd set CURLOPT_USERPWD with [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php). An example authenticated GET request is: ``` @@ -123,11 +126,16 @@ will need to be replaced with account ID (typically a six digit number)* Which would return the following -``` -[{"balance":"12.32","currency":"GBP"}] +```json +[ + { + "balance": "12.32", + "currency": "GBP" + } +] ``` -Adding `?pretty=true` to the end of the URL would give you the same information in the following format; +Adding `?pretty=true` to the end of the URL would give you the same information in the following format: ```json [ { @@ -137,15 +145,12 @@ Adding `?pretty=true` to the end of the URL would give you the same information ] ``` -Both are treated equally by a JSON parser, and are syntactically valid, however the ‘pretty-printed’ version +Both are treated equally by a JSON parser, and are syntactically valid, however the ‘pretty-printed' version may be useful for debugging. -Simwood - - ### PUT and DELETE requests In the spirit of being REST-ful, many URLs can be acted upon with different methods. The URL does not -change, only the HTTP method used against it. One example of this is number configuration, for example; +change, only the HTTP method used against it. One example of this is number configuration, for example: ``` https://api.simwood.com/v3/numbers/{ACCOUNT}/allocated/{NUMBER} @@ -182,7 +187,7 @@ https://api.simwood.com/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config will just remove the configuration, leaving the number on your account Setting the method is language specific and `PUT` and `DELETE` cannot be easily replicated in a browser. Almost -all environments/browsers will default to GET so the chances are if it doesn’t work as you expect you are +all environments/browsers will default to GET so the chances are if it doesn't work as you expect you are using the `GET` method. For development languages which do not permit all HTTP methods to be used you can pass a hidden parameter named _method in an HTTP POST or GET and set the method to use in there. @@ -217,19 +222,20 @@ The output from such a POST request (which requests a report) will typically be "account": "ACCOUNT", "format": "json", "hash": "4e591630fedf4aa149db9874fb33fe23", - "link": "\/v3\/files\/ACCOUNT\/4e591630fedf4aa149db9874fb33fe23"} + "link": "\/v3\/files\/ACCOUNT\/4e591630fedf4aa149db9874fb33fe23" +} ``` -You will note that this is not in fact a summary of today’s charges. It is a hash that uniquely identifies that +You will note that this is not in fact a summary of today's charges. It is a hash that uniquely identifies that report and a link to it. As the return suggests, you can retrieve the actual results with a GET request to ``` -https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23. +https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23 ``` -#### But don’t worry... +#### But don't worry... Whilst is is important to understand the effect a given request method will have, we are somewhat relaxed in our interpretation of them where possible. DELETE is always DELETE with no alternative but we will accept a POST instead of a PUT and a GET instead of a POST where possible. You should not assume we will, and @@ -238,7 +244,7 @@ example. #### Report De-duplication As described above, when you request a report the return will just contain a link to the results. That link will -be unique to that specific report, i.e. in the above example the hash for today’s summary will be the same with +be unique to that specific report, i.e. in the above example the hash for today's summary will be the same with every request, but only every request `today`. Tomorrow will generate a different hash. If you make multiple requests for the same report before you retrieve it, duplicates will simply be ignored and the report will only be run once. @@ -257,7 +263,7 @@ hash. A different report for today or the same report for tomorrow will give dif different numbers will generate different hashes. Further, de-duplication will only apply where previous results have not been retrieved. -The intention here is to protect the system from the coder who wishes to request a year’s CDRs every second. +The intention here is to protect the system from the coder who wishes to request a year's CDRs every second. He can, but all requests other than the first will be ignored until he retrieves the results. This rather extreme example is actually real and was a consequence of the way the v2 API paginated results and required clients to step through them. More than a few customer implementations reached the end of the results and went @@ -271,10 +277,10 @@ https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23 ``` This URL can be polled at a sensible interval as it will simply return a 204 No Content until the report exists. Once the report does exist, it can be downloaded only once and then will be automatically deleted. -To negate the need for polling, clients may instead wish to specify a ‘callback’ URL with their request. This -should be POSTed as a variable called ‘callback’. The response to the request will be identical as without it but +To negate the need for polling, clients may instead wish to specify a ‘callback' URL with their request. This +should be POSTed as a variable called ‘callback'. The response to the request will be identical as without it but on successful generation of the report we will make a POST to the URL provided. This will contain a single -HTTP POST variable call ‘payload’ which will contain the report hash in JSON format, e.g.: +HTTP POST variable call ‘payload' which will contain the report hash in JSON format, e.g.: ```json { @@ -291,7 +297,7 @@ Dates are always expressed in MySQL format (YYYY-MM-DD hh:mm:ss), e.g. 2012-01-0 #### File (Report Output) Handling Unlike many APIs the Simwood API is asynchronous when requesting some complex reports to improve performance (this is discussed in more detail above) and some POST requests will result in a small response -containing a hash and ‘link’ to a file e.g. +containing a hash and ‘link' to a file e.g. ```json { "mode": "vsind", @@ -304,7 +310,7 @@ containing a hash and ‘link’ to a file e.g. } ``` -The functions below are used to retrieve these; +The functions below are used to retrieve these: `` /v3/files/{ACCOUNT} @@ -337,10 +343,10 @@ The functions below are used to retrieve these; ## API Endpoints If the above has all made sense, you should need little more than a list of the available end-points and the -HTTP methods they support to get going. This follows and you’ll quickly observe they are hierarchical and +HTTP methods they support to get going. This follows and you'll quickly observe they are hierarchical and hopefully consistent. The method shown indicates behaviour as described earlier. -Each endpoint is documented below in the following format; +Each endpoint is documented below in the following format: ``/v3/URL`` @@ -351,17 +357,17 @@ Each endpoint is documented below in the following format; | | *parameter* - An example GET / POST or PUT parameter | | | *anotherparam* - Another parameter to be sent by POST | -`Please Note ` - Where example responses are shown in this documentation they may be reformatted to be +**Please Note** - Where example responses are shown in this documentation they may be reformatted to be more easily human-readable, the actual response will have escaped slashes (e.g. / replaced with \/) and not include any excess white space. | |The following conventions are used in describing the URL or other parameters| |:--------|:----------------------------------------------------------------------| |{ACCOUNT} | Where a word is capitalised and enclosed by curly braces { } it must be replaced with the appropriate information e.g. {ACCOUNT} or {IP} | -| [ on \| off ] | Where two or more words are separated by the pipe character \| and enclosed within square brackets [ ] these are ‘either or’ options. e.g. a url with the form /latest/[1\|5\|10] allows you to specify any of the following 3 URLs;
/latest/1
/latest/5
/latest/10
Arbitrary values (e.g. /latest/15) are not supported | +| [ on \| off ] | Where two or more words are separated by the pipe character \| and enclosed within square brackets [ ] these are ‘either or' options. e.g. a url with the form /latest/[1\|5\|10] allows you to specify any of the following 3 URLs:
/latest/1
/latest/5
/latest/10
Arbitrary values (e.g. /latest/15) are not supported | | URLs | The URLs are shown without the leading https://api.simwood.com/ which must be inserted before the /v3/ when making any API call. | | paramname | Parameters are shown in italics, these are passed by GET, POST or PUT in the request and do not form part of the URI (except in the case of the GET request, when they are part of the query string after the ? mark) | -| paramname[] | Parameters with square brackets at the end are different and can be thought of as Array Parameters. These can be passed multiple times but even if only one item is being included you must include the [] on the end. For compatibility with some languages (e.g. PHP with Curl) an integer value can be between the square brackets e.g the following two examples are equivalent;
`?param[]=apple¶m[]=orange¶m[]=pear`
`?param[0]=apple¶m[1]=orange¶m[2]=pear` | +| paramname[] | Parameters with square brackets at the end are different and can be thought of as Array Parameters. These can be passed multiple times but even if only one item is being included you must include the [] on the end. For compatibility with some languages (e.g. PHP with Curl) an integer value can be between the square brackets e.g the following two examples are equivalent:
`?param[]=apple¶m[]=orange¶m[]=pear`
`?param[0]=apple¶m[1]=orange¶m[2]=pear` | ## Tools @@ -369,7 +375,7 @@ The following tools are made available without authentication to help integrate ### IP Address Your IP address, as seen by the Simwood API service ``` -curl https://api.simwood.com/v3/tools/myip +https://api.simwood.com/v3/tools/myip ``` | Method | Description | | :----- | :---------------------------------------------------------- | @@ -378,7 +384,7 @@ curl https://api.simwood.com/v3/tools/myip ### Time The current server timestamp ``` -curl https://api.simwood.com/v3/tools/time +https://api.simwood.com/v3/tools/time ``` | Method | Description | | :----- | :---------------------------- | @@ -407,7 +413,7 @@ Timestamp: 2023-03-14 21:53:44 HTTP Request Method: GET API Request Method: GET == Query String ======================================== -Your query string contained 2 elements; +Your query string contained 2 elements: test => 1 pretty => true == HTTP Post Vars ===================================== @@ -430,7 +436,7 @@ Simwood API v3 http://mirror.simwood.com/pdfs/APIv3.pdf -Your account will be one of the following four types; `developer, startup, virtual_interconnect, or managed_interconnect`, each have different commercials but are functionally identical. All new accounts start off as ‘Developer’, we encourage you to move to ‘Start-Up’ for production use, and to consider ‘Virtual Interconnect’ or ‘Managed Interconnect’ as your requirements evolve. +Your account will be one of the following four types: `developer, startup, virtual_interconnect, or managed_interconnect`, each have different commercials but are functionally identical. All new accounts start off as ‘Developer', we encourage you to move to ‘Start-Up' for production use, and to consider ‘Virtual Interconnect' or ‘Managed Interconnect' as your requirements evolve. The differences between these account types can be found in the [Simwood Account Pricing](https://cdn.simwood.com/docs/simwood_account_pricing.pdf) document. @@ -440,7 +446,7 @@ The differences between these account types can be found in the [Simwood Account | Method | Description | | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Get your current account type, and limitations Account type will be one of the following; developer, startup, virtual_interconnect, managed_interconnect | +| GET | Get your current account type, and limitations Account type will be one of the following: developer, startup, virtual_interconnect, managed_interconnect | @@ -660,7 +666,7 @@ You can set an amount at which you will receive a notification (configured via t /v3/accounts/{ACCOUNT}/prepay/balance/locked ``` -We provide the ability to ‘lock’ a portion of your balance to make it unavailable to spend. i.e. you can specify the balance at which we’ll treat your account as ‘out of credit’ and therefore kill calls in progress. +We provide the ability to ‘lock' a portion of your balance to make it unavailable to spend. i.e. you can specify the balance at which we'll treat your account as ‘out of credit' and therefore kill calls in progress. This is normally zero but the balance locking facility enables customers to keep large credit balances without risking the entire amount in the event that they, or a customer, suffer a compromise. @@ -671,7 +677,7 @@ You can set alerts based on the *available* balance (i.e. balance-locked balance | Method | Description | | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | - | GET | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | + | GET | Returns the ‘locked' balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | | PUT | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent. | | | *balance* The amount to be protected. | | DELETE | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | @@ -696,7 +702,7 @@ You can set alerts based on the *available* balance (i.e. balance-locked balance -**NB** *The above ‘locked balance’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account.* +**NB** *The above ‘locked balance' function is provided on a ‘best-efforts' basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account.* ### Termination Rate Functions @@ -707,7 +713,7 @@ You can set alerts based on the *available* balance (i.e. balance-locked balance /v3/accounts/{ACCOUNT}/rates/tariffs ``` -Some account types have more than one available tariff or rate deck, these can be viewed as follows where this is applicable to your account; +Some account types have more than one available tariff or rate deck, these can be viewed as follows where this is applicable to your account: @@ -753,7 +759,7 @@ Some account types have more than one available tariff or rate deck, these can b /v3/accounts/{ACCOUNT}/rates/csv/[default|silver|platinum|gold|name] ``` -Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API; +Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API: @@ -776,7 +782,7 @@ Effective: 2023-03-10 -**NB: The options silver, platinum and gold are only for ‘legacy’ or ‘startup’ account types with multiple rate decks. Virtual Interconnect and Managed Interconnect customers should use default or the file name provided from the above query** +**NB: The options silver, platinum and gold are only for ‘legacy' or ‘startup' account types with multiple rate decks. Virtual Interconnect and Managed Interconnect customers should use default or the file name provided from the above query** #### Destination Lookup ``` @@ -869,7 +875,7 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon | Method | Description | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET / POST | Request an inbound or outbound summary report by KEY (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | +| GET / POST | Request an inbound or outbound summary report by KEY (see below). If ‘in' or ‘out' is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter' parameter) or, preferred, as a JSON object in the request | | | *date_start* [Optional] specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | | | *limit* [Optional] specify limit of results to return, default 9999 | | | *sort* [Optional] Key to sort by | @@ -959,9 +965,9 @@ Some notifications can now (as of v3.15) be received via Webhooks, for more info | Method | Description | | :----- | :--------------------------------------------------------------------------------------------------------------------------------- | | GET | Shows all configured recipients of notifications of {TYPE} using {method} | -| :-- | *method* is one of **email** or **sms** | +| | *method* is one of **email** or **sms** | | POST | Add a new notification recipient to receive notifications of {TYPE} using {METHOD}. Returns a hash corresponding to this recipient | -| :-- | *destination* eMail address or Mobile Number (in E164 format) of the recipient. | +| | *destination* eMail address or Mobile Number (in E164 format) of the recipient. | ``` @@ -974,7 +980,7 @@ Some notifications can now (as of v3.15) be received via Webhooks, for more info | DELETE | Deletes this recipient | -The {HASH} referred to above can be generated locally and is simply an md5()’d version of the notification address. This is used simply to avoid potential url encoding issues. +The {HASH} referred to above can be generated locally and is simply an md5()'d version of the notification address. This is used simply to avoid potential url encoding issues. NB **SMS** notification requires credit balance, sent messages will be deducted from your usual credit. @@ -1076,8 +1082,8 @@ Customers with a dedicated channel allocation can manage this allocation, splitt ```json { - "limit_concurrent_in": 10, - "limit_concurrent_out": 20 + "limit_concurrent_in": 10, + "limit_concurrent_out": 20 } ``` @@ -1241,7 +1247,7 @@ Customers with a dedicated channel allocation can manage this allocation, splitt **As of version 3.15 this information is now also able to be pushed directly to you via Webhooks, for more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** -The above example shows many calls in progress to the UK, along with two to Mexico (MX) and one to Spain (ES) - calls are grouped both by destination (keyed by a unique numeric identifier for that destination) in then "calls" group and by country in "countries" - this makes it simple to alert, for example, if there are any more than a predefined number of calls to any country you don’t expect. +The above example shows many calls in progress to the UK, along with two to Mexico (MX) and one to Spain (ES) - calls are grouped both by destination (keyed by a unique numeric identifier for that destination) in then "calls" group and by country in "countries" - this makes it simple to alert, for example, if there are any more than a predefined number of calls to any country you don't expect. See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/** for some examples of how this data can be used to help protect you against fraud and monitor your VoIP traffic. @@ -1303,7 +1309,7 @@ In addition to the CDR Reports (above) you can retrieve any CDRs from the last t | | *limit* Optionally specify limit of results to return, default 500 | | | *start* Optional offset to start from (for pagination) | | | *filter* Object of "search_key" => "value" e.g. {"trunk": "930000- TEST"} would return CDRs only for the trunk named "930000- TEST". | -| | At present you can filter only on the following values, more will be added in the future; **from, to, toISO, trunk, tag** | +| | At present you can filter only on the following values, more will be added in the future: **from, to, toISO, trunk, tag** | ``` /v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD} @@ -1438,8 +1444,8 @@ The "L001" trunk is your default **IP-Authenticated** trunk and cannot be rename |:--|:--| |GET | Request information on specified {TRUNK} | | PUT | Create new trunk {TRUNK}| -||NB for an ‘auth’ trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions) or (if additional optional configuration parameters specified, see overleaf) Update existing {TRUNK} settings such as channel and rate limits.| -||When creating a new trunk, the **type** can be one of; **IP** create an IP-authenticated Trunk or **auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| +||NB for an ‘auth' trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions) or (if additional optional configuration parameters specified, see overleaf) Update existing {TRUNK} settings such as channel and rate limits.| +||When creating a new trunk, the **type** can be one of: **IP** create an IP-authenticated Trunk or **auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| | DELETE | Delete trunk {TRUNK} **NB the default trunk {ACCOUNT}-L001 cannot be deleted** | Newly created trunks are available for use immediately although, at times, may not show in the outbound trunk list for a short time. @@ -1494,7 +1500,7 @@ Each trunk can have its own balance, this allows you to manage the spend of indi | | *balance* Sets the balance of the trunk to balance. | | | **-or-** | | | *adjust* Adjust the trunk balance by the amount shown, use negative amounts to decrement the balance. | -| DELETE | Remove the balance from trunk {TRUNK} **NB The trunk will function as before, without it’s own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)** | +| DELETE | Remove the balance from trunk {TRUNK} **NB The trunk will function as before, without it's own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)** | **The trunk balance feature is provided for convenience and is not a substitute for your own billing and credit control procedures. Simwood will not be liable for any calls made on a trunk when its trunk-specific balance is depleted for any reason.** @@ -1550,7 +1556,7 @@ As with your account you can also view realtime "in progress" information on a p -Where a trunk has a balance the three additional elements will be present which have the same meaning as in your account snapshot but pertain only to the TRUNK specified; +Where a trunk has a balance the three additional elements will be present which have the same meaning as in your account snapshot but pertain only to the TRUNK specified: **balance, percent_available, and approx_seconds_remaining** @@ -1623,14 +1629,14 @@ is to reset the password using the above functionality. Please keep your passwor ### Outbound Destination Prefix ACLs Not to be confused with IP ACLs (to determine which IPs can make outbound calls on a particular trunk) Destination Prefix ACLs allow you to limit access on a per-account of per-trunk basis to certain destinations. -The ACL is specified in a JSON-encoded object as follows; +The ACL is specified in a JSON-encoded object as follows: | Variable | Description | | :------- | :-------------------------------------------- | | *allow* | Array Allowed Prefixes e.g. [441,442,443,448] | | *deny* | Array Denied Prefixes e.g. [44870] | -This would be encoded in JSON as follows; +This would be encoded in JSON as follows: ```json { @@ -1664,16 +1670,16 @@ Please note: | Method | Description | | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | Retrieve active ACL on your account or trunk as specified | -| PUT | Replace active ACL with the JSON object PUT. **The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’** | +| PUT | Replace active ACL with the JSON object PUT. **The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload'** | | DELETE | Remove the ACL associated with the account or trunk **Please note that the default is to allow access to ALL destinations without restriction - please ensure this is what you want.** | -Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE; +Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE: **X-Reason: 447700900123 matches trunk do not route 447** **X-Reason: 449098790000 matches customer do not route 449** Either one of these may have (cached) appended where the number has been blocked more than once in the last 60s, in such case the prefix may not be shown. -**NB** The above ‘destination acl’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account. +**NB** The above ‘destination acl' function is provided on a ‘best-efforts' basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account. ### Trunk Routing Configuration It is now possible to set a trunk-level routing configuration which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls for a group of numbers to one destination, and another group of numbers to a different destination. @@ -1693,7 +1699,7 @@ For full syntax and available options please refer to [Number Routing Configurat ### Bulk Number Association As detailed below, inbound numbers can be associated with a trunk either for billing purposes only, or to make use of its additional controls and/or routing configuration (where one does not exist on the number itself). These associations can be created individually by updating each number as required, or where multiple numbers are to be associated with the same trunk, it can be performed in a single request using the following endpoint. -**NB** If a number has its own specific routing configuration, then any trunk association defined in the ‘options’ block will continue to take priority. +**NB** If a number has its own specific routing configuration, then any trunk association defined in the ‘options' block will continue to take priority. ``` /v3/voice/{ACCOUNT}/trunks/{TRUNK}/numbers @@ -1729,7 +1735,7 @@ As detailed below, inbound numbers can be associated with a trunk either for bil When associating numbers to a trunk, any individual routing configuration currently set on those numbers will need to be removed if your intention is for the configuration of the newly associated trunk to be followed. You -can do this for each number individually using the number’s own configuration endpoint, or alternatively, if you +can do this for each number individually using the number's own configuration endpoint, or alternatively, if you wish to remove all number-level configuration at the same time as associating with the trunk, you can include the optional force property: ```json @@ -1750,7 +1756,7 @@ the optional force property: You can access your outbound SIP rates from any* standard BT landline using our shared IDA code **12940**. Access is restricted to authorised CLIs. -IDA users are managed much like trunks (see above), each number added automatically creates a ‘trunk’ in the form {ACCOUNT}-IDA01xxxxxxxxx, you will see these identifiers as the trunk in your CDRs and the same settings can be applied as to trunks (see above) +IDA users are managed much like trunks (see above), each number added automatically creates a ‘trunk' in the form {ACCOUNT}-IDA01xxxxxxxxx, you will see these identifiers as the trunk in your CDRs and the same settings can be applied as to trunks (see above) ``` /v3/voice/{ACCOUNT}/ida @@ -1773,7 +1779,7 @@ IDA users are managed much like trunks (see above), each number added automatica Users making calls using the IDA service should dial the full number prefixed with 12940 e.g. to call 029 2120 2120 you would dial **1294002921202120** -1. At present you cannot associate more than one CLI with a single IDA ‘trunk’ +1. At present you cannot associate more than one CLI with a single IDA ‘trunk' 2. If another Simwood customer has enabled a CLI for the IDA service you will not be able to associate the same CLI with your own account. @@ -1836,7 +1842,7 @@ Virtual Interconnect - Inbound customers using their own IDA codes should not us | Method | Description | | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Returns 1,10 or 100 numbers available for allocation matching the pattern specified.One of all, gold, or standard should be specified in the URL;*all* returns all available numbers matching *pattern* **gold** returns only gold numbers matching *pattern* *standard* returns only non-gold numbers matching *pattern* | +| GET | Returns 1,10 or 100 numbers available for allocation matching the pattern specified.One of all, gold, or standard should be specified in the URL:*all* returns all available numbers matching *pattern* **gold** returns only gold numbers matching *pattern* *standard* returns only non-gold numbers matching *pattern* | | | *pattern* Search for numbers matching specified pattern (can use wildcards e.g \*203\*) **NB** For backward compatibility, please note that if country_code is not set, a search for 4420\* and 20\* are identical and are assumed to be UK numbers (without the leading 0). Similarly, a search for 1212\* will be assumed to be the UK (0121 2\*), NOT the USA 1-212. | | | *country_code* [Optional] country code, currently only one of [1\|44] Defaults to 44 for UK numbering, use 1 for USA numbering. | @@ -1939,7 +1945,7 @@ When a new configuration is provided this will take precedence over any existing | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | Return configuration information on allocated {NUMBER} | | PUT | Replace active configuration for {NUMBER} with the JSON object PUT. | -| | The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’ | +| | The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload' | | DELETE | De-configure the configuration of {NUMBER} **NB** if configuration is still present on the /voice endpoint, it will be used | @@ -2088,7 +2094,7 @@ Per number configuration options (detailed above) apply to the number at all tim ```json { - "meta": [] + "meta": [] } ``` The *meta* block contains arbitrary metadata that you want to associate with the number. @@ -2105,7 +2111,7 @@ The following options can be set on a per-number basis, they apply to the entire |*enabled*|[true\|false]|Allows number to be disabled [false] without removing the configuration.|Default [true]| |*block_payphone* | [true\|false] | Prevents inbound calls originating from payphones |Default [false]| |*acr*|[true\|false]|Apply ACR to this number. ACR Prevents calls originating from Withheld numbers reaching this number. Withheld callers will be diverted to a recorded announcement.|Default [false]| -|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block.

You can also configure this using the endpoint /v3/numbers/{ACCOUNT}/allocated/ {NUMBER}/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| +|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg' routing block.

You can also configure this using the endpoint /v3/numbers/{ACCOUNT}/allocated/ {NUMBER}/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| #### **$.. Chargeable Options** @@ -2114,7 +2120,7 @@ Please see https://simwood.com/rates for full information #### "rules" -The ‘rules’ parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters; +The ‘rules' parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters: |Parameter|Format|Description| |:--|:--|:--| @@ -2173,12 +2179,12 @@ Christmas / New Year - Dec 25th , December 26th, January 1st, January 2nd #### "routing" -Much like the rules above the ‘routing’ property is an array of objects named corresponding to the rules. There is also the special ‘default’ rule, which applies when there are no rules specified or outwith the times specified in the rules. +Much like the rules above the ‘routing' property is an array of objects named corresponding to the rules. There is also the special ‘default' rule, which applies when there are no rules specified or outwith the times specified in the rules. **NB** This property is mandatory and submitted config will be rejected without it. Routing blocks (described below) can be arranged to allow dialling in parallel or in sequence, or a -combination of both as shown below; +combination of both as shown below: **Ring A & B simultaneously, Then C** @@ -2224,7 +2230,7 @@ combination of both as shown below; #### "meta" -The ‘meta’ parameter in the JSON object allows you to store your own arbitrary data in the Simwood database associated with a number and which can be easily accessed via the API. +The ‘meta' parameter in the JSON object allows you to store your own arbitrary data in the Simwood database associated with a number and which can be easily accessed via the API. The **key** parameter can be used to search for number(s) matching a specified key, the rest of the object is freeform up to a size limit of around 512 bytes. @@ -2270,17 +2276,14 @@ The lastUpdated parameter is used to show when a number was last updated. - This shows how this could be used to store a note associated with a number that hasn’t been configured yet. + This shows how this could be used to store a note associated with a number that hasn't been configured yet. ```json -{ - "meta": { - "notes": "This is reserved for Brian at - Example Corp and is not yet in use", - "reserved": true - } +"meta": { + "notes": "This is reserved for Brian at Example Corp", + "reserved": true } ``` @@ -2293,7 +2296,7 @@ The flexibility offered by the "meta" block enables customers to build a full se **NB** Meta attributes are intended for API use only and are NOT displayed in the portal. These attributes may be overwritten if a number is later configured using the portal. #### Routing Block -Each routing block is defined by a minimum of a ‘type’ and some optional parameters delay and timeout; +Each routing block is defined by a minimum of a ‘type' and some optional parameters delay and timeout: |***parameter***|***values***|| |:-|-|:-| @@ -2310,21 +2313,21 @@ Each routing block is defined by a minimum of a ‘type’ and some optional par It is not possible to simultaneously use the same number for voice and fax. #### Routing Block Additional Parameters -Depending on the type of endpoint selected above there are some additional endpoint-specific mandatory and optional parameters; +Depending on the type of endpoint selected above there are some additional endpoint-specific mandatory and optional parameters: |type| parameter|| |:-|:-|-| -|**sip**|*endpoint*|SIP Endpoint (user@host.com with optional :port and ;transport parameters e.g. %164@example.com:5060;transport=tcp) the following substitutions will take place;
**%e164** will be replaced with the full number in **E164** format
**%ukn** will be replaced with the number in **UK National** format| +|**sip**|*endpoint*|SIP Endpoint (user@host.com with optional :port and :transport parameters e.g. %164@example.com:5060:transport=tcp) the following substitutions will take place:
**%e164** will be replaced with the full number in **E164** format
**%ukn** will be replaced with the number in **UK National** format| ||*sdes*|One of **optional, required,** or **none**. If optional we will offer SDES encryption for the audio on inbound calls. If set to required, the call will not complete without successful negotiation of SDES. If not specified, or set to none, SDES will not be offered by default.| -||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform;

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| +||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform:

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| ||*zone*|One of our zone names [**slo, lon, ny** or **sj**]..

If present, calls originating in the specified zone will be passed to this endpoint, overriding any equal priority endpoints without a zone specified.
This can be used together with multiple sip endpoints to ensure that calls are routed in the most efficient way depending on where they ingress the Simwood network. e.g. calls arriving in London, will route to your own local proxy.
This will be particularly useful to customers with direct connections to Simwood, or hosting their own equipment on- net.

**NB if a call originates from any zone which matches an endpoint with a specific zone set, then any other endpoints within that group will be disregarded.
If the call originates from a zone which does not match a specific endpoint, any endpoint without a zone parameter will be used.
There must always be one endpoint at the same level with no zone specified.**| |**reg**|*user*|SIP registration user (e.g. 9xxxxx-USERNAME)| ||*sdes*|One of **optional** or **required**. Defaults to **optional**, we will offer SDES encryption for the audio on inbound calls to registered endpoints. If set to required, the call will not complete without successful negotiation of SDES.| -||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform;

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| -|||**NB** if the user is not registered at the time the call is received this will be skipped entirely, we advise you use another destination (or ‘busy’) in addition to a **reg** endpoint.| +||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform:

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| +|||**NB** if the user is not registered at the time the call is received this will be skipped entirely, we advise you use another destination (or ‘busy') in addition to a **reg** endpoint.| |**pstn**|*number*|Destination number in e164 format (e.g. 447700900123)
**NB the pstn divert function is intended for voice calls only.**| ||*maxcpm*|Maximum cost per minute (in your billing currency) of the B leg of the call, intended for use with NTS services to limit exposure to expensive destinations or to ensure that the destination number cost is covered by the revenue share from the inbound leg. (e.g. 0.05)| -||*maxcpc*|To be used in conjunction with the above, sets a maximum call cost (e.g. connection cost)
**NB does not limit call duration to a cost ‘limit’**| +||*maxcpc*|To be used in conjunction with the above, sets a maximum call cost (e.g. connection cost)
**NB does not limit call duration to a cost ‘limit'**| ||*cli*|CLI to present when forwarding the call, if not specified will present the callers CLI where it is available.| ||trunk|The trunk to be associated (for billing and CDR purposes) with the outbound (B-leg) (e.g. 9xxxxx-TRUNKNAME)| |**fax**|*method*|One of **http** or **mail**| @@ -2332,7 +2335,7 @@ Depending on the type of endpoint selected above there are some additional endpo |**busy**|no parameters available| -**NB** The ‘pstn’ endpoint is intended for **voice calls only**. +**NB** The ‘pstn' endpoint is intended for **voice calls only**. We cannot guarantee successful transmission of fax or data calls forwarded to the PSTN using this functionality. #### Number Configuration Worked Examples @@ -2430,7 +2433,7 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th - The above might seem complicated but corresponds to the following simple PHP example, which illustrates the underlying structure; + The above might seem complicated but corresponds to the following simple PHP example, which illustrates the underlying structure: @@ -2443,13 +2446,13 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th 'sip', 'endpoint' => ‘%did@sip.mycompany.com’); -// Add it to the ‘default’ routing block -$arrayRouting['default'][] = Array($arrayRouteDefinition); +$arrayRouteDefinition = Array('type' => 'sip', 'endpoint' => ‘%did@sip.mycompany.com'): +// Add it to the ‘default' routing block +$arrayRouting['default'][] = Array($arrayRouteDefinition): // Add the routing configuration to the config -$arrayConfig['routing'] = $arrayRouting; +$arrayConfig['routing'] = $arrayRouting: // encodedConfig now contains the JSON encoded routing -$encodedConfig = json_encode($arrayConfig); +$encodedConfig = json_encode($arrayConfig): ``` @@ -2459,14 +2462,14 @@ $encodedConfig = json_encode($arrayConfig); Another advantage of this method is that you can retrieve the configuration as a JSON object via your favourite programming language, edit the required entry in place and PUT the changed configuration back. #### Number Configuration - Success -Changes should take effect immediately, and the following simple JSON object will be returned; +Changes should take effect immediately, and the following simple JSON object will be returned: |||| |:-|:-|-| |success | true |Will always be true when the routing has been successfully updated.| #### Number Configuration - Errors -In the event of a configuration error a simple JSON object will be returned as follows; +In the event of a configuration error a simple JSON object will be returned as follows: |||| |:-|:-|-| @@ -2479,20 +2482,20 @@ In the event of a configuration error a simple JSON object will be returned as f | | | |:--|:-| -|Setting **‘OPTION’** must be **X, Y or Z**|An option in the "options" section has an invalid value, please select from one of the provided values | -|Invalid parameter **‘OPTION’** in settings |A parameter in the "options" section is unrecognised. please remove this parameter| -|Rule name **‘NAME’** is invalid.|Rule names must contain the characters shown only| +|Setting **‘OPTION'** must be **X, Y or Z**|An option in the "options" section has an invalid value, please select from one of the provided values | +|Invalid parameter **‘OPTION'** in settings |A parameter in the "options" section is unrecognised. please remove this parameter| +|Rule name **‘NAME'** is invalid.|Rule names must contain the characters shown only| |[Rule|Routing Block] must be an array.|Rules and routing blocks must be arrays, even if they contain only one item.| -|Rule **‘NAME’** entry **X** parameter **‘PARAM’** is invalid.|The value provided for the parameter in the rule shown is invalid.| -|Routing block **'NAME'** does not match any specified rules (or default) | A routing block has been specified that doesn’t correspond to any time-dependant rules (or "default") - therefore would never be called. Check your rule names match.| -|Unknown section **‘NAME’** in configuration.|There is a section that is unrecognised, if you wish to store your own information in a number configuration you may do so but this must be within the ‘meta’ section (which can contain anything)| +|Rule **‘NAME'** entry **X** parameter **‘PARAM'** is invalid.|The value provided for the parameter in the rule shown is invalid.| +|Routing block **'NAME'** does not match any specified rules (or default) | A routing block has been specified that doesn't correspond to any time-dependant rules (or "default") - therefore would never be called. Check your rule names match.| +|Unknown section **‘NAME'** in configuration.|There is a section that is unrecognised, if you wish to store your own information in a number configuration you may do so but this must be within the ‘meta' section (which can contain anything)| ### Inbound Trunk Association Inbound numbers can be associated with a trunk either for billing reconciliation purposes only, or to take advantage of some of the trunk-specific controls and/or routing configuration for inbound traffic. If a number- level configuration exists then this will take priority over any trunk-level configuration, which in turn, will take priority over the default account-level configuration. -**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block in either the Number or Trunk Configuration as shown above. +**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg' routing block in either the Number or Trunk Configuration as shown above. `/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/trunk` @@ -2622,7 +2625,7 @@ a legacy configuration and does not support modern TLS endpoints or Unicode mess endpoint - + @@ -2755,10 +2758,10 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **Remember this information is to assist the Emergency Service response and you have a legal obligation to ensure this information is provided fully and accurately to the best of your ability.** -The name and address information should be sufficient to identify the premises or individual promptly in an emergency. This is more important than it matching the ‘official’ record; for a business entry include only the business details, do NOT specify your contact there or primary account holder etc as an individual. +The name and address information should be sufficient to identify the premises or individual promptly in an emergency. This is more important than it matching the ‘official' record: for a business entry include only the business details, do NOT specify your contact there or primary account holder etc as an individual. **Note 1 : Business Names** -Business names should be chosen that best allow the Emergency Services to identify and locate the business - typically this is the ‘name over the door’ rather than that of a parent or holding company irrespective of who you address the bill to. +Business names should be chosen that best allow the Emergency Services to identify and locate the business - typically this is the ‘name over the door' rather than that of a parent or holding company irrespective of who you address the bill to. **Note 2 - Business Suffix** Addition to business name (e.g. Ltd or Plc) this can also be used to include a brief description that identifies the function of the business - e.g. "Hospital", "Hotel", "Fuel Storage Depot" provides valuable extra information to the Emergency Services @@ -2998,7 +3001,7 @@ Each port will be one of the following types, if unsure please contact the LCP b The above is provided for guidance only, the Number Portability Guide should be consulted to determine lead times for porting requests. #### Number Object -The ‘numbers’ array in the above should be an array of objects each with the following structure. These must include all numbers, including the MBN (even though it is specified separately) +The ‘numbers' array in the above should be an array of objects each with the following structure. These must include all numbers, including the MBN (even though it is specified separately) |Parameter|Values|| |:-|-|-| @@ -3007,7 +3010,7 @@ The ‘numbers’ array in the above should be an array of objects each with the ||associated| Associated Number (e.g. another DDI on an ISDN circuit)| ||other |Other Number at the same address (but not associated)| |**action**| port| Port this number to Simwood| -||retain |Retain service on this number as-is (only for ‘other’ type)| +||retain |Retain service on this number as-is (only for ‘other' type)| || drop| Drop this number and cease service on the porting date| **Customer Object** @@ -3073,7 +3076,7 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) - +
-Only where mode is ‘http’ or 'http_json' +Only where mode is ‘http' or 'http_json' An HTTP(S) URL that will receive a POST request for each SMS sent to this number.
NB only the http_json method supports TLS endpoints. @@ -2746,7 +2749,7 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage)
postcode 12Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail’s
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML		Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail's
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML
postcode 12Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail’s
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML		Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail's
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML
@@ -3119,7 +3122,7 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **Response** -The response will be a JSON similar to the following; +The response will be a JSON similar to the following: ```json { "success": true, @@ -3129,7 +3132,7 @@ The response will be a JSON similar to the following; ``` The *"ref"* value corresponds to the ticket that will be used to track the progress of the porting request. -If any error(s) occurred whilst validating the configuration these will be returned as follows; +If any error(s) occurred whilst validating the configuration these will be returned as follows: ```json { "success": false, @@ -3425,7 +3428,7 @@ Lists las secen days of inbound faxes (optionally filtered by NUMBER) "data": [ { "hash": "7e2bb7bb87300ff83c657b04b07b8261", - "time": "2015-02-30 12;34:56", + "time": "2015-02-30 12:34:56", "originator": "07700900123", "destination": "443301223000", "station": "MYFAX", @@ -3482,8 +3485,8 @@ Send an SMS Message flash
[optional] -Defaults to 0. If set to 1 message is sent as a ‘flash’ message -(i.e. it will be displayed on the phone screen but not stored in the recipient’s inbox, subject to handset and network support) +Defaults to 0. If set to 1 message is sent as a ‘flash' message +(i.e. it will be displayed on the phone screen but not stored in the recipient's inbox, subject to handset and network support) replace
[optional] @@ -3498,7 +3501,7 @@ of 1 will truncate your message if it is longer than 160 characters unless you s report
[optional] -URL for delivery report. The following placeholders can be used; +URL for delivery report. The following placeholders can be used: %id% @@ -3523,8 +3526,8 @@ URL for delivery report. The following placeholders can be used; -If successful the message will be queued immediately and an id returned as follows; -If the extended parameter is included, additional information will be included in the response e.g; +If successful the message will be queued immediately and an id returned as follows: +If the extended parameter is included, additional information will be included in the response e.g: ``` @@ -3590,7 +3593,7 @@ Despite the inclusion of [] in the name, this parameter cannot be repeated multi report
[optional] URL for delivery report. -The following placeholders can be used; +The following placeholders can be used: %id% Message ID @@ -3609,7 +3612,7 @@ The following placeholders can be used; If submission is successful, the fax will be queued immediately and response returned as an array containing -the number and corresponding id of the submitted fax for each destination number; +the number and corresponding id of the submitted fax for each destination number: ```json [ @@ -3644,13 +3647,13 @@ There are now a number of event-driven webhooks available which provide realtime For more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf ### Received Fax -When a fax is received on a number configured to relay them by HTTP POST you will receive an HTTP POST message with a single parameter payload containing a JSON-encoded representation of the following; +When a fax is received on a number configured to relay them by HTTP POST you will receive an HTTP POST message with a single parameter payload containing a JSON-encoded representation of the following: - @@ -3726,7 +3729,7 @@ You must request the PDF from the URL provided within 5 minutes from successful ### Received Fax (Beta) When a fax is received on a number configured to relay them by the **http_json** method you will receive an -HTTP POST message of Content-type **application/json** with the following JSON body; +HTTP POST message of Content-type **application/json** with the following JSON body: Your endpoint can support (or require) TLSv1.1, TLSv1.2. Please note that SSLv3 and TLSv1 are not supported by this service. @@ -3736,7 +3739,7 @@ Please note that SSLv3 and TLSv1 are not supported by this service. - @@ -3810,7 +3813,7 @@ You must request the PDF from the URL provided within 5 minutes from successful ### Received SMS (http) - Deprecated -When an SMS is received on a number configured to relay them by using the legacy **http** method you will receive an HTTP sPOST message of Content-type **application/x-www-form-urlencoded** with a single parameter payload containing a JSON-encoded representation of the following; +When an SMS is received on a number configured to relay them by using the legacy **http** method you will receive an HTTP sPOST message of Content-type **application/x-www-form-urlencoded** with a single parameter payload containing a JSON-encoded representation of the following: **Please note your endpoint cannot require TLSv1.1 or higher. The legacy SMS service supports SSLv3 and TLSv1 only (or plain http) for TLS support please use the service described below (with type http_json)** @@ -3819,7 +3822,7 @@ When an SMS is received on a number configured to relay them by using the legacy - @@ -3867,7 +3870,7 @@ For your security we do not retain message content after relay to your own platf ### Received SMS (http_json) When an SMS is received on a number configured to relay them by using the **http_json** method you will -receive an HTTP POST message of Content-type **application/json** with the following JSON body;
+receive an HTTP POST message of Content-type **application/json** with the following JSON body:
Your endpoint can support (or require) TLSv1.1, TLSv1.2.
Please note that SSLv3 and TLSv1 are not supported by this service. @@ -3876,7 +3879,7 @@ Please note that SSLv3 and TLSv1 are not supported by this service. - @@ -3938,7 +3941,7 @@ An example full message is shown below ### Outbound Fax Reports -Where a report field was specified for an outgoing fax, we will make a POST to the URL specified. If present, ‘%id%’ in your URL will be replaced by the message ID returned in the response below and ‘%status%’ will be replaced with the status code.

+Where a report field was specified for an outgoing fax, we will make a POST to the URL specified. If present, ‘%id%' in your URL will be replaced by the message ID returned in the response below and ‘%status%' will be replaced with the status code.

Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. @@ -3946,7 +3949,7 @@ Additionally the POSTed data will contain a single parameter called payload, the - @@ -4006,7 +4009,7 @@ The number of retries required.
Description
app‘fax_inbound’ in this case. +‘fax_inbound' in this case. This is to facilitate re-use of the same status receiver your side for multiple applications.
Description
app‘fax_inbound’ in this case.
+		‘fax_inbound' in this case.
NB This field exists to facilitate re-use of the same status receiver your side for multiple applications. However as this is a beta this is subject to change and it is strongly recommended to use a dedicated URL to receive HTTP requests.
Description
app‘mvno_inbound_sms’ in this case.
+		‘mvno_inbound_sms' in this case.
This is to facilitate re-use of the same status receiver your side for multiple applications.
Description
app‘sms_inbound’ in this case.
+		‘sms_inbound' in this case.
NB This field exists to facilitate re-use of the same URL for multiple applications. However we strongly recommended to use a dedicated URL where possible.
Description
app‘fax_inbound’ in this case.
+		‘fax_inbound' in this case.
This is to facilitate re-use of the same status receiver your side for multiple applications.
### Outbound SMS Delivery Reports (DLRs) -Where a report field was specified for an outgoing SMS, we will make a POST to the URL specified. If present, ‘%id%’ in your URL will be replaced by the message ID returned in the response below and ‘%status%’ will be replaced with the status code. +Where a report field was specified for an outgoing SMS, we will make a POST to the URL specified. If present, ‘%id%' in your URL will be replaced by the message ID returned in the response below and ‘%status%' will be replaced with the status code. Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. @@ -4014,7 +4017,7 @@ Additionally the POSTed data will contain a single parameter called payload, the FieldDescription app -‘sms_send_status’ in this case. This is to facilitate re-use of the same status receiver your side for multiple applications. +‘sms_send_status' in this case. This is to facilitate re-use of the same status receiver your side for multiple applications. From 0b53ea891eb88c135d1c0cf9551d98ea490b3b6f Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Tue, 10 Oct 2023 15:05:36 +0100 Subject: [PATCH 14/15] revert Simwood changes (for new PR) --- docs/wholesale/api/v3.md | 2990 +++++++++++++++++++------------------- 1 file changed, 1495 insertions(+), 1495 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 69ac131..14b573d 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -18,13 +18,13 @@ services. The API is the preferred way to configure your Simwood services. Everything in the portal can also be configured via the API (and in some cases the API offers some additional functionality) Our portal is based on the API, and everything you can do in the portal you can do through the API in your own -code. We've deliberately made it this way. The only exception to this is the authentication elements of the +code. We’ve deliberately made it this way. The only exception to this is the authentication elements of the portal, as using your API key to log in on the web would be cumbersome. ### Databases -As before, many queries are made against MySQL although we have dedicated servers for the API's use. +As before, many queries are made against MySQL although we have dedicated servers for the API’s use. These are built for queries and are slaves of masters. We can build additional query servers sideways as required. Writes are, of course, made against the masters. Increasingly, API requests are served directly from our underlying REDIS ram-based data stores where possible. @@ -32,7 +32,7 @@ our underlying REDIS ram-based data stores where possible. This API introduces multiple layers in between the above for performance and scale: #### Beanstalkd Queues We use Beanstalkd a lot for internal messaging. In this API where a request is non-trivial and involves -other processes, we'll simply queue a job. +other processes, we’ll simply queue a job. #### REDIS REDIS replaced memcached as our caching data store, and is used for much more as it supports a number of advanced data structures facilitating vastly improved monitoring and real-time @@ -48,7 +48,7 @@ release of a job to a daemon is sub-millisecond giving the queueing the performa requests. Most complicated jobs involve multiple daemons working through a sequence of queues. ## Basic Operations -The Simwood API can be found at the following URI: +The Simwood API can be found at the following URI; https://api.simwood.com/v3/ Please note that TLS v1.1 or Higher is Mandatory for all requests. @@ -64,17 +64,14 @@ https://api.simwood.com/v3/tools/myip - will return your IP address as seen by t https://api.simwood.com/v3/tools/time - will return a timestamp from the API ### JSON Output Format -You'll see that in both above cases the output is JSON, e.g: +You’ll see that in both above cases the output is JSON, e.g: -```json -{ - "timestamp": 1388748052, - "rfc": "Fri, 03 Jan 2014 11:20:52 +0000" -} -``` +`` +{"timestamp":1388748052,"rfc":"Fri, 03 Jan 2014 11:20:52 +0000"} +`` -JSON ("JavaScript Object Notation") is used as it's a lightweight format designed for exchange of data +JSON ("JavaScript Object Notation") is used as it’s a lightweight format designed for exchange of data structures which has an additional advantage of being relatively human readable. All modern languages such as PHP, ASP, .net, Node, Perl etc can handle JSON structures and convert to/from their native objects or arrays easily making it the ideal choice for REST APIs. @@ -82,9 +79,9 @@ arrays easily making it the ideal choice for REST APIs. JSON is designed to be machine-readable and as such is sent with minimal whitespace by default however when developing it is often useful to see the output in a more human-friendly format, you can achieve this simply by appending `"?pretty=true"` to any endpoint e.g https://api.simwood.com/v3/tools/time?pretty=true -would look like this: +would look like this; -```json +``` { "timestamp": 1388748052, "rfc": "Fri 03 Jan 2014 11:20:52 +0000" @@ -96,9 +93,9 @@ Most commands are linked to an account and therefore require authentication. We use standard Basic Authentication, i.e. your client makes a request, we respond with a 401 response code, your client replies with the API username and password included. Your API username and password were provided at the time of creating your Simwood account, if you do not -have these please contact our support team and we'll be happy to provide you with them. +have these please contact our support team and we’ll be happy to provide you with them. -Note that, at present: +Note that, at present; - Your API username and password is not the same as your portal login details - Your API password is designed to be used programatically, and is typically not memorable @@ -106,15 +103,13 @@ Note that, at present: - You cannot, currently, change your API username or password - although our support team are happy to do so if required (e.g. if your details are lost or you have reason to believe they are compromised) -If you pull up an example URL in your browser it'll do this for you. For your code, different development -languages will tackle this in different ways but most will ‘just deal with it' automatically for you. +If you pull up an example URL in your browser it’ll do this for you. For your code, different development +languages will tackle this in different ways but most will ‘just deal with it’ automatically for you. cURL for example, will just take the username and password as parameters, e.g.: -``` -curl --user name:password https://api.simwood.com/v3/… -``` +``curl --user name:password https://api.simwood.com/v3/…`` -PHP's cURL implementation is very similar in that you'd set CURLOPT_USERPWD with [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php). +PHP’s cURL implementation is very similar in that you’d set CURLOPT_USERPWD with [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php). An example authenticated GET request is: ``` @@ -126,32 +121,27 @@ will need to be replaced with account ID (typically a six digit number)* Which would return the following -```json -[ - { - "balance": "12.32", - "currency": "GBP" - } -] -``` +``[{"balance":"12.32","currency":"GBP"}] `` -Adding `?pretty=true` to the end of the URL would give you the same information in the following format: -```json +Adding `?pretty=true` to the end of the URL would give you the same information in the following format; +``` [ { - "balance": "12.32", - "currency":"GBP" + "balance": "12.32", + "currency":"GBP" } ] ``` -Both are treated equally by a JSON parser, and are syntactically valid, however the ‘pretty-printed' version +Both are treated equally by a JSON parser, and are syntactically valid, however the ‘pretty-printed’ version may be useful for debugging. +Simwood + + ### PUT and DELETE requests In the spirit of being REST-ful, many URLs can be acted upon with different methods. The URL does not -change, only the HTTP method used against it. One example of this is number configuration, for example: - +change, only the HTTP method used against it. One example of this is number configuration, for example; ``` https://api.simwood.com/v3/numbers/{ACCOUNT}/allocated/{NUMBER} ``` @@ -187,7 +177,7 @@ https://api.simwood.com/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config will just remove the configuration, leaving the number on your account Setting the method is language specific and `PUT` and `DELETE` cannot be easily replicated in a browser. Almost -all environments/browsers will default to GET so the chances are if it doesn't work as you expect you are +all environments/browsers will default to GET so the chances are if it doesn’t work as you expect you are using the `GET` method. For development languages which do not permit all HTTP methods to be used you can pass a hidden parameter named _method in an HTTP POST or GET and set the method to use in there. @@ -214,28 +204,21 @@ requests. The output from such a POST request (which requests a report) will typically be small, i.e.: -```json -{ - "mode": "vsind", - "date": "2012-01-28", - "type": "voice_summary", - "account": "ACCOUNT", - "format": "json", - "hash": "4e591630fedf4aa149db9874fb33fe23", - "link": "\/v3\/files\/ACCOUNT\/4e591630fedf4aa149db9874fb33fe23" -} +``` +{"mode":"vsind","date":"2012-01-28","type":"voice_summary","account":"ACCOUNT","format" +:"json","hash":"4e591630fedf4aa149db9874fb33fe23","link":"\/v3\/files\/ACCOUNT\/ +4e591630fedf4aa149db9874fb33fe23"} ``` -You will note that this is not in fact a summary of today's charges. It is a hash that uniquely identifies that +You will note that this is not in fact a summary of today’s charges. It is a hash that uniquely identifies that report and a link to it. As the return suggests, you can retrieve the actual results with a GET request to ``` -https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23 +https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23. ``` - -#### But don't worry... +#### But don’t worry... Whilst is is important to understand the effect a given request method will have, we are somewhat relaxed in our interpretation of them where possible. DELETE is always DELETE with no alternative but we will accept a POST instead of a PUT and a GET instead of a POST where possible. You should not assume we will, and @@ -244,7 +227,7 @@ example. #### Report De-duplication As described above, when you request a report the return will just contain a link to the results. That link will -be unique to that specific report, i.e. in the above example the hash for today's summary will be the same with +be unique to that specific report, i.e. in the above example the hash for today’s summary will be the same with every request, but only every request `today`. Tomorrow will generate a different hash. If you make multiple requests for the same report before you retrieve it, duplicates will simply be ignored and the report will only be run once. @@ -263,7 +246,7 @@ hash. A different report for today or the same report for tomorrow will give dif different numbers will generate different hashes. Further, de-duplication will only apply where previous results have not been retrieved. -The intention here is to protect the system from the coder who wishes to request a year's CDRs every second. +The intention here is to protect the system from the coder who wishes to request a year’s CDRs every second. He can, but all requests other than the first will be ignored until he retrieves the results. This rather extreme example is actually real and was a consequence of the way the v2 API paginated results and required clients to step through them. More than a few customer implementations reached the end of the results and went @@ -277,17 +260,13 @@ https://api.simwood.com/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23 ``` This URL can be polled at a sensible interval as it will simply return a 204 No Content until the report exists. Once the report does exist, it can be downloaded only once and then will be automatically deleted. -To negate the need for polling, clients may instead wish to specify a ‘callback' URL with their request. This -should be POSTed as a variable called ‘callback'. The response to the request will be identical as without it but +To negate the need for polling, clients may instead wish to specify a ‘callback’ URL with their request. This +should be POSTed as a variable called ‘callback’. The response to the request will be identical as without it but on successful generation of the report we will make a POST to the URL provided. This will contain a single -HTTP POST variable call ‘payload' which will contain the report hash in JSON format, e.g.: +HTTP POST variable call ‘payload’ which will contain the report hash in JSON format, e.g.: -```json -{ - "app": "reports", - "id": "76e7a8102f93c636785ea8432c72e07a", - "data": null -} +``` +{"app":"reports","id":"76e7a8102f93c636785ea8432c72e07a","data":null} ``` The client should then GET the report as usual within a maximum of 5 minutes, after which it may expire. @@ -297,37 +276,36 @@ Dates are always expressed in MySQL format (YYYY-MM-DD hh:mm:ss), e.g. 2012-01-0 #### File (Report Output) Handling Unlike many APIs the Simwood API is asynchronous when requesting some complex reports to improve performance (this is discussed in more detail above) and some POST requests will result in a small response -containing a hash and ‘link' to a file e.g. +containing a hash and ‘link’ to a file e.g. ```json { - "mode": "vsind", - "date": "2012-01-28", - "type": "voice_summary", - "account": "{ACCOUNT}", - "format": "json", - "hash": "4e591630fedf4aa149db9874fb33fe23", - "link": "/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23" + "mode":"vsind", + "date":"2012-01-28", + "type":"voice_summary", + "account":"{ACCOUNT}", + "format":"json", + "hash":"4e591630fedf4aa149db9874fb33fe23", + "link":"/v3/files/{ACCOUNT}/4e591630fedf4aa149db9874fb33fe23" } ``` -The functions below are used to retrieve these: +The functions below are used to retrieve these; `` /v3/files/{ACCOUNT} `` -| Method | Description | -| :----- | :------------------------------------- | -| GET | Lists uncollected files on the account | +|GET|Lists uncollected files on the account | +|:--|:----------------------------------------------------------------------------------| ```json { - "ff98d8d8fdf9dfd178e72b6e6ba207ff" { - "name":"ff98d8d8fdf9dfd178e72b6e6ba207ff", - "content_type":"application/json", - "length":410, - "uri":"/v3/files/ACCOUNT/ff98d8d8fdf9dfd178e72b6e6ba207ff" - } +"ff98d8d8fdf9dfd178e72b6e6ba207ff" { +"name":"ff98d8d8fdf9dfd178e72b6e6ba207ff", +"content_type":"application/json", +"length":410, +"uri":"/v3/files/ACCOUNT/ff98d8d8fdf9dfd178e72b6e6ba207ff" +} } ``` @@ -335,39 +313,36 @@ The functions below are used to retrieve these: /v3/files/{ACCOUNT}/{HASH} `` -| Method | Description | -| :----- | :-------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Retrieve specific file on account, where HASH is the hash returned when the report was requested. File will be deleted after retrieval. | - +|GET |Retrieve specific file on account, where HASH is the hash returned when the report was requested. File will be deleted after retrieval. | +|:--|--------------------------------------------------------------------------------------------------------| ## API Endpoints If the above has all made sense, you should need little more than a list of the available end-points and the -HTTP methods they support to get going. This follows and you'll quickly observe they are hierarchical and +HTTP methods they support to get going. This follows and you’ll quickly observe they are hierarchical and hopefully consistent. The method shown indicates behaviour as described earlier. -Each endpoint is documented below in the following format: +Each endpoint is documented below in the following format; -``/v3/URL`` +`/v3/URL` -| Method | Description | -| :----- | :----------------------------------------------------------------------------------------------- | -| GET | Explains what happens when the GET method is used | -| POST | Explains what happens when the POST method is used. Will also explain what parameter is used for | -| | *parameter* - An example GET / POST or PUT parameter | -| | *anotherparam* - Another parameter to be sent by POST | +|GET |Explains what happens when the GET method is used | +|:----|:------------------------------------------------------------------------------------------------------------| +|POST |Explains what happens when the POST method is used. Will also explain what parameter is used for +| |*parameter* - An example GET / POST or PUT parameter | +| |*anotherparam* - Another parameter to be sent by POST | -**Please Note** - Where example responses are shown in this documentation they may be reformatted to be +`Please Note ` - Where example responses are shown in this documentation they may be reformatted to be more easily human-readable, the actual response will have escaped slashes (e.g. / replaced with \/) and not include any excess white space. | |The following conventions are used in describing the URL or other parameters| |:--------|:----------------------------------------------------------------------| |{ACCOUNT} | Where a word is capitalised and enclosed by curly braces { } it must be replaced with the appropriate information e.g. {ACCOUNT} or {IP} | -| [ on \| off ] | Where two or more words are separated by the pipe character \| and enclosed within square brackets [ ] these are ‘either or' options. e.g. a url with the form /latest/[1\|5\|10] allows you to specify any of the following 3 URLs:
/latest/1
/latest/5
/latest/10
Arbitrary values (e.g. /latest/15) are not supported | +| [ on \| off ] | Where two or more words are separated by the pipe character \| and enclosed within square brackets [ ] these are ‘either or’ options. e.g. a url with the form /latest/[1\|5\|10] allows you to specify any of the following 3 URLs;
/latest/1
/latest/5
/latest/10
Arbitrary values (e.g. /latest/15) are not supported | | URLs | The URLs are shown without the leading https://api.simwood.com/ which must be inserted before the /v3/ when making any API call. | | paramname | Parameters are shown in italics, these are passed by GET, POST or PUT in the request and do not form part of the URI (except in the case of the GET request, when they are part of the query string after the ? mark) | -| paramname[] | Parameters with square brackets at the end are different and can be thought of as Array Parameters. These can be passed multiple times but even if only one item is being included you must include the [] on the end. For compatibility with some languages (e.g. PHP with Curl) an integer value can be between the square brackets e.g the following two examples are equivalent:
`?param[]=apple¶m[]=orange¶m[]=pear`
`?param[0]=apple¶m[1]=orange¶m[2]=pear` | +| paramname[] | Parameters with square brackets at the end are different and can be thought of as Array Parameters. These can be passed multiple times but even if only one item is being included you must include the [] on the end. For compatibility with some languages (e.g. PHP with Curl) an integer value can be between the square brackets e.g the following two examples are equivalent;
`?param[]=apple¶m[]=orange¶m[]=pear`
`?param[0]=apple¶m[1]=orange¶m[2]=pear` | ## Tools @@ -375,37 +350,52 @@ The following tools are made available without authentication to help integrate ### IP Address Your IP address, as seen by the Simwood API service ``` -https://api.simwood.com/v3/tools/myip +curl https://api.simwood.com/v3/tools/myip ``` -| Method | Description | -| :----- | :---------------------------------------------------------- | -| GET | Return your external IP address, as seen by the Simwood API | +| Request Type | result | +|:--|:----| +| GET | Return your external IP address, as seen by the Simwood API| ### Time The current server timestamp ``` -https://api.simwood.com/v3/tools/time +curl https://api.simwood.com/v3/tools/time ``` -| Method | Description | -| :----- | :---------------------------- | -| GET | Returns the current timestamp | +| Request Type | result | +|:--|:----| +| GET | Returns the current timestamp| ### Explain This tool is provided to help debug requests to the Simwood API. It accepts any request method (GET, PUT, POST, DELETE etc) and returns a human-readable report of the information submitted. - + - | Method | Description | - | :----- | :---------------------------------------------------- | - | ANY | Returns human-readable report of the request received | +```bash +curl "https://api.simwood.com/v3/tools/explain?test=1&pretty=true" +or + +curl -X POST "https://api.simwood.com/v3/tools/explain?test=1&pretty=true" +``` - + + -```json + + + + + + + + + + +
Request TypeResult
ANY Returns human-readable report of the request receive +
+ +``` Simwood API - Explain Tool ======================================================== Query ID: swAPI6410ece80eaff @@ -413,7 +403,7 @@ Timestamp: 2023-03-14 21:53:44 HTTP Request Method: GET API Request Method: GET == Query String ======================================== -Your query string contained 2 elements: +Your query string contained 2 elements; test => 1 pretty => true == HTTP Post Vars ===================================== @@ -425,94 +415,105 @@ No JSON Request body ======================================================= Simwood API v3 http://mirror.simwood.com/pdfs/APIv3.pdf ``` - - -#### NB As this is intended to be a human-readable report for debugging purposes the format may change at any time, and without notice, and should not be relied upon. +
-## Account Management -#### Account Type +#### NB As this is intended to be a human-readable report for debugging purposes the format may change at any time, and without notice, and should not be relied upon. +## Account Management -Your account will be one of the following four types: `developer, startup, virtual_interconnect, or managed_interconnect`, each have different commercials but are functionally identical. All new accounts start off as ‘Developer', we encourage you to move to ‘Start-Up' for production use, and to consider ‘Virtual Interconnect' or ‘Managed Interconnect' as your requirements evolve. +#### Account Type +Your account will be one of the following four types; `developer, startup, virtual_interconnect, or managed_interconnect`, each have different commercials but are functionally identical. All new accounts start off as ‘Developer’, we encourage you to move to ‘Start-Up’ for production use, and to consider ‘Virtual Interconnect’ or ‘Managed Interconnect’ as your requirements evolve. The differences between these account types can be found in the [Simwood Account Pricing](https://cdn.simwood.com/docs/simwood_account_pricing.pdf) document. +##### /v3/accounts/{ACCOUNT}/type - + -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Get your current account type, and limitations Account type will be one of the following: developer, startup, virtual_interconnect, managed_interconnect | + ```bash +curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/type + ``` ```json { - "success": true, - "data": { - "account_type": "developer", - "number_limit": 5, - "channel_limit": 5, - "min_prepay": 50 - } -} + "success": true, + "data": { + "account_type": "developer", + "number_limit": 5, + "channel_limit": 5, + "min_prepay": 50 +} } ``` +please replace all variables above for the curl command to work. check introduction page to see how you can set envronmental variabls in your lab. + +| Request Type | result | +|:--|:----| +| GET | Get your current account type, and limitations Account type will be one of the following; `developer, startup, virtual_interconnect, managed_interconnect` | +| PUT | Upgrade or downgrade your account
This option is only available to customers of account_type `developer` or `startup`
+| | account_type updgrade to `developer`(if startup), or upgrade to `startup`(if developer) | #### Charges Apply -There is a minimum commitment associated with the Start-Up package, along with other commercial differences. Please see the Simwood Product Brochure for more information +$.. There is a minimum commitment associated with the Start-Up package, along with other commercial differences. Please see the Simwood Product Brochure for more information #### PLEASE NOTE -You can only migrate from Developer to Start-up. For all other account changes please contact our Operations Desk via eMail to team@simwood.com, or call us on 44330 122 3000 to discuss your requirements further. +You can migrate between developer and startup at any time. By changing your package type to Start-Up please ensure you are aware of the commercial obligations of this package, including the **minimum pre- payment amount** (which differs from the developer package) and the **minimum total spend** per month, which replaces the service charge of the Developer pack. -### Credit Account Management +It is not possible to switch to our **Virtual Interconnect** or **Managed Interconnect** options online either via the API or Portal. Please contact us if you are interested in these packages. -``` -/v3/accounts/{ACCOUNT}/credit/invoices/* -``` +If you are unsure, please contact our Operations Desk via eMail to team@simwood.com, or call us on 0330 122 3000 to discuss your requirements further. +### Credit Account Management The current status of all invoices on your account is available through the API. - + -| Method | Endpoint | Description | -| :------ | :-------------------------------------------- | :--------------------------------------------------- | -| GET | /v3/accounts/{ACCOUNT}/credit/invoices/unpaid | List of unpaid invoices on account (since June 2010) | -| GET | /v3/accounts/{ACCOUNT}/credit/invoices/paid | List of paid invoices on account (since June 2010) | -| GET | /v3/accounts/{ACCOUNT}/credit/invoices/all | Upgrade or downgrade your account | +```bash +#List of unpaid invoices on account (since June 2010) +curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/unpaid + +#List of paid invoices on account (since June 2010) +curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/paid + +#List of invoices on account (since June 2010) +curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/credit/invoices/all +``` ```json { - "Invoices": [ - { - "InvoiceNumber": "I3010999999", - "Date": "2014-02-30", - "DueDate": "2014-02-30", - "Currency": "GBP", - "Net": "200.00", - "VAT": "40.00", - "Total": "240.00", - "AmountPaid": "240.00", - "AmountCredited": "0.00", - "AmountDue": "0.00" - } - ], - "TotalDue": { - "GBP": 0 - }, - "TotalOverDue": null + "Invoices": [ + { + "InvoiceNumber": "I3010999999", + "Date": "2014-02-30", + "DueDate": "2014-02-30", + "Currency": "GBP", + "Net": "200.00", + "VAT": "40.00", + "Total": "240.00", + "AmountPaid": "240.00", + "AmountCredited": "0.00", + "AmountDue": "0.00" +} ], + "TotalDue": { + "GBP": 0 +}, + "TotalOverDue": null } ``` @@ -520,282 +521,213 @@ The current status of all invoices on your account is available through the API. #### PDF Copy Invoices - ``` /v3/accounts/{ACCOUNT}/credit/invoices/{INVOICE_NUMBER}[.pdf] ``` -| Method | Description | -| :----- | :--------------------------------------------------------------------- | -| GET | Get invoice INVOICE_NUMBER as a pdf file. The .pdf suffix is optional. | -### Prepay Account Management -``` -/v3/accounts/{ACCOUNT}/prepay/summary -``` +### Prepay Account Management +`/v3/accounts/{ACCOUNT}/prepay/summary` - - -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | Requests a report of Summary of account movements. If the optional from_date and to_date parameters are not specified will default to today. | -| | *from_date* Start date of report (in form YYYY-MM-DD) | -| | *to_date* End date of report (in form YYYY-MM-DD) | + + ```bash +curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/prepay/summary + ``` ```json { - "mode": null, - "from": "2023-03-15 00:00:00", - "to": "2023-03-15 23:59:59", - "type": "balance_summary", - "account": "000000", - "format": "json", - "hash": "d3ccc0eb54e65b63c0fea0e9235afbca", - "link": "/v3/files/000000/d3ccc0eb54e65b63c0fea0e9235afbca" + "mode": null, + "from": "2023-03-15 00:00:00", + "to": "2023-03-15 23:59:59", + "type": "balance_summary", + "account": "000000", + "format": "json", + "hash": "d3ccc0eb54e65b63c0fea0e9235afbca", + "link": "/v3/files/000000/d3ccc0eb54e65b63c0fea0e9235afbca" } ``` +| | | +|:--|:-------| +| POST | Requests a report of Summary of account movements. If the optional *from_date* and *to_date* parameters are not specified will default to today.
**from_date** Start date of report (in form YYYY-MM-DD)
**to_date** End date of report (in form YYYY-MM-DD) | -``` +**Other examples** +```bash +#GET List all account pre-payments /v3/accounts/{ACCOUNT}/prepay/prepayments/all -``` -| Method | Description | -| :----- | :----------------------------- | -| GET | List all account pre-payments. | - -``` +#GET List last (1) or last ten (10) pre-payments to account /v3/accounts/{ACCOUNT}/prepay/prepayments/latest/[1|10] -``` - -| Method | Description | -| :----- | :----------------------------------------------------- | -| GET | List last (1) or last ten (10) pre-payments to account. | - -``` +#GET Transfers between this prepay account and others. /v3/accounts/{ACCOUNT}/prepay/transfers/all -``` - -| Method | Description | -| :----- | :------------------------------------------------ | -| GET | Transfers between this prepay account and others. | - -``` +#List last (1) or last ten (10) transfers on the prepay account /v3/accounts/{ACCOUNT}/prepay/transfers/latest/[1|10] ``` -| Method | Description | -| :----- | :-------------------------------------------------------------- | -| GET | List last (1) or last ten (10) transfers on the prepay account. | - - #### Prepay Account Balance -``` -/v3/accounts/{ACCOUNT}/prepay/balance -``` The API provides tools for checking and protecting your pre-paid balance(s) - - - - - -| Method | Description | -| :----- | :------------------------- | -| GET | Return balance of account. | - - - - - +```bash +#Return balance of account +/v3/accounts/{ACCOUNT}/prepay/balance +``` +*Example result* ```json -{ - "balance": "168.06100", - "currency": "GBP" -} +[ + { + "balance": "168.06100", + "currency": "GBP" + } +] ``` - - #### Low Balance Alerts - -``` -/v3/accounts/{ACCOUNT}/prepay/balance/alert -``` - You can set an amount at which you will receive a notification (configured via the notifications, detailed below) when your balance drops below the specified amount. A maximum of **one** notification will be sent per day. +` /v3/accounts/{ACCOUNT}/prepay/balance/alert` - - - - | Method | Description | - | :----- | :---------------------------------------------------- | - | GET | Returns the current level of alert. | - | PUT | Sets the alert balance to the specified alert_balance | - + + + + + + + + + - - +
GET - - +Returns the current level of alert.
-```json -{ - "account": ACCOUNT, - "alert_balance": 90 -} - - +```bash +[ + { + "account": ACCOUNT, + "alert_balance": 90 + } +] ``` - - - - -#### Balance Locking - -``` -/v3/accounts/{ACCOUNT}/prepay/balance/locked -``` +
PUT -We provide the ability to ‘lock' a portion of your balance to make it unavailable to spend. i.e. you can specify the balance at which we'll treat your account as ‘out of credit' and therefore kill calls in progress. +Sets the alert balance to the specified alert_balance
-This is normally zero but the balance locking facility enables customers to keep large credit balances without risking the entire amount in the event that they, or a customer, suffer a compromise. +**alert_balance** The balance at which an alert should be generated -You can set alerts based on the *available* balance (i.e. balance-locked balance) using the balance alert above. +
- | Method | Description | - | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | - | GET | Returns the ‘locked' balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend | - | PUT | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent. | - | | *balance* The amount to be protected. | - | DELETE | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | - - +#### Balance Locking +We provide the ability to ‘lock’ a portion of your balance to make it unavailable to spend. i.e. you can specify the balance at which we’ll treat your account as ‘out of credit’ and therefore kill calls in progress. -```json -{ - "account":ACCOUNT, - "balance":10.4688, - "locked":5, - "available":5.4688 -} -``` - - +This is normally zero but the balance locking facility enables customers to keep large credit balances without risking the entire amount in the event that they, or a customer, suffer a compromise. +You can set alerts based on the *available* balance (i.e. balance-locked balance) using the balance alert above. +`/v3/accounts/{ACCOUNT}/prepay/balance/locked` +| Method | Description | +|:--|:-------| +| **GET** | Returns the ‘locked’ balance, this represents a portion of your pre-paid balance that cannot be consumed - e.g. to protect against unexpected spend
```[{"account":ACCOUNT,"balance":10.4688,"locked":5,"available":5.4688}]``` | +| **PUT** | Sets the protected amount to the specified balance. This amount remains in your account but cannot be spent.
*balance* The amount to be protected.| +| **DELETE** | Remove the locked balance, allowing the full amount of your pre-paid balance to be used for calls. | -**NB** *The above ‘locked balance' function is provided on a ‘best-efforts' basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account.* +**NB** *The above ‘locked balance’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account.* ### Termination Rate Functions #### Available Tariffs +Some account types have more than one available tariff or rate deck, these can be viewed as follows where this is applicable to your account; -``` -/v3/accounts/{ACCOUNT}/rates/tariffs -``` - -Some account types have more than one available tariff or rate deck, these can be viewed as follows where this is applicable to your account: - +`/v3/accounts/{ACCOUNT}/rates/tariffs` - - - - - | Method | Description| - | :----- |:--------------------------------------------------------------------------------------------------------------------------------------------------- | - | GET | Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck) | +| Method| Description| +|:--|:--| +| GET |Request tariffs available on your account, these are shown together with the prefix required for dynamic rate deck selection (no prefix is required for calls using the default rate deck)| - - +*Example result* ```json { "success": true, "data": [ - { - "description": "Legacy GBP Platinum", - "servicelevel": 1, - "quality": "Platinum", - "prefix": 999001, - "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Platinum.csv" - },{ - "description": "Legacy GBP Gold", - "servicelevel": 2, - "quality": "Gold", - "prefix": 999002, - "default": true, - "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Gold.csv" - } - ] -} + { + "description": "Legacy GBP Platinum", + "servicelevel": 1, + "quality": "Platinum", + "prefix": 999001, + "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Platinum.csv" + }, { + "description": "Legacy GBP Gold", + "servicelevel": 2, + "quality": "Gold", + "prefix": 999002, + "default": true, + "url": "\/v3\/accounts\/929999\/rates\/csv\/Simwood_Gold.csv" + } +] } ``` - - - #### Ratecard Downloads (CSV Format) +Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API; -``` -/v3/accounts/{ACCOUNT}/rates/csv/[default|silver|platinum|gold|name] -``` -Our latest termination rates are also always available in CSV and Excel (XLSX) format from the portal https://portal.simwood.com/ or in CSV format via the API: +`/v3/accounts/{ACCOUNT}/rates/csv/[default|silver|platinum|gold|name]` - + + + ```bash + #Get Request the latest ratecard in CSV Format +curl --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/rates/csv/default + ``` - | Method | Description | - | :-- | :---| - | GET | Request the latest ratecard in CSV Format | -```csv +```bash Effective: 2023-03-10 "prefix","location","day","evening","weekend","connection","minimum_sec","increment_sec" 44113403,"UK - Fixed - Simwood",0.000310,0.000310,0.000310,0.0000,1,1 44113454,"UK - Fixed - Simwood",0.000310,0.000310,0.000310,0.0000,1,1 + ``` - - -**NB: The options silver, platinum and gold are only for ‘legacy' or ‘startup' account types with multiple rate decks. Virtual Interconnect and Managed Interconnect customers should use default or the file name provided from the above query** +**NB: The options silver, platinum and gold are only for ‘legacy’ or ‘startup’ account types with multiple rate decks. Virtual Interconnect and Managed Interconnect customers should use default or the file name provided from the above query** +
#### Destination Lookup -``` -/v3/accounts/{ACCOUNT}/rate/{NUMBER} -``` +`/v3/accounts/{ACCOUNT}/rate/{NUMBER}` - - +| Method| Description| +|:--|:--| +| GET |Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge.| - | Method | Description | - | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | GET | Returns the cost of calling the specified number in your account currency. Each rate array is keyed by the relevant deck (1 - platinum, 2 - gold, 3 - silver) and shows (p)eak, (o)ffpeak, (w)eekend rates and the (c)onnection charge. | + + + ```bash + #Get Note number is in 164 format. ie UK is 44XXXXXXXXXX +curl -X POST --user $CARRIER_API_USERNAME:$CARRIER_API_PASSWORD https://api.simwood.com/v3/accounts/$ACCOUNT/rate/$NUMBER + ``` @@ -813,50 +745,37 @@ Effective: 2023-03-10 - ### General Accounting Reports / CDRs -``` -/v3/accounts/{ACCOUNT}/reports/voice/summary/day/[in|out] -``` +`/v3/accounts/{ACCOUNT}/reports/voice/summary/day/[in|out]` -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------- | -| POST | Request a summary of [incoming] or [outgoing] voice charges. | -| | *date* Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| Method| Description| +|:--|:--| +| **POST** | Request a summary of [incoming] or [outgoing] voice charges
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | -``` -/v3/accounts/{ACCOUNT}/reports/voice/cdr/day -``` +`/v3/accounts/{ACCOUNT}/reports/voice/cdr/day` -| Method | Description | -| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | Request daily CDR report date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| Method| Description| +|:--|:--| +| **POST** | Request daily CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current.| -``` -/v3/accounts/{ACCOUNT}/reports/voice/cdr/latest/[10|100|1000|10000] -``` +`/v3/accounts/{ACCOUNT}/reports/voice/cdr/latest/[10|100|1000|10000]` -| Method | Description | -| :----- | :-------------------------------------------------------------- | -| POST | Request report of last [ 10 \ 100 \ 1,000 \ 10,000 ] Voice CDRs | +| Method| Description| +|:--|:--| +| **POST** | Request report of last [ 10 \| 100 \| 1,000 \| 10,000 ] Voice CDRs | -``` -/v3/accounts/{ACCOUNT}/reports/sms/cdr/day -``` +`/v3/accounts/{ACCOUNT}/reports/sms/cdr/day` -| Method | Description | -| :----- | :--------------------------------------------------------------------------------------------------------------- | -| POST | Request daily SMS CDR report | -| | *date* Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | +| Method| Description| +|:--|:--| +| **POST** |Request daily SMS CDR report
date Optionally specify date in YYYY-MM-DD format to request report as at date, otherwise defaults to current. | -``` -/v3/accounts/{ACCOUNT}/reports/sms/cdr/latest/[10|100|1000|10000] -``` +`/v3/accounts/{ACCOUNT}/reports/sms/cdr/latest/[10|100|1000|10000]` -| Method | Description | -| :----- | :------------------------------------------------------------ | -| POST | Request report of last [ 10 \ 100 \ 1,000 \ 10,000 ] SMS CDRs | +| Method| Description| +|:--|:--| +| **POST** | Request report of last [ 10 \| 100 \| 1,000 \| 10,000 ] SMS CDRs | ### Summary Reports (Instant) @@ -866,182 +785,139 @@ The new Summary Reports are, unlike the CDRs above, not asynchronous, the respon **NB These are intended to be indicative only and are not suitable for billing purposes.** -``` -/v3/accounts/{ACCOUNT}/summary/([in|out])/{KEY} -``` +`/v3/accounts/{ACCOUNT}/summary/([in|out])/{KEY}` - - +| Method| Description| +|:--|:--|:--| +| GET / POST | | Request an inbound or outbound summary report by {KEY} (see below). If ‘in’ or ‘out’ is omitted from the URI bi-directional traffic will be shown.
The parameters below can be provided in the query string (with the exception of the ‘filter’ parameter) or, preferred, as a JSON object in the request | +| |date_start | Optionally specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | +| |limit|Optionally specify limit of results to return, default 9999| +| |sort|Key to sort by| +| |filter| Array of "search_key" => "value" e.g. {"trunk": "930000-TEST"} would generate a report only for the trunk named "930000- TEST" | -| Method | Description | -| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET / POST | Request an inbound or outbound summary report by KEY (see below). If ‘in' or ‘out' is omitted from the URI bi-directional traffic will be shown. The parameters below can be provided in the query string (with the exception of the ‘filter' parameter) or, preferred, as a JSON object in the request | -| | *date_start* [Optional] specify date/time in YYYY-MM-DD HH:mm:ss format to request report from date_start, otherwise defaults to start of current day. **NB Dates must be specified in GMT** | -| | *limit* [Optional] specify limit of results to return, default 9999 | -| | *sort* [Optional] Key to sort by | -| | *filter* Array of "search_key" to "value" | - - - -| Key | Description | -| :----- | :-------------------------------------------------- | -| destid | Summary by Destination ID | -| iso | Summary by ISO Country Code (of destination) | -| codec | Summary by Codec | -| tag | Summary by Tag (as set with "X-simwood-tag" header) | -| trunk | Summary by Trunk | - - +#### Summary Report Keys +The following keys are available for summary reports; + +| Key| Description| +|:--|:--| +| **destid** | Summary by Destination ID | +| **iso** | Summary by ISO Country Code (of destination) | +| **codec** | Summary by Codec | +| **tag** | Summary by Tag (as set with "X-simwood-tag" header) | +| **trunk** | Summary by Trunk | + +#### Example Summary Report +The report below was generated based on a key of ‘trunk’ with a sort of ‘calls’; ```json [ { - "trunk": "930000-ACME", - "calls": 378, - "acd": 1.6, - "minutes": 603.32, - "charges": 8.32 - },{ - "trunk": "930000-WIDGETINC", - "calls": 2856, - "acd": 1.56, - "minutes": 4458.47, - "charges": 23.01 + "trunk": "930000-ACME", + "calls": 378, + "acd": 1.6, + "minutes": 603.32, + "charges": 8.32 + }, + { + + "trunk": "930000-WIDGETINC", + "calls": 2856, + "acd": 1.56, + "minutes": 4458.47, + "charges": 23.01 + } ] ``` - - - #### Event Notifications -``` -/v3/accounts/{ACCOUNT}/notifications -``` - Some notifications can now (as of v3.15) be received via Webhooks, for more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf - - +`/v3/accounts/{ACCOUNT}/notifications` - | Method | Description | - | :----- | :-------------------------------------------- | - | GET | List available notifications on your account. | +| Method| Description| +|:--|:--| +| **GET** |List available notifications on your account
`["blocked_calls","prepay_debit"]` | - - +
-```json -[ - "blocked_calls", - "prepay_debit" -] -``` - - +`/v3/accounts/{ACCOUNT}/notifications/available` -``` -/v3/accounts/{ACCOUNT}/notifications/available -``` +| Method| Description| +|:--|:--| +| **GET** |List available notification TYPEs | -| Method | Description | -| :----- | :-------------------------------- | -| GET | List available notification TYPEs | +`/v3/accounts/{ACCOUNT}/notifications/{TYPE}` -``` -/v3/accounts/{ACCOUNT}/notifications/{TYPE} -``` - -| Method | Description | -| :----- | :----------------------------------------------------- | -| GET | List configured recipients for notifications of {TYPE} | -| DELETE | Delete all configured notifications of {TYPE} | +| Method| Description| +|:--|:--| +| **GET** | List configured recipients for notifications of {TYPE} | +| **DELETE** | Delete all configured notifications of {TYPE} | -``` -/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD} -``` +`/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}` -| Method | Description | -| :----- | :--------------------------------------------------------------------------------------------------------------------------------- | -| GET | Shows all configured recipients of notifications of {TYPE} using {method} | -| | *method* is one of **email** or **sms** | -| POST | Add a new notification recipient to receive notifications of {TYPE} using {METHOD}. Returns a hash corresponding to this recipient | -| | *destination* eMail address or Mobile Number (in E164 format) of the recipient. | +| Method| Description| +|:--|:--| +| **GET** |Shows all configured recipients of notifications of {TYPE} using {METHOD}
METHOD is one of email or sms* | +|**POST**|Add a new notification recipient to receive notifications of {TYPE} using {METHOD}. Returns a hash corresponding to this recipient
*destination* eMail address or Mobile Number (in E164 format) of the recipient.| -``` -/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}/{HASH} -``` +`/v3/accounts/{ACCOUNT}/notifications/{TYPE}/{METHOD}/{HASH}` -| Method | Description | -| :----- | :-------------------------------------- | -| GET | Shows the ifnormation on this recipient | -| DELETE | Deletes this recipient | +| Method| Description| +|:--|:--| +| **GET** |Shows the ifnormation on this recipient| +|**DELETE**| Deletes this recipient | -The {HASH} referred to above can be generated locally and is simply an md5()'d version of the notification address. This is used simply to avoid potential url encoding issues. +The {HASH} referred to above can be generated locally and is simply an md5()’d version of the notification address. This is used simply to avoid potential url encoding issues. -NB **SMS** notification requires credit balance, sent messages will be deducted from your usual credit. +** *SMS** notification requires credit balance, sent messages will be deducted from your usual credit. -``` -/v3/accounts/{ACCOUNT}/notifications/history -``` +`/v3/accounts/{ACCOUNT}/notifications/history` -| Method | Description | -| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Retrieve a history of recent (last 60 days) notifications on your account All parameters below are optional, by default will return all notifications for the last 60 days.Returns a JSON Array of Objects, each Object contains a "data" attribute which contains an Object containing all variables in the original notification. Please note if the original message contained a password it will be redacted and replaced with ###### as these are not stored. | -| | *class* Class of notification ( e.g. trunk or billing ) | -| | *date_start* Start date (no more than 60 days ago) | -| | *date_end* End date (YYYY-MM-DD HH:ii:ss) | +| Method| Description| +|:--|:--|:--| +| **GET** | | Retrieve a history of recent (last 60 days) notifications on your account All parameters below are optional, by default will return all notifications for the last 60 days.
Returns a JSON Array of Objects, each Object contains a "data" attribute which contains an Object containing all variables in the original notification.
Please note if the original message contained a password it will be redacted and replaced with ###### as these are not stored.| +| | *class* | Class of notification ( e.g. trunk or billing ) | +| | *date_start* | Start date (no more than 60 days ago) | +| | *date_end* | End date (YYYY-MM-DD HH:ii:ss) | ## Voice Termination ### Account Limits (and Dynamic Channel Limits) -``` -/v3/voice/{ACCOUNT}/limits -``` - - +`/v3/voice/{ACCOUNT}/limits` - | Method | Description | - | :----- | :------------------------------------------------------------------------ | - | GET | Shows limits in effect on an account including any Dynamic Channel Limits | +**GET** Shows limits in effect on an account including any Dynamic Channel Limits +```json - - -```json { - "channel_allocation": 30, - "channel_allocation_global_numbers": 10, - "channel_allocation_adjustable": false, - "limit_concurrent_in": 10, - "limit_concurrent_out": 20, - "limit_concurrent_out_per_number": 10, - "limit_concurrent_out_international": 3, - "limit_concurrent_out_hotspot": 2, - "limit_rate_out": "10/1s", - "limit_rate_out_international": null, - "limit_rate_out_hotspot": "2/12h", - "dynamic": { - "balance": "15.52680", - "limit_concurrent_out": 3, - "limit/_rate_out": "30/10s" - } -} + "channel_allocation": 30, + "channel_allocation_global_numbers": 10, + "channel_allocation_adjustable": false, + "limit_concurrent_in": 10, + "limit_concurrent_out": 20, + "limit_concurrent_out_per_number": 10, + "limit_concurrent_out_international": 3, + "limit_concurrent_out_hotspot": 2, + "limit_rate_out": "10/1s", + "limit_rate_out_international": null, + "limit_rate_out_hotspot": "2/12h", + "dynamic": { + "balance": "15.52680", + "limit_concurrent_out": 3, + "limit_rate_out": "30/10s" +} } ``` - - - #### Dynamnic Channel Limits Applies only to accounts without a dedicated channel allocation Any dynamic channel limits shown in the "dynamic" block take precedence over the usual account limits. e.g. in the above example due to the low balance there is a concurrent channel limit of 3 channels and a rate limit of 30 calls per 10 seconds. - #### Channel Allocation (Inbound/Outbound) Applies only to accounts with a dedicated channel allocation @@ -1060,58 +936,63 @@ We impose these limits to protect and manage our network utilisation. If you require more channels or a higher rate of calls per second please contact team@simwood.com ### Adjusting your Channel Allocation +Customers with a dedicated channel allocation can manage this allocation, splitting channels between inbound and outbound as required. +`/v3/voice/{ACCOUNT}/limits` -``` -/v3/voice/{ACCOUNT}/limits -``` -Customers with a dedicated channel allocation can manage this allocation, splitting channels between inbound and outbound as required. - - + - | Method | Description | - | :----- | :----------------------------------------------------------------- | - | PUT | Update channel limits | - | | *limit_concurrent_in* inbound channel limit | - | | *limit_concurrent_out* outbound channel limit | - | | NB the above must, together, total the value of channel_allocation | + + - - + + + + + + -```json -{ - "limit_concurrent_in": 10, - "limit_concurrent_out": 20 +```bash + { + "limit_concurrent_in": 10, + "limit_concurrent_out": 20 } ``` - - + + + + + + + - - + +
PUT +Update channel limits
+
JSON request
limit_concurrent_ininbound channel Limit
limit_concurrent_outoutbound channel Limit
NB the above must, together, total the value of channel_allocation
JSON response - - -### Channel Statistics - -``` -/v3/voice/{ACCOUNT}/channels/current +```bash +{ + "success": true + "data": { + "limit_concurrent_in": 10, + "limit_concurrent_out": 20 +} } ``` +
- | Method | Description | - | :----- | :---------------------------------------------------------------------------------------------------------------------- | - | GET | Current channel utilisation | - | | NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below | - - +### Channel Statistics +`/v3/voice/{ACCOUNT}/channels/current` ```json +# GET Current channel utilisation +NB: this is returned as an array (with one member) for compatibility with the /channels/history function detailed below + [ { "datetime": "2014-02-30 12:34:35", @@ -1121,152 +1002,155 @@ Customers with a dedicated channel allocation can manage this allocation, splitt } ] ``` - - -``` -/v3/voice/{ACCOUNT}/channels/history -``` - - +`/v3/voice/{ACCOUNT}/channels/history` - | Method | | - | :----- | :----------------------------------------------------------------------------------------------------------------------- | - | GET | Recent (around 24h) channel utilisation samples | - | | The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one. | - | | *1m* One minute | - | | *5m* (Default) Five Minutes | - | | *1h* One Hour | - - + + + + + + + + + + + + +
GET +
Recent (around 24h) channel utilisation samples +The channels count shows the peak number of channels in use between the previous datetime timestamp and the current one.
interval
+Optional interval for samples in the following form; +
1m - One Minute +
5m - Five Minutes(Default) +
1h - Hourly
```json + [ - { - "datetime": "2023-03-18 17:40:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - },{ - "datetime": "2023-03-18 17:30:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - },{ - "datetime": "2023-03-18 17:20:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - },{ - "datetime": "2023-03-18 17:10:00", - "channels": 11, - "channels_out": 10, - "channels_in": 1 - } + { + "datetime": "2023-03-18 17:40:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + }, + { + "datetime": "2023-03-18 17:30:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + }, + { + "datetime": "2023-03-18 17:20:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + }, + { + "datetime": "2023-03-18 17:10:00", + "channels": 11, + "channels_out": 10, + "channels_in": 1 + }, + .... ] + ``` - - +
-### Real-Time Calls in Progress -``` -/v3/voice/{ACCOUNT}/inprogress/current -``` +### Real-Time Calls in Progress +`/v3/voice/{ACCOUNT}/inprogress/current` - - - | Method | Description | - | :----- | :---------------------------------------------------------------------------------------------- | - | GET | Number and value of calls in progress relative to account balance. Useful for fraud monitoring. | + + + + + + - - + + + + + +
GET +
Number and value of calls in progress relative to account balance. Useful for fraud monitoring.
```json { - "datetime": "2014-02-30 12:34:35", - "total": 1.164, - "callcount": 107, - "balance": 24.406, - "percent_available": 0.25, - "approx_seconds_remaining": 56838, - "calls": { - "1739": { - "location": "UK - Fixed", - "country": "GB", - "total": 0.85, - "callcount": 85 - }, - "2303": { - "location": "UK - Mobile - T-Mobile", - "country": "GB", - "total": 0.244, - "callcount": 19 + "datetime": "2014-02-30 12:34:35", + "total": 1.164, + "callcount": 107, + "balance": 24.406, + "percent_available": 0.25, + "approx_seconds_remaining": 56838, + "calls": { + "1739": { + "location": "UK - Fixed", + "country": "GB", + "total": 0.85, + "callcount": 85 + }, "2303": { + "location": "UK - Mobile - T-Mobile", + "country": "GB", + "total": 0.244, + "callcount": 19 + }, "277": { + "location": "Mexico - Mexico City", + "country": "MX", + "total": 0.04, + "callcount": 2 +}, "2761": { + "location": "Spain - Mobile - Telefonica", + "country": "ES", + "total": 0.02, + "callcount": 1 +} }, + "countries": { + "MX": { + "total": 0.04, + "callcount": 2 }, - "277": { - "location": "Mexico - Mexico City", - "country": "MX", - "total": 0.04, - "callcount": 2 + "ES": { + "total": 0.02, + "callcount": 1 }, - "2761": { - "location": "Spain - Mobile - Telefonica", - "country": "ES", - "total": 0.02, - "callcount": 1 - } - }, - "countries": { - "MX": { - "total": 0.04, - "callcount": 2 - }, - "ES": { - "total": 0.02, - "callcount": 1 - }, - "GB": { - "total": 1.094, - "callcount": 104 - } + "GB": { + "total": 1.094, + "callcount": 104 + } } } ``` - - + +
**As of version 3.15 this information is now also able to be pushed directly to you via Webhooks, for more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** -The above example shows many calls in progress to the UK, along with two to Mexico (MX) and one to Spain (ES) - calls are grouped both by destination (keyed by a unique numeric identifier for that destination) in then "calls" group and by country in "countries" - this makes it simple to alert, for example, if there are any more than a predefined number of calls to any country you don't expect. +The above example shows many calls in progress to the UK, along with two to Mexico (MX) and one to Spain (ES) - calls are grouped both by destination (keyed by a unique numeric identifier for that destination) in then "calls" group and by country in "countries" - this makes it simple to alert, for example, if there are any more than a predefined number of calls to any country you don’t expect. See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/** for some examples of how this data can be used to help protect you against fraud and monitor your VoIP traffic. ### Call Control -``` -/v3/voice/{ACCOUNT}/inprogress/{CALL_ID} -``` +`/v3/voice/{ACCOUNT}/inprogress/{CALL_ID}` - - - | Method | Description | - | :----- | :------------------------------------------ | - | GET | Get information on current call in progress | - | DELETE | End a call in progress | - + + + +Get information on current call in progress - ```json { @@ -1277,13 +1161,29 @@ See **http://blog.simwood.com/2014/01/2-quick-scripts-to-help-you-sleep-easier/* "progress": "2019-09-23 12:27:17", "answered": "2019-09-23 12:27:21", "destid": "2303" - } - } +} } + ``` - - + + + + +End a call in progress + + +```json +{ + "success": true +} + +``` + + + + +
GET
DELETE
**This is designed to be used in conjunction with the Webhook HTTP Events (Beta) detailed at https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf** @@ -1293,42 +1193,39 @@ As this is a BETA endpoint, the information returned from the above may change a ### Voice CDRs (Inline Response) -``` -/v3/voice/{ACCOUNT}/cdr -``` - In addition to the CDR Reports (above) you can retrieve any CDRs from the last three months with a simple inline response (rather than polling for a report) +`/v3/voice/{ACCOUNT}/cdr` +| Method| Description| +|:--|:--|:--| +| **GET/POST** | | Both GET and POST are supported. The request can either be made as a GET query string or JSON POST body. At present, the filter attribute is only supported where requested by POST with a JSON body. | +|| date_start | Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | +| | date_end | Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_end, otherwise defaults to now. | +| | limit | Optionally specify limit of results to return, default 500 | +| | start | Optional offset to start from (for pagination) | +| | filter | Object of "search_key" => "value" e.g. {"trunk": "930000- TEST"} would return CDRs only for the trunk named "930000- TEST".
At present you can filter only on the following values, more will be added in the future; **from, to, toISO, trunk, tag** | -| Method | Description | -| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET/POST | Both GET and POST are supported. The request can either be made as a GET query string or JSON POST body. At present, the filter attribute is only supported where requested by POST with a JSON body. | -| | *date_start* Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_start, otherwise defaults to start of current day.
**NB Dates must be specified in GMT, within the last 90 days** | -| | *date_end* Optionally specify date/time in YYYY-MM-DD HH:ii:ss format to request report from date_end, otherwise defaults to now. | -| | *limit* Optionally specify limit of results to return, default 500 | -| | *start* Optional offset to start from (for pagination) | -| | *filter* Object of "search_key" => "value" e.g. {"trunk": "930000- TEST"} would return CDRs only for the trunk named "930000- TEST". | -| | At present you can filter only on the following values, more will be added in the future: **from, to, toISO, trunk, tag** | - -``` -/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD} -``` - -| Method | Description | -| :------- | :------------------------------------------------------------------------------------------------------------------- | -| GET/POST | As above, a shorthand way of retrieving CDRs for a particular day. The date must be within the last 90 calendar days | -| | *limit* Optionally specify limit of results to return, default 500 | -| | *start* Optional offset to start from (for pagination) | -| | *filter* As above | +`/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}` +| Method| Description| +|:--|:--|:--| +| **GET/POST** | | As above, a shorthand way of retrieving CDRs for a particular day. The date must be within the last 90 calendar days | +| | limit | Optionally specify limit of results to return, default 500| +| | start | Optional offset to start from (for pagination) | +| | filter| As above| -``` -/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}/{REFERENCE} -``` +
+*/v3/voice/{ACCOUNT}/cdr/{YYYY-MM-DD}/{REFERENCE}* + + + + + +
GET Retrieve more information, where available, on a specific call using the reference value returned from the above CDRs (or the CDR Reporting) - +
**This function is temporarily unavailable as of version v3.10.5 ** @@ -1336,62 +1233,18 @@ Retrieve more information, where available, on a specific call using the referen ### Rejected Calls -``` -/v3/voice/{ACCOUNT}/rejected -``` - When calls are rejected by Simwood for any reason (e.g. exceeding a channel limit, invalid CLI information, or because they are on a blacklist or your own do not call list) no CDR is generated and, therefore, they cannot be retrieved with the above endpoints. These rejections are notified using the notification endpoint you have configured (e.g. by eMail or HTTP post) Additionally, the most recent rejections can be retrieved from the following API endpoints. - - - -| Method | Description | -| :----- | :----------------------------------------- | -| GET | Get all available recently rejected calls. | - - - - - -```json - -{ - "success": true, - "data": [ - { - "calldate": "2016-02-08 07:00:04", - "reason": "maxcost", - "from": "441632496000", - "to": "447700900123", - "message": "Call to 447700900123 will exceed 0.1 ( 0.25450 )", - "source_ip": "10.0.0.0", - "trunk": "9XXXXX-L001", - "notified": false - } - ] -} -``` - - - - - -``` -/v3/voice/{ACCOUNT}/rejected/{REASON} -``` - - - - +`/v3/voice/{ACCOUNT}/rejected` - | Method | Description | - | :----- | :--------------------------------------------------------------------- | - | GET | As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli"). | - - + + + + ```json @@ -1411,10 +1264,24 @@ These rejections are notified using the notification endpoint you have configure ] } ``` - - + + + +
GET Get all available recently rejected calls +
+ +`/v3/voice/{ACCOUNT}/rejected/{REASON}` + + + + + + +
GET +As above, but an optional REASON is specified to return only rejections of the specified reason (e.g. "maxcost" or "cli") +
+ **NB** Rejection data should be considered ephemeral. In any event the above endpoints will never return more than data from the current day and the preceding day. ## Voice Trunks @@ -1423,58 +1290,51 @@ These rejections are notified using the notification endpoint you have configure ### Trunk Management -``` -/v3/voice/{ACCOUNT}/trunks -``` - -Trunks should following the naming ACCOUNT-{ID} e.g. if your account is 930004 and the trunk for ACME Products you could name the trunk 930004-ACMEPRODUCTS. +Trunks should following the naming ACCOUNT-{ID} e.g. if your account is 930004 and the trunk for ACME Products you could name the trunk 930004-ACMEPRODUCTS.
The "L001" trunk is your default **IP-Authenticated** trunk and cannot be renamed, additionally there are some features (Trunk Balances, Realtime Trunk Calls in Progress etc) that are not available on the L001 trunk. +`/v3/voice/{ACCOUNT}/trunks` -| Method | Description | -| :----- | :------------------------------- | -| GET | List all active outbound trunks. | + + + + + +
GET +List all active outbound trunks. +
-``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK} -``` +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}` | Method| Description| |:--|:--| -|GET | Request information on specified {TRUNK} | -| PUT | Create new trunk {TRUNK}| -||NB for an ‘auth' trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions) or (if additional optional configuration parameters specified, see overleaf) Update existing {TRUNK} settings such as channel and rate limits.| -||When creating a new trunk, the **type** can be one of: **IP** create an IP-authenticated Trunk or **auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| -| DELETE | Delete trunk {TRUNK} **NB the default trunk {ACCOUNT}-L001 cannot be deleted** | +| **GET** | Request information on specified {TRUNK} | +| **PUT** | Create new trunk {TRUNK}
**NB for an ‘auth’ trunk the SIP password will be returned ONLY as a response to this API call and cannot be retrieved later. If you forget the password it can be reset as described below (Trunk Password Functions)

or (if additional optional configuration parameters specified, see overleaf)**
Update existing {TRUNK} settings such as channel and rate limits

When creating a new trunk, the **type** can be one of;
**IP** create an IP-authenticated Trunk
**auth** create a username/pass authenticated trunk. for compatibility, if not specified defaults to 'auth'| +| **DELETE** | Delete trunk {TRUNK}
**NB the default trunk {ACCOUNT}-L001 cannot be deleted** | Newly created trunks are available for use immediately although, at times, may not show in the outbound trunk list for a short time. #### Trunk Options +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}` -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK} -``` - -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| PUT | Update existing {TRUNK} settings such as channel and rate limits
**The options below are only to be used when updating an existing trunk** | -| | *enabled* *[optional]* Enable [1] or Disable [0] this trunk.
NB this takes precedence over in/out below | -| | *enable_in* *[optional]* Enable [1] or Disable [0] inbound calls on this trunk (when being used via SIP registration) | -| | *enabled_out* *[optional]* Enable [1] or Disable [0] outbound calls on this trunk. | -| | *limit_concurrent\_\* *[optional]* The * above to be replaced by one of the following parameters | -| | Concurrent channel limit for the class of calls indicated as an integer value or [null] (do not impose a limit) *out out_international*, *out_international_hotspot*, *out_per_number in* | -| | *limit_rate\_\* * *[optional]* Rate limit for each of the above outbound categories in the form calls/duration (or [null] where no limit) e.g: | -| | *5/10s* 5 calls per 10 seconds *100/12h*, 100 calls in 12 hours **NB The timeframe must be one of [ 12h \| 10s \| 1s ]** | -| | *cli_format* *[optional]* For inbound calls associated with this trunk, receive the CLI in the selected format, one of [ e164 \| +164 \| uk \| us ] | -| | *cli_default* *[optional]* Default Presentation Number to be presented when no valid CLI is provided or cli_force_default set (E164 format) | -| | *cli_force_default* *[optional]* Set to [1] to force above value to be used on all calls. [0] allows customer-specified CLI | -| | *nni_default* *[optional]* Default Network Number to be used when required **must be a number on your account** in E.164 format (e.g.441632960123) | -| | *max_cpm* *[optional]* Maximum cost per minute (in your billing currency) of the B leg of the call. Using this can help ensure a customer trunk cannot make calls to expensive destinations | -| | *max_cpc* *[optional]* To be used in conjunction with the above, sets a maximum connection cost per call. | -| | *max_cost* *[optional]* Sets a maximum cost per call, i.e. when the cost of the call reaches (approximately) this amount it will be cleared | -| | *max_dur* *[optional]* Sets a maximum duration per call, when the call reaches this duration, it will be cleared. | -| | *emergency_enabled* *[optional]* Set to [1] to enable emergency calls (requires account activation) | +| Method| Description| +|:--|:--|:--| +| **PUT** | | Update existing {TRUNK} settings such as channel and rate limits
**The options below are only to be used when updating an existing trunk**| +|| *enabled*
*[optionala]*| Enable [1] or Disable [0] this trunk.
NB this takes precedence over in/out below| +||*enable_in*
*[optional]* | Enable [1] or Disable [0] inbound calls on this trunk (when being used via SIP registration)| +|| *enabled_out*
*[optional]* | Enable [1] or Disable [0] outbound calls on this trunk. | +|| *limit_concurrent\_\* *
*[optional]*
The * above to be replaced by one of the parameters opposite | Concurrent channel limit for the class of calls indicated as an integer value or [null] (do not impose a limit)
**out out_international
out_international_hotspot out_per_number in** | +|| *limit_rate\_\* *
*[optional]* | Rate limit for each of the above outbound categories in the form calls/duration (or [null] where no limit) e.g.
**5/10s** 5 calls per 10 seconds
**100/12h** 100 calls in 12 hours
**NB The timeframe must be one of [ 12h \| 10s \| 1s ]** | +|| *cli_format*
*[optional]* | For inbound calls associated with this trunk, receive the CLI in the selected format, one of [ e164 \| +164 \| uk \| us ] | +|| *cli_default*
*[optional]* | Default Presentation Number to be presented when no valid CLI is provided or cli_force_default set (E164 format)| +|| *cli_force_default*
*[optional]* | Set to [1] to force above value to be used on all calls. [0] allows customer-specified CLI | +|| *nni_default*
*[optional]* | Default Network Number to be used when required **must be a number on your account** in E.164 format (e.g.441632960123) | +|| *max_cpm*
*[optional]* | Maximum cost per minute (in your billing currency) of the B leg of the call. Using this can help ensure a customer trunk cannot make calls to expensive destinations | +|| *max_cpc*
*[optional]* | To be used in conjunction with the above, sets a maximum connection cost per call.| +|| *max_cost*
*[optional]* | Sets a maximum cost per call, i.e. when the cost of the call reaches (approximately) this amount it will be cleared | +|| *max_dur*
*[optional]* | Sets a maximum duration per call, when the call reaches this duration, it will be cleared. | +|| *emergency_enabled*
*[optional]* | Set to [1] to enable emergency calls (requires account activation) | **NB** If you update a trunk and one or more parameters are invalid, the update will succeed with the **valid parameters**, please check the output returned and ensure the trunk is configured as you expect. @@ -1483,80 +1343,67 @@ Please note that all trunk settings are updated immediately, therefore disabling ### Trunk Balances - -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/balance -``` - Each trunk can have its own balance, this allows you to manage the spend of individual customers. You can also view "inprogress" information for a trunk which will show the value of calls in progress. Where the value of calls in progress exceeds the trunk balance, calls in progress will be ended. +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/balance` - -| Method | Description | -| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Get Balance for {Trunk} | -| PUT | Set or adjust the balance for {TRUNK} | -| | *balance* Sets the balance of the trunk to balance. | -| | **-or-** | -| | *adjust* Adjust the trunk balance by the amount shown, use negative amounts to decrement the balance. | -| DELETE | Remove the balance from trunk {TRUNK} **NB The trunk will function as before, without it's own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)** | +| Method| Description| +|:--|:--|:--| +| **GET** | Get Balance for {Trunk}| +| **PUT** | Set or adjust the balance for {TRUNK}
*balance* - Sets the balance of the trunk to balance
**-or-**
*adjust* - Adjust the trunk balance by the amount shown, use negative amounts to decrement the balance.| +| **GET** | Remove the balance from trunk {TRUNK}
**NB The trunk will function as before, without it’s own balance, so will be limited only by your account balance or balance lock
This is NOT EQUIVALENT TO setting a balance to 0 which would prevent further calls being made (i.e. Balance exhausted)**| **The trunk balance feature is provided for convenience and is not a substitute for your own billing and credit control procedures. Simwood will not be liable for any calls made on a trunk when its trunk-specific balance is depleted for any reason.** -**Examples:** -| **Set balance on trunk 920123-ACME to £200** | -| :------------------------------------------- | -| {"balance": 200} | +| **Set balance on trunk 920123-ACME to £200**| +|:--| +|{"balance": 200}| We strongly recommend that "balance" is used to set an initial balance only, and thereafter the level is maintained using the "adjust" function. -| **Adjust balance on trunk 920123-ACME by £50 (e.g. if Customer has topped up)** | -| :------------------------------------------------------------------------------ | -| {"adjust": 50} | +|**Adjust balance on trunk 920123-ACME by £50 (e.g. if Customer has topped up)**| +|:--| +| {"adjust": 50}| -| Adjust balance on trunk 920123-ACME by £20 (e.g. to deduct supplementary services) | -| :--------------------------------------------------------------------------------- | -| {"adjust": -20} | +|Adjust balance on trunk 920123-ACME by £20 (e.g. to deduct supplementary services)| +|:--| +| {"adjust": -20}| **NB Your account primary -L001 IP trunk does not support Trunk Balances.** ### Per-Trunk Realtime Call Information - -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/inprogress -``` - As with your account you can also view realtime "in progress" information on a per-trunk basis. +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/inprogress` - - - - | Method | Description | - | :----- | :-------------------------------------- | - | GET | Provides information on the calls currently in progress on the specified TRUNK | - - + + + + ```json { - "datetime": "2014-02-30 12:34:35", - "total": 1.164, - "callcount": 107, - "balance": 24.406, - "percent_available": 0.25, - "approx_seconds_remaining": 56838, + "datetime": "2014-02-30 12:34:35", + "total": 1.164, + "callcount": 107, + "balance": 24.406, + "percent_available": 0.25, + "approx_seconds_remaining": 56838, } ``` - - + + + +
GET +Provides information on the calls currently in progress on the specified TRUNK +
-Where a trunk has a balance the three additional elements will be present which have the same meaning as in your account snapshot but pertain only to the TRUNK specified: +Where a trunk has a balance the three additional elements will be present which have the same meaning as in your account snapshot but pertain only to the TRUNK specified; **balance, percent_available, and approx_seconds_remaining** @@ -1565,48 +1412,37 @@ These are omitted where a trunk has no balance, but you can still view the curre **NB Your account primary -L001 IP trunk does not support this feature.** ### Trunk IP Functions - The following applies only to trunks using IP-Based authentication, your primary trunk ({ACCOUNT}-L001) is an example of one such trunk which does not require a SIP username and password. Please ensure you only add IP addresses that you control and DELETE any that are no longer required. Please note that that this functionality should **NOT** be used to update an account with dynamic IP addresses - such installations, where unavoidable, should use authenticated SIP trunks as described above. -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl -``` -| Method | Description | -| :----- | :---------------------------------------------------------- | -| GET | Request a list of IP address authorised on ip-based {TRUNK} | -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl/{IP} -``` +||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl| +|:--|:--| +| **GET** |Request a list of IP address authorised on ip-based {TRUNK}| + +
-| Method | Description | -| :----- | :-------------------------------- | -| PUT | Add {IP} to ip-based {TRUNK} | -| DELETE | Remove {IP} from ip-based {TRUNK} | +||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/acl/{IP}| +|:--|:--| +| **PUT** |Add {IP} to ip-based {TRUNK}| +|**DELETE**|Remove {IP} from ip-based {TRUNK}| ### Trunk Password Functions The following applies only to authenticated trunks (those using a username and password) or being used for SIP registration. -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/password_reset -``` +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/password_reset` - - - -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | Request and return a new password for this trunk. | -| | NB The old password will be disabled immediately, any devices configured to use this trunk will need reconfigured to continue to make outbound calls. | - - - - + + + + ```json @@ -1617,8 +1453,11 @@ The following applies only to authenticated trunks (those using a username and p "pass":"e5d5aca5e39251bdc19554d3" } ``` - - + + + + +
POST +Request and return a new password for this trunk.
+NB The old password will be disabled immediately, any devices configured to use this trunk will need reconfigured to continue to make outbound calls. +
**NB** It is not possible to specify a password for a trunk, they are automatically generated. @@ -1629,113 +1468,74 @@ is to reset the password using the above functionality. Please keep your passwor ### Outbound Destination Prefix ACLs Not to be confused with IP ACLs (to determine which IPs can make outbound calls on a particular trunk) Destination Prefix ACLs allow you to limit access on a per-account of per-trunk basis to certain destinations. -The ACL is specified in a JSON-encoded object as follows: +The ACL is specified in a JSON-encoded object as follows; -| Variable | Description | -| :------- | :-------------------------------------------- | -| *allow* | Array Allowed Prefixes e.g. [441,442,443,448] | -| *deny* | Array Denied Prefixes e.g. [44870] | - -This would be encoded in JSON as follows: +|| +|:-| +|allow Array Allowed Prefixes e.g. [441,442,443,448]| +|deny Array Denied Prefixes e.g. [44870]| +This would be encoded in JSON as follows; ```json -{ - "allow": - [441,442,443,448], - "deny": - [44870] -} +{"allow":[441,442,443,448],"deny":[44870]} ``` This example would allow calls to all UK Geographic, 03 Numbers and all 08 Numbers except 0870. - -Please note: -(1) Longest prefix matching is used, so 44870 in the **deny** list will block even if 448 is allowed. -(2) If only **allow** is specified, this is treated as a whitelist. all other destinations will be denied. -(3) If only **deny** is specified, this is treated as a blacklist. all other destinations will be allowed. +
+Please note
+(1) Longest prefix matching is used, so 44870 in the **deny** list will block even if 448 is allowed.
+(2) If only **allow** is specified, this is treated as a whitelist. all other destinations will be denied.
+(3) If only **deny** is specified, this is treated as a blacklist. all other destinations will be allowed.
(4) Account-level blocks will override any trunk settings. -(e.g. a trunk cannot call a destination blocked at the account level). +(e.g. a trunk cannot call a destination blocked at the account level)
(5) Trunk level blocks will override any account-level allows. (e.g. you may deny certain trunks access to destinations that are otherwise allowed) -``` -/v3/voice/{ACCOUNT}/outbound/destinationacl -``` +`/v3/voice/{ACCOUNT}/outbound/destinationacl` -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/destinationacl -``` +`/v3/voice/{ACCOUNT}/trunks/{TRUNK}/destinationacl` -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GET | Retrieve active ACL on your account or trunk as specified | -| PUT | Replace active ACL with the JSON object PUT. **The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload'** | -| DELETE | Remove the ACL associated with the account or trunk **Please note that the default is to allow access to ALL destinations without restriction - please ensure this is what you want.** | +| Method| Description| +|:-|:-| +|**GET**|Retrieve active ACL on your account or trunk as specified| +|**PUT**|Replace active ACL with the JSON object PUT.
**The preferred method of doing this is to send the new ACL as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’**| +|**DELETE**|Remove the ACL associated with the account or trunk
**Please note that the default is to allow access to ALL destinations without restriction - please ensure this is what you want.**| -Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE: - **X-Reason: 447700900123 matches trunk do not route 447** - **X-Reason: 449098790000 matches customer do not route 449** +Calls rejected due to failing a destination ACL rule will have the following X-Reason headers set in the SIP response to the initial INVITE;
+ **X-Reason: 447700900123 matches trunk do not route 447**
+ **X-Reason: 449098790000 matches customer do not route 449**
-Either one of these may have (cached) appended where the number has been blocked more than once in the last 60s, in such case the prefix may not be shown. +Either one of these may have (cached) appended where the number has been blocked more than once in the last 60s, in such case the prefix may not be shown.
-**NB** The above ‘destination acl' function is provided on a ‘best-efforts' basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account. +**NB** The above ‘destination acl’ function is provided on a ‘best-efforts’ basis and is not intended as a substitute for securing your own VoIP platform. You remain responsible for all calls made on your account. ### Trunk Routing Configuration It is now possible to set a trunk-level routing configuration which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls for a group of numbers to one destination, and another group of numbers to a different destination. -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config -``` - -| Method | Description | -| :----- | :----------------------------------------------------- | -| GET | Return configuration for {TRUNK} | -| PUT | Replace active configuration with the JSON object PUT. | -| DELETE | Remove configuration for {TRUNK} | +||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config| +|:-|:-| +|**GET**|Return configuration for {TRUNK}| +|**PUT**|Replace active configuration with the JSON object PUT.| +|**DELETE**|Remove configuration for {TRUNK}| For full syntax and available options please refer to [Number Routing Configuration](#number-routing-configuration) below. ### Bulk Number Association As detailed below, inbound numbers can be associated with a trunk either for billing purposes only, or to make use of its additional controls and/or routing configuration (where one does not exist on the number itself). These associations can be created individually by updating each number as required, or where multiple numbers are to be associated with the same trunk, it can be performed in a single request using the following endpoint. -**NB** If a number has its own specific routing configuration, then any trunk association defined in the ‘options' block will continue to take priority. - -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/numbers -``` +**NB** If a number has its own specific routing configuration, then any trunk association defined in the ‘options’ block will continue to take priority. - - - -| Method | Description | -| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Return the currently associated numbers. | -| PUT | Associate more numbers to the trunk, passing the numbers you wish to append as an array, per the example below. | -| | { "data": [ "443301223003", "443301223004", "443301223005", ... ] } | -| POST | Replace the list of associated numbers entirely, passing the numbers you wish to replace it with as an array. Passing an empty array will remove any direct associations with this trunk. **NB** All existing associations with this trunk will be removed! | -| | { “data”: [ “443301223100”, “443301223101”, “443301223102”, ... ]} | - - - -```json - -{ - "success": true, - "data": [ - "443301223000", - "443301223001", - "443301223002" - ] -} -``` - - +||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/numbers| +|:-|:-| +|**GET**|Return the currently associated numbers
{ "success": true, "data": [ "443301223000", "443301223001", "443301223002", ... ] }| +|**PUT**|Associate more numbers to the trunk, passing the numbers you wish to append as an array, per the example below
{ "data": [ "443301223003", "443301223004", "443301223005", ... ] }| +| **POST** | Replace the list of associated numbers entirely, passing the numbers you wish to replace it with as an array. Passing an empty array will remove any direct associations with this trunk.
**NB** All existing associations with this trunk will be removed!
{ “data”: [ “443301223100”, “443301223101”, “443301223102”, ... ]} | When associating numbers to a trunk, any individual routing configuration currently set on those numbers will need to be removed if your intention is for the configuration of the newly associated trunk to be followed. You -can do this for each number individually using the number's own configuration endpoint, or alternatively, if you +can do this for each number individually using the number’s own configuration endpoint, or alternatively, if you wish to remove all number-level configuration at the same time as associating with the trunk, you can include the optional force property: ```json @@ -1756,34 +1556,24 @@ the optional force property: You can access your outbound SIP rates from any* standard BT landline using our shared IDA code **12940**. Access is restricted to authorised CLIs. -IDA users are managed much like trunks (see above), each number added automatically creates a ‘trunk' in the form {ACCOUNT}-IDA01xxxxxxxxx, you will see these identifiers as the trunk in your CDRs and the same settings can be applied as to trunks (see above) - -``` -/v3/voice/{ACCOUNT}/ida -``` -| Method | Description | -| :----- | :----------------------------------- | -| GET | Retrieve active IDAs on your account | - -``` -/v3/voice/{ACCOUNT}/ida/{CLI} -``` - -| Method | Description | -| :----- | :--------------------------------------------------------------------------------------------------------- | -| GET | Retrieve active IDAs on your account | -| PUT | Create a new IDA user with the specified {CLI} **or (if additional parameters are supplied)** | -| | update an existing IDA user (see above "Trunk Management" for an example of what parameters are available) | -| DELETE | Delete the IDA user with the specified {CLI} | +IDA users are managed much like trunks (see above), each number added automatically creates a ‘trunk’ in the form {ACCOUNT}-IDA01xxxxxxxxx, you will see these identifiers as the trunk in your CDRs and the same settings can be applied as to trunks (see above) +||/v3/voice/{ACCOUNT}/ida| +|:-|:-| +|**GET**|Retrieve active IDAs on your account| +||/v3/voice/{ACCOUNT}/ida/{CLI}| +|:-|:-| +|**GET**|Retrieve the details associated with this IDA User| +|**PUT**|Create a new IDA user with the specified {CLI}
**or (if additional parameters are supplied)**
update an existing IDA user (see above "Trunk Management" for an example of what parameters are available)| +|**DELETE**|Delete the IDA user with the specified {CLI}| Users making calls using the IDA service should dial the full number prefixed with 12940 e.g. to call 029 2120 2120 you would dial **1294002921202120** -1. At present you cannot associate more than one CLI with a single IDA ‘trunk' +1. At present you cannot associate more than one CLI with a single IDA ‘trunk’ 2. If another Simwood customer has enabled a CLI for the IDA service you will not be able to associate the same CLI with your own account. -*Some landlines may not permit IDA calls* +\* Some landlines may not permit IDA calls **IDA for Virtual Interconnect ("Hosted IDA")** Virtual Interconnect - Inbound customers using their own IDA codes should not use the above functionality. Please contact us for more information on IDA for Virtual Interconnect. @@ -1792,104 +1582,100 @@ Virtual Interconnect - Inbound customers using their own IDA codes should not us ### Number Allocation #### UK Number Ranges +`/v3/numbers/{ACCOUNT}/ranges` -``` -/v3/numbers/{ACCOUNT}/ranges -``` - - -| Method | Description | -| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GET | Retrieves a list of all available UK number ranges, including descriptions. This is intended for customers to populate, for example, a drop down to allow customers to select an area | -| | NB: This does not return international numbering at this time. | - - + + + + ```json { - "success": true, - "data": [ - { - "id": "03dd542cafcecf43fc06024ee6099311424c71cf", - "prefix": "113403", - "sabc": "1134", - "description": "Geographic - Leeds", - "chargeband": "geo" - },{ - "id": "3d80bd92a9ba2ca31c646881127d322a", - "prefix": "113499", - "sabc": "1134", - "description": "Geographic - Leeds", - "chargeband": "geo" - }, - ... - ] + "success": true, + "data": [ + { + "id": "03dd542cafcecf43fc06024ee6099311424c71cf", + "prefix": "113403", + "sabc": "1134", + "description": "Geographic - Leeds", + "chargeband": "geo" + }, + { + "id": "3d80bd92a9ba2ca31c646881127d322a", + "prefix": "113499", + "sabc": "1134", + "description": "Geographic - Leeds", + "chargeband": "geo" + }, + ... + ] } -``` - - +``` + + + + + +
GET +etrieves a list of all available UK number ranges, including descriptions. This is intended for customers to populate, for example, a drop down to allow customers to select an area
+NB This does not return international numbering at this time. + +
#### Available Numbers +||/v3/numbers/{ACCOUNT}/available/[all\|gold\|standard]/[1\|10\|100]| +|:-|:-| +|**GET**|Returns 1,10 or 100 numbers available for allocation matching the pattern specified.
One of all, gold, or standard should be specified in the URL;
**all** returns all available numbers matching *pattern*
**gold** returns only gold numbers matching *pattern*
**standard** returns only non-gold numbers matching *pattern*| +||***pattern***
Search for numbers matching specified pattern (can use wildcards e.g \*203\*)
**NB** For backward compatibility, please note that if country_code is not set, a search for 4420\* and 20\* are identical and are assumed to be UK numbers (without the leading 0). Similarly, a search for 1212\* will be assumed to be the UK (0121 2\*), NOT the USA 1-212.| +||***country_code***
Optional country code, currently only one of [1\|44] Defaults to 44 for UK numbering, use 1 for USA numbering.| +||[{ "country_code":"44", "number":"1134032330", "recommended_gold_premium": 0, "wholesale_gold_premium" 0, "block":"03dd542cafcecf43fc06024ee6099311424c71cf", "bill_class":"Carrier", "SMS": 0 }]| -``` -/v3/numbers/{ACCOUNT}/available/[all\|gold\|standard]/[1\|10\|100] -``` -| Method | Description | -| :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Returns 1,10 or 100 numbers available for allocation matching the pattern specified.One of all, gold, or standard should be specified in the URL:*all* returns all available numbers matching *pattern* **gold** returns only gold numbers matching *pattern* *standard* returns only non-gold numbers matching *pattern* | -| | *pattern* Search for numbers matching specified pattern (can use wildcards e.g \*203\*) **NB** For backward compatibility, please note that if country_code is not set, a search for 4420\* and 20\* are identical and are assumed to be UK numbers (without the leading 0). Similarly, a search for 1212\* will be assumed to be the UK (0121 2\*), NOT the USA 1-212. | -| | *country_code* [Optional] country code, currently only one of [1\|44] Defaults to 44 for UK numbering, use 1 for USA numbering. | -``` -/v3/numbers/{ACCOUNT}/available/consecutive/[10\20\30\40\50\60\..100] -``` +
-| Method | Description | -| :----- | :----------------------------------------------------- | -|POST|Request a report of 10,20,30,40,50,60,70,80,90 or 100 consecutive numbers available for allocation matching the pattern specified.*NB* This function currently does not support country_code or non UK searches| +||/v3/numbers/{ACCOUNT}/available/consecutive/[10\|20\|30\|40\|50\|60\|..100]| +|:-|:-| +|**POST**|Request a report of 10,20,30,40,50,60,70,80,90 or 100 consecutive numbers available for allocation matching the pattern specified.
**NB** This function currently does not support country_code or non UK searches| ||*pattern* Search for numbers matching specified pattern (can use wildcards e.g *203*)| -Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported. +Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported.
**NB** Some number types, e.g. OTT Mobile Numbers are only available as gold numbers at this time. #### Allocated Numbering - -| Method | Description | -| :----- | :----------------------------------------------------- | -| POST| Request a report of all current allocated numbers on account.| +|||/v3/numbers/{ACCOUNT}/allocated/all| +|:-|:-|:-| +|**POST**||Request a report of all current allocated numbers on account.| ||*pattern*|Optionally specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*)| -||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)**NB Keys are case-insensitive, wildcards not supported.**| +||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)
**NB Keys are case-insensitive, wildcards not supported.**| ||*filter_config*|Only return numbers that have their own individual routing configuration.| -``` -/v3/numbers/{ACCOUNT}/allocated/[10\|100\|1000\|10000] -``` -| Method | Description | -| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | Request a report of the first [ 10 \| 100 \| 1,000 \| 10,000 ] numbers that match the optional pattern. | -| | *pattern* [Optional] specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*) | -| | *key* [Optional] Only return those numbers that match the specified key in their metadata (see Advanced Routing below) **NB Keys are case-insensitive, wildcards not supported.** | -| | *filter_config* [Optional] Only return numbers that have their own individual routing configuration. | + +
+ +|||/v3/numbers/{ACCOUNT}/allocated/[10\|100\|1000\|10000]| +|:-|:-|:-| +|**POST**||Request a report of the first [ 10 \| 100 \| 1,000 \| 10,000 ] numbers that match the optional pattern.| +||*pattern*|Optionally specify to include only those numbers that match the specified pattern(can use wildcards e.g \*203\*)| +||*key*|Only return those numbers that match the specified key in their metadata (see Advanced Routing below)
**NB Keys are case-insensitive, wildcards not supported.**| +||*filter_config*|Only return numbers that have their own individual routing configuration.| Please note the above options (e.g. 1|10|100) are the only options, arbitrary values (e.g. /25) are not supported. -``` -/v3/numbers/{ACCOUNT}/allocated/{NUMBER} -``` -| Method | Description | -| :----- | :-------------------------------------------------------- | -| GET | Return configuration information on allocated {NUMBER} | -| PUT | Allocate an available {NUMBER} to the account | -| DELETE | De-configure and irrevocably remove {NUMBER} from account | + +|||/v3/numbers/{ACCOUNT}/allocated/{NUMBER}| +|:-|:-| +|**GET**|Return configuration information on allocated {NUMBER}| +|**PUT**|Allocate an available {NUMBER} to the account| +|**DELETE**|De-configure and irrevocably remove {NUMBER} from account| **$ Gold Number Activation Fee** Where {NUMBER} is a Gold Number an activation fee will be charged @@ -1897,36 +1683,31 @@ Please note the above options (e.g. 1|10|100) are the only options, arbitrary va #### Last Call +`/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/lastcall` -``` -/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/lastcall -``` - - - - - -| Method | Description | -| :----- | :------------------------------------------------------------------- | -| GET | Returns a JSON object describing the most recent call to this number | - - - + + + + ```json { - "success":true, - "data": { - "calldate":"2017-05-01 12:34:01", - "cli":"07700900123", - "disposition":"NORMAL_CLEARING", - "billsec":"64", - "duration":"68" - } -} + "success":true, + "data": { + "calldate":"2017-05-01 12:34:01", + "cli":"07700900123", + "disposition":"NORMAL_CLEARING", + "billsec":"64", + "duration":"68" +} } ``` - - + + + + +
GET +Returns a JSON object describing the most recent call to this number +
### Number Routing Configuration @@ -1934,73 +1715,61 @@ Introduced in May 2014, the following is the preferred way of configuring a numb When a new configuration is provided this will take precedence over any existing configuration. -``` -/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config -``` - - - - -| Method | Description | -| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | Return configuration information on allocated {NUMBER} | -| PUT | Replace active configuration for {NUMBER} with the JSON object PUT. | -| | The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload' | -| DELETE | De-configure the configuration of {NUMBER} **NB** if configuration is still present on the /voice endpoint, it will be used | +`/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/config` - - +**GET** Return configuration information on allocated {NUMBER} +**See Configuration Syntax (New) below** ```json { "routing": { - "default": [ - [ - { - "type": "sip", - "endpoint": "441632960000@pbx.simwood.com" - },{ - "type": "reg", - "user": "930XXX-SIPUSER" - } - ],[ - { - "type": "pstn", - "number": "447700900123" - } - ] - ] - } -} + "default": [ + [ + { + "type": "sip", + "endpoint": "441632960000@pbx.simwood.com" + }, + { + "type": "reg", + "user": "930XXX-SIPUSER" + } + ], + [ + { + "type": "pstn", + "number": "447700900123" + } + ] + ] + } + } ``` - - -Similarly, it is now possible to set a [trunk-level configuration](#trunk-routing-configuration) which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls to a group of numbers to a single destination, and another group of numbers to a different destination. -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config -``` -| Method | Description | -| :----- | :----------------------------------------------------- | -| GET | Return configuration for {TRUNK} | -| PUT | Replace active configuration with the JSON object PUT. | -| DELETE | Remove configuration for {TRUNK} | +| Method| Description| +|:-|-| +|**PUT**|Replace active configuration for {NUMBER} with the JSON object PUT.
**The preferred method of doing this is to send the new routing configuration as the body of the PUT request, however if your implementation does not support this you may send the entire string in a single HTTP form encoded variable ‘payload’**
{"success": true}
If any error(s) occurred whilst validating the configuration these will be shown;
{ "success": false, "errors": [ "Message #1", "Message #2" ] }| +|**DELETE**|De-configure the configuration of {NUMBER}
**NB** if configuration is still present on the /voice endpoint, it will be used| -Lastly, the default configuration will be used for all numbers on your account where no other configuration exists - this is ideal for customers who send all calls to a SIP URI and handle onward routing themselves +Similarly, it is now possible to set a [trunk-level configuration](#trunk-routing-configuration) which will be used for any numbers associated with it (and not having their own configuration) - this is ideal for customers who send calls to a group of numbers to a single destination, and another group of numbers to a different destination. -``` -/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config -``` +||/v3/voice/{ACCOUNT}/trunks/{TRUNK}/config| +|:-|:-| +|**GET**|Return configuration for {TRUNK}| +|**PUT**|Replace active configuration with the JSON object PUT.| +|**DELETE**|Remove configuration for {TRUNK}| + +
+Lastly, the default configuration will be used for all numbers on your account where no other configuration exists - this is ideal for customers who send all calls to a SIP URI and handle onward routing themselves -| Method | Description | -| :----- | :------------------------------------------------------------- | -| GET | Return configuration for {ACCOUNT} | -| PUT | Replace active default configuration with the JSON object PUT. | -| DELETE | Remove default configuration | +||/v3/numbers/{ACCOUNT}/default/config| +|:-|:-| +|**GET**|Return default number configuration for {ACCOUNT}| +|**PUT**|Replace active default configuration with the JSON object PUT| +|**DELETE**|Remove default configuration| #### Number Configuration Syntax - Advanced **NB** The syntax described in this section applies equally to number, trunk, and default configuration @@ -2011,74 +1780,97 @@ Numbers are configured using a JSON object which is described below, offering in An example (annotated) configuration is below, and the full list of options can be found overleaf. - + + + + + -Rules define times of day that routing blocks (below) apply, outwith the rules given - or if the rules section is omitted entirely - the default routing block will be used. - + + + + + + + + + + + + + + + + + + + + + + + + +
```json "rules": { - "mon__fri_0700__1700": [ - { - "dow": [1,2,3,4,5], - "time": ["0700","1700"] - } - ] + "mon__fri_0700__1700": [ + { + "dow": [1,2,3,4,5], + "time": ["0700","1700"] + } + ] }, ``` +Rules define times of day that routing blocks (below) apply, outwith the rules given - + or if the rules section is omitted entirely - the default routing block will be used.
```json "routing": { - "mon__fri_0700__1700": [ - [ - { - "type": "reg", - "user": "939998-FREDTEST", - "timeout": 30, - "sdes": "optional", - "opus": "default" - } - ], + "mon__fri_0700__1700": [ + [ + { + "type": "reg", + "user": "939998-FREDTEST", + "timeout": 30, + "sdes": "optional", + "opus": "default" + } + ], ``` - -This block will run during the *officehours* time block defined above (Mon-Fri 9am-5pm) +This block will run during the officehours time block defined above (Mon-Fri 9am-5pm) and will call the SIP endpoint shown and the user on the registration proxy simultaneously. +
```json [ - { - "type": "sip", - "endpoint": "%e164@pbx.mycompany.com", - "timeout": 30, - "sdes": "none", - "opus": "default" - } - ],[ - { - "type": "pstn", - "number": "447405644486" - } + { + "type": "sip", + "endpoint": "%e164@pbx.mycompany.com", + "timeout": 30, + "sdes": "none", + "opus": "default" + } + ], + [ + { + "type": "pstn", + "number": "447405644486" + } ] - ], +], ``` -After the timeout above (30s) we will try the PSTN number provided +After the timeout above (30s) we will try the PSTN number provided
```json - "default": [ - [ - { - "type": "pstn", - "timeout": 30, - "number": "447405644486", - "trunk": "939998-ALAUTHTEST" - } + "default": [ + [ + { + "type": "pstn", + "timeout": 30, + "number": "447405644486", + "trunk": "939998-ALAUTHTEST" + } + ] ] - ] }, ``` -The *default* routing block will be used outwith the office hours specified above. +The default routing block will be used outwith the office hours specified above. So calls outside of normal office hours will be forwarded directly to the PSTN number shown. +
```json "options": { @@ -2090,14 +1882,21 @@ So calls outside of normal office hours will be forwarded directly to the PSTN n }, ``` -Per number configuration options (detailed above) apply to the number at all times +Per number configuration options (detailed above) apply to the number at all times
```json -{ - "meta": [] + "meta": [] } ``` -The *meta* block contains arbitrary metadata that you want to associate with the number. +The meta block contains arbitrary metadata that you want to associate with the number
#### Number Configuration Syntax @@ -2106,12 +1905,12 @@ The *meta* block contains arbitrary metadata that you want to associate with the The following options can be set on a per-number basis, they apply to the entire configuration at all times -|Option|Parameters|Description|Default| -|:--|:--|:--|:--| +|Option||Description|| +|:-|:-|:-|-| |*enabled*|[true\|false]|Allows number to be disabled [false] without removing the configuration.|Default [true]| |*block_payphone* | [true\|false] | Prevents inbound calls originating from payphones |Default [false]| |*acr*|[true\|false]|Apply ACR to this number. ACR Prevents calls originating from Withheld numbers reaching this number. Withheld callers will be diverted to a recorded announcement.|Default [false]| -|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg' routing block.

You can also configure this using the endpoint /v3/numbers/{ACCOUNT}/allocated/ {NUMBER}/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| +|**trunk**|9XXXXX-TRUNK|Associate a trunk with this number for billing purposes ONLY, shown in CDRs.

**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block.

You can also configure this using the endpoint /v3/numbers/[ACCOUNT]/allocated/ {NUMBER]/trunk.

This option is only relevant for number-level configuration.|Default [9XXXXX-L001] or your account default inbound trunk if different.| #### **$.. Chargeable Options** @@ -2120,10 +1919,10 @@ Please see https://simwood.com/rates for full information #### "rules" -The ‘rules' parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters: +The ‘rules’ parameter in the JSON object should be an array of named objects (named using the characters a- z and the _ character only) each of which defines a time period using the following parameters; -|Parameter|Format|Description| -|:--|:--|:--| +|Parameter||description| +|:-|:-|:-| |*dow*|Array of values [1..7]|The days of week this rule is active (according to ISO 8601) e.g. **1 = Monday, 7 = Sunday.**
**NB if one day must still be an array. e.g. [3] not 3**| |*time*|Array [start,end]|Array of two values, denoting the start and end time this rule applies in 24h format (e.g. [0900,1700] would represent 9am - 5pm. The leading 0 can be omitted)| |day|Array of values [1..31]|The days of month this rule is active **NB if one day must still be an array. e.g. [25] not 25**| @@ -2132,114 +1931,144 @@ The ‘rules' parameter in the JSON object should be an array of named objects ( **Example** -Office Hours - Mon - Fri 0900-1700 -```json -{ - "rules":{ - "officehours": [ - { - "dow": [1,2,3,4,5], - "time": [900,1700] - } - ] - } + + + + + + + -Weekends - Sat/Sun (All Day) + + + + + -```json -"rules": { - "christmasholiday": [ - { - "month": [12], - "day": [25,26] - },{ - "month": [1], - "day": [1,2] - } - ] -} + + + + + + + + +
Office Hours +Mon - Fri
0900-1700 +		 + +```bash +"rules": { + "officehours": [ + { + "dow": [1,2,3,4,5], + "time": [900,1700] +} ] } ``` +
Weekends +Sat/Sun
(All Day) +		 -```json -{ - "rules": { +```bash +"rules": { "weekend": [ - { - "dow": [6,7] - } - ] - } + { + "dow": [6,7] +} ] } ``` -Christmas / New Year - Dec 25th , December 26th, January 1st, January 2nd +
Christmas / New Year +
Dec 25th +
December 26th +
January 1st +
January 2nd +		 +```bash +"rules": { + "christmasholiday": [ +{ +"month": [12], + "day": [25,26] + },{ + "month": [1], + "day": [1,2] + } +] } ``` +
#### "routing" -Much like the rules above the ‘routing' property is an array of objects named corresponding to the rules. There is also the special ‘default' rule, which applies when there are no rules specified or outwith the times specified in the rules. +Much like the rules above the ‘routing’ property is an array of objects named corresponding to the rules. There is also the special ‘default’ rule, which applies when there are no rules specified or outwith the times specified in the rules. **NB** This property is mandatory and submitted config will be rejected without it. Routing blocks (described below) can be arranged to allow dialling in parallel or in sequence, or a -combination of both as shown below: +combination of both as shown below; **Ring A & B simultaneously, Then C** ```json "routing": { - "officehours": [ - [ - { BLOCK A }, - { BLOCK B } - ],[ - { BLOCK C } - ] - ] + "officehours": [ +[ +{ +BLOCK A }, +{ +BLOCK B +} ], +[ +{ +BLOCK C } +] ] } ``` **Ring A, B and C simultaneously** ```json "routing": { - "officehours": [ - [ - { BLOCK A }, - { BLOCK B }, - { BLOCK C } - ] - ] + "officehours": [ +[ +{ +BLOCK A }, +{ +BLOCK B +}, { +BLOCK C } +] ] } ``` **Ring A, then B, then C** ```json "routing": { - "officehours": [ - [ - { BLOCK A }, - ],[ - { BLOCK B } - ],[ - { BLOCK C } - ] - ] + "officehours": [ +[ +{ +BLOCK A }, +], [ +{ +BLOCK B +} ], +[ +{ +BLOCK C } +] ] } ``` #### "meta" -The ‘meta' parameter in the JSON object allows you to store your own arbitrary data in the Simwood database associated with a number and which can be easily accessed via the API. +The ‘meta’ parameter in the JSON object allows you to store your own arbitrary data in the Simwood database associated with a number and which can be easily accessed via the API. The **key** parameter can be used to search for number(s) matching a specified key, the rest of the object is freeform up to a size limit of around 512 bytes. - -|key|String[40 chars]| -|:--|:--| -| | A (non-unique) key for this number which you can use to search for matching numbers, most commonly customers use this to store a representation of their own customer account ID or username.
**NB Keys are treated as case-insensitive**| - -The rest of the **meta** parameter can be composed of ANY valid JSON structure, some example uses are given below. +|||| +|:-|-|-| +|key|String[40 chars]| A (non-unique) key for this number which you can use to search for matching numbers, most commonly customers use this to store a representation of their own customer account ID or username.
**NB Keys are treated as case-insensitive**| +| .. | .. |The rest of the **meta** parameter can be composed of ANY valid JSON structure, some example uses are given below.| #### Examples @@ -2250,13 +2079,12 @@ The friendlyName is used to allow the customer to assign a memorable name to the The lastUpdated parameter is used to show when a number was last updated. @@ -2266,26 +2094,24 @@ The lastUpdated parameter is used to show when a number was last updated.
-```json -"meta": { - "key": "403010", - "friendlyName": "Main office number", - "lastUpdated": "2014-02-30 01:20:30" -} -``` + + "meta": { + "key": "403010", + "friendlyName": "Main office number", + "lastUpdated": "2014-02-30 01:20:30" + }
-```json -"meta": { - "key": "customer@example.com", - "pass": "secretWord" -} -``` + "meta": { + "key": "customer@example.com", + "pass": "secretWord" + }
- This shows how this could be used to store a note associated with a number that hasn't been configured yet. + This shows how this could be used to store a note associated with a number that hasn’t been configured yet. -```json -"meta": { - "notes": "This is reserved for Brian at Example Corp", - "reserved": true -} -``` + "meta": { + "notes": "This is reserved for Brian at + Example Corp and is not yet in use", + "reserved": true + } +
@@ -2296,7 +2122,7 @@ The flexibility offered by the "meta" block enables customers to build a full se **NB** Meta attributes are intended for API use only and are NOT displayed in the portal. These attributes may be overwritten if a number is later configured using the portal. #### Routing Block -Each routing block is defined by a minimum of a ‘type' and some optional parameters delay and timeout: +Each routing block is defined by a minimum of a ‘type’ and some optional parameters delay and timeout; |***parameter***|***values***|| |:-|-|:-| @@ -2313,21 +2139,21 @@ Each routing block is defined by a minimum of a ‘type' and some optional param It is not possible to simultaneously use the same number for voice and fax. #### Routing Block Additional Parameters -Depending on the type of endpoint selected above there are some additional endpoint-specific mandatory and optional parameters: +Depending on the type of endpoint selected above there are some additional endpoint-specific mandatory and optional parameters; |type| parameter|| |:-|:-|-| -|**sip**|*endpoint*|SIP Endpoint (user@host.com with optional :port and :transport parameters e.g. %164@example.com:5060:transport=tcp) the following substitutions will take place:
**%e164** will be replaced with the full number in **E164** format
**%ukn** will be replaced with the number in **UK National** format| +|**sip**|*endpoint*|SIP Endpoint (user@host.com with optional :port and ;transport parameters e.g. %164@example.com:5060;transport=tcp) the following substitutions will take place;
**%e164** will be replaced with the full number in **E164** format
**%ukn** will be replaced with the number in **UK National** format| ||*sdes*|One of **optional, required,** or **none**. If optional we will offer SDES encryption for the audio on inbound calls. If set to required, the call will not complete without successful negotiation of SDES. If not specified, or set to none, SDES will not be offered by default.| -||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform:

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| +||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform;

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| ||*zone*|One of our zone names [**slo, lon, ny** or **sj**]..

If present, calls originating in the specified zone will be passed to this endpoint, overriding any equal priority endpoints without a zone specified.
This can be used together with multiple sip endpoints to ensure that calls are routed in the most efficient way depending on where they ingress the Simwood network. e.g. calls arriving in London, will route to your own local proxy.
This will be particularly useful to customers with direct connections to Simwood, or hosting their own equipment on- net.

**NB if a call originates from any zone which matches an endpoint with a specific zone set, then any other endpoints within that group will be disregarded.
If the call originates from a zone which does not match a specific endpoint, any endpoint without a zone parameter will be used.
There must always be one endpoint at the same level with no zone specified.**| |**reg**|*user*|SIP registration user (e.g. 9xxxxx-USERNAME)| ||*sdes*|One of **optional** or **required**. Defaults to **optional**, we will offer SDES encryption for the audio on inbound calls to registered endpoints. If set to required, the call will not complete without successful negotiation of SDES.| -||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform:

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| -|||**NB** if the user is not registered at the time the call is received this will be skipped entirely, we advise you use another destination (or ‘busy') in addition to a **reg** endpoint.| +||*opus*|One of **never, always,** or **only**. Override the default handling of Opus offers in INVITEs to your platform;

**never** will suppress the Opus codec from the SDP, which may be useful for UDP destinations to prevent long INVITEs becoming fragmented as Opus does typically increase the SDP payload by around 220 bytes.
**always** will always offer the Opus codec, together with the usual codec offering of G.722 and G.711, in the SDP.
**only** will offer the Opus codec only, excluding all other codecs. This is ideal if your platform uses Opus and you can support Opus for all calls, and still keeps the SDP to a size that is unlikely to result in fragmentation| +|||**NB** if the user is not registered at the time the call is received this will be skipped entirely, we advise you use another destination (or ‘busy’) in addition to a **reg** endpoint.| |**pstn**|*number*|Destination number in e164 format (e.g. 447700900123)
**NB the pstn divert function is intended for voice calls only.**| ||*maxcpm*|Maximum cost per minute (in your billing currency) of the B leg of the call, intended for use with NTS services to limit exposure to expensive destinations or to ensure that the destination number cost is covered by the revenue share from the inbound leg. (e.g. 0.05)| -||*maxcpc*|To be used in conjunction with the above, sets a maximum call cost (e.g. connection cost)
**NB does not limit call duration to a cost ‘limit'**| +||*maxcpc*|To be used in conjunction with the above, sets a maximum call cost (e.g. connection cost)
**NB does not limit call duration to a cost ‘limit’**| ||*cli*|CLI to present when forwarding the call, if not specified will present the callers CLI where it is available.| ||trunk|The trunk to be associated (for billing and CDR purposes) with the outbound (B-leg) (e.g. 9xxxxx-TRUNKNAME)| |**fax**|*method*|One of **http** or **mail**| @@ -2335,7 +2161,7 @@ Depending on the type of endpoint selected above there are some additional endpo |**busy**|no parameters available| -**NB** The ‘pstn' endpoint is intended for **voice calls only**. +**NB** The ‘pstn’ endpoint is intended for **voice calls only**. We cannot guarantee successful transmission of fax or data calls forwarded to the PSTN using this functionality. #### Number Configuration Worked Examples @@ -2353,18 +2179,10 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th "routing": { "default": [ [ - { - "type": "sip", - "endpoint": "user@host.com", - "timeout": 20 - } - ],[ - { - "type": "pstn", - "number": "447700900123", - "cli": "442921202120", - "maxcpm": 0.02 - } + { "type": "sip","endpoint": "user@host.com","timeout": 20 } + ], + [ + { "type": "pstn","number": "447700900123","cli": "442921202120","maxcpm": 0.02} ] ] } @@ -2388,16 +2206,14 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th ```json { - "routing": { - "default": [ - [ - { - "type": "pstn", - "number": "447700900123" - } - ] - ] - } + "routing": { + "default": [ + [ + { + "type": "pstn", + "number": "447700900123" +} ] +] } } ``` @@ -2416,16 +2232,14 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th ```json { - "routing": { - "default": [ - [ - { - "type": "sip", - "endpoint": "%did@sip.mycompany.com" - } - ] - ] - } + "routing": { + "default": [ + [ + { + "type": "sip", + "endpoint": "%did@sip.mycompany.com" +} ] +] } } ``` @@ -2433,7 +2247,7 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th - The above might seem complicated but corresponds to the following simple PHP example, which illustrates the underlying structure: + The above might seem complicated but corresponds to the following simple PHP example, which illustrates the underlying structure; @@ -2446,13 +2260,13 @@ We cannot guarantee successful transmission of fax or data calls forwarded to th 'sip', 'endpoint' => ‘%did@sip.mycompany.com'): -// Add it to the ‘default' routing block -$arrayRouting['default'][] = Array($arrayRouteDefinition): +$arrayRouteDefinition = Array('type' => 'sip', 'endpoint' => ‘%did@sip.mycompany.com’); +// Add it to the ‘default’ routing block +$arrayRouting['default'][] = Array($arrayRouteDefinition); // Add the routing configuration to the config -$arrayConfig['routing'] = $arrayRouting: +$arrayConfig['routing'] = $arrayRouting; // encodedConfig now contains the JSON encoded routing -$encodedConfig = json_encode($arrayConfig): +$encodedConfig = json_encode($arrayConfig); ``` @@ -2462,14 +2276,14 @@ $encodedConfig = json_encode($arrayConfig): Another advantage of this method is that you can retrieve the configuration as a JSON object via your favourite programming language, edit the required entry in place and PUT the changed configuration back. #### Number Configuration - Success -Changes should take effect immediately, and the following simple JSON object will be returned: +Changes should take effect immediately, and the following simple JSON object will be returned; |||| |:-|:-|-| |success | true |Will always be true when the routing has been successfully updated.| #### Number Configuration - Errors -In the event of a configuration error a simple JSON object will be returned as follows: +In the event of a configuration error a simple JSON object will be returned as follows; |||| |:-|:-|-| @@ -2482,20 +2296,20 @@ In the event of a configuration error a simple JSON object will be returned as f | | | |:--|:-| -|Setting **‘OPTION'** must be **X, Y or Z**|An option in the "options" section has an invalid value, please select from one of the provided values | -|Invalid parameter **‘OPTION'** in settings |A parameter in the "options" section is unrecognised. please remove this parameter| -|Rule name **‘NAME'** is invalid.|Rule names must contain the characters shown only| +|Setting **‘OPTION’** must be **X, Y or Z**|An option in the "options" section has an invalid value, please select from one of the provided values | +|Invalid parameter **‘OPTION’** in settings |A parameter in the "options" section is unrecognised. please remove this parameter| +|Rule name **‘NAME’** is invalid.|Rule names must contain the characters shown only| |[Rule|Routing Block] must be an array.|Rules and routing blocks must be arrays, even if they contain only one item.| -|Rule **‘NAME'** entry **X** parameter **‘PARAM'** is invalid.|The value provided for the parameter in the rule shown is invalid.| -|Routing block **'NAME'** does not match any specified rules (or default) | A routing block has been specified that doesn't correspond to any time-dependant rules (or "default") - therefore would never be called. Check your rule names match.| -|Unknown section **‘NAME'** in configuration.|There is a section that is unrecognised, if you wish to store your own information in a number configuration you may do so but this must be within the ‘meta' section (which can contain anything)| +|Rule **‘NAME’** entry **X** parameter **‘PARAM’** is invalid.|The value provided for the parameter in the rule shown is invalid.| +|Routing block **'NAME'** does not match any specified rules (or default) | A routing block has been specified that doesn’t correspond to any time-dependant rules (or "default") - therefore would never be called. Check your rule names match.| +|Unknown section **‘NAME’** in configuration.|There is a section that is unrecognised, if you wish to store your own information in a number configuration you may do so but this must be within the ‘meta’ section (which can contain anything)| ### Inbound Trunk Association Inbound numbers can be associated with a trunk either for billing reconciliation purposes only, or to take advantage of some of the trunk-specific controls and/or routing configuration for inbound traffic. If a number- level configuration exists then this will take priority over any trunk-level configuration, which in turn, will take priority over the default account-level configuration. -**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg' routing block in either the Number or Trunk Configuration as shown above. +**NB** This does NOT result in the number being routed to a registration-based SIP trunk. You would need to use the appropriate ‘reg’ routing block in either the Number or Trunk Configuration as shown above. `/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/trunk` @@ -2515,8 +2329,9 @@ Get the trunk currently associated with this number { "success": true, "data": { - "trunk": "930XXX-ACMEPRODUCTS" + "trunk": "930XXX-ACMEPRODUCTS" } + } ``` @@ -2542,13 +2357,12 @@ Get the trunk currently associated with this number JSON response ```json - -{ - "success": true, - "data": { - "trunk": "930XXX-ACMEPRODUCTS" - } -} + +{ + "success": true, + "data": { + "trunk": "930XXX-ACMEPRODUCTS" +} } ``` @@ -2581,11 +2395,11 @@ Request current inbound SMS configuration for the provided number ```json { - "success": true, - "data": { - "mode": "http", - "endpoint": "http://api.yourdomain.com/path/to/mtsms.cgi" - } + "success": true, + "data": { + "mode": "http", + "endpoint": "http://api.yourdomain.com/path/to/mtsms.cgi" + } } ``` @@ -2625,7 +2439,7 @@ a legacy configuration and does not support modern TLS endpoints or Unicode mess endpoint @@ -2656,7 +2470,7 @@ SMS sent to this number.
```json { - "success": true + "success": true } ``` @@ -2749,7 +2563,7 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) - + @@ -2758,10 +2572,10 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **Remember this information is to assist the Emergency Service response and you have a legal obligation to ensure this information is provided fully and accurately to the best of your ability.** -The name and address information should be sufficient to identify the premises or individual promptly in an emergency. This is more important than it matching the ‘official' record: for a business entry include only the business details, do NOT specify your contact there or primary account holder etc as an individual. +The name and address information should be sufficient to identify the premises or individual promptly in an emergency. This is more important than it matching the ‘official’ record; for a business entry include only the business details, do NOT specify your contact there or primary account holder etc as an individual. **Note 1 : Business Names** -Business names should be chosen that best allow the Emergency Services to identify and locate the business - typically this is the ‘name over the door' rather than that of a parent or holding company irrespective of who you address the bill to. +Business names should be chosen that best allow the Emergency Services to identify and locate the business - typically this is the ‘name over the door’ rather than that of a parent or holding company irrespective of who you address the bill to. **Note 2 - Business Suffix** Addition to business name (e.g. Ltd or Plc) this can also be used to include a brief description that identifies the function of the business - e.g. "Hospital", "Hotel", "Fuel Storage Depot" provides valuable extra information to the Emergency Services @@ -2791,31 +2605,29 @@ be obtained from a GET request to /v3/numbers/{ACCOUNT}/validate/44330 { "success": true, "data": { - "valid": true, - "country_code": "44", - "iso": "gb", - "national_number": "3301229999", - "type": "uan", - "carrier": "Simwood", - "timezones": [ - "Europe\/Guernsey", - "Europe\/Isle_of_Man", - "Europe\/Jersey", - "Europe\/London" - ], - "formatted": { - "e164": "+443301229999", - "national": "0330 122 9999", - "international": "+44 330 122 9999" - }, - "ofcom": { + "valid": true, + "country_code": "44", + "iso": "gb", + "national_number": "3301229999", + "type": "uan", + "carrier": "Simwood", + "timezones": [ + "Europe\/Guernsey", + "Europe\/Isle_of_Man", + "Europe\/Jersey", + "Europe\/London" + ], + "formatted": { + "e164": "+443301229999", + "national": "0330 122 9999", + "international": "+44 330 122 9999" + }, "ofcom": { "status": "allocated", "use": "national non-geographic", "rh": "Simwood eSMS Limited", "date": "2010-07-20", "valid_cli": true - } - } +} } } ``` @@ -2844,14 +2656,13 @@ Lookup information on the number provided (number should in e.164 format) ```json { - "success": true, - "formatted": "+44(0)330 1223000", - "data": { - "code": "3301", - "prefix": "330122", - "rh": "Simwood eSMS Limited" - } -} + "success": true, + "formatted": "+44(0)330 1223000", + "data": { + "code": "3301", + "prefix": "330122", + "rh": "Simwood eSMS Limited" +} } ``` @@ -3001,7 +2812,7 @@ Each port will be one of the following types, if unsure please contact the LCP b The above is provided for guidance only, the Number Portability Guide should be consulted to determine lead times for porting requests. #### Number Object -The ‘numbers' array in the above should be an array of objects each with the following structure. These must include all numbers, including the MBN (even though it is specified separately) +The ‘numbers’ array in the above should be an array of objects each with the following structure. These must include all numbers, including the MBN (even though it is specified separately) |Parameter|Values|| |:-|-|-| @@ -3010,7 +2821,7 @@ The ‘numbers' array in the above should be an array of objects each with the f ||associated| Associated Number (e.g. another DDI on an ISDN circuit)| ||other |Other Number at the same address (but not associated)| |**action**| port| Port this number to Simwood| -||retain |Retain service on this number as-is (only for ‘other' type)| +||retain |Retain service on this number as-is (only for ‘other’ type)| || drop| Drop this number and cease service on the porting date| **Customer Object** @@ -3076,7 +2887,7 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) - +
-Only where mode is ‘http' or 'http_json' +Only where mode is ‘http’ or 'http_json' An HTTP(S) URL that will receive a POST request for each SMS sent to this number.
NB only the http_json method supports TLS endpoints. @@ -2643,8 +2457,8 @@ SMS sent to this number.
```json { - "mode": "http_json", - "endpoint": "https://secure.api.yourdomain.com/path/to/mt" + "mode": "http_json", + "endpoint": "https://secure.api.yourdomain.com/path/to/mt" } ```
postcode 12Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail's
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML		Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail’s
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML
postcode 12Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail's
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML		Mandatory for Individual and Business End Users
The full current postcode as recognised by Royal Mail’s
PAF database. This must be in the form Out-code space In
code e.g. LS11 5DF, S9 5AD, S60 3ML
@@ -3086,57 +2897,61 @@ or Name (e.g. 104, The Lighthouse, Thatched Cottage) **JSON of example porting request** ```json { - "mbn": "01632960100", - "contact_email": "simwood.customer@example.com", - "lcp": "BT", - "lcp_cupid": "001", - "account_number": "NA1234B32", - "billing_postcode": "A12 3BC", - "type": "multi", - "lines": 1, - "channels": 30, - "customer": { - "title": "Mr", - "forename": "John", - "name": "Doe", - "loa_initial": "J", - "loa_surname": "Doe", - "premises": "123", - "thoroughfare": "Some Street", - "locality": "Sometown", - "postcode": "A12 3BC" - }, - "numbers": [ - {"number": "01632960100", "type": "mbn", "action": "port"}, - {"number": "01632960101", "type": "associated", "action": "port"}, - {"number": "01632960102", "type": "associated", "action": "port"}, - {"number": "01632960103", "type": "associated", "action": "port"}, - {"number": "01632960104", "type": "associated", "action": "port"}, - {"number": "01632960105", "type": "associated", "action": "port"}, - {"number": "01632960106", "type": "associated", "action": "port"}, - {"number": "01632960290", "type": "other", "action": "retain"} - ] + + + "mbn": "01632960100", + "contact_email": "simwood.customer@example.com", + "lcp": "BT", + "lcp_cupid": "001", + "account_number": "NA1234B32", + "billing_postcode": "A12 3BC", + "type": "multi", + "lines": 1, + "channels": 30, + "customer": { + "title": "Mr", + "forename": "John", + "name": "Doe", + "loa_initial": "J", + "loa_surname": "Doe", + "premises": "123", + "thoroughfare": "Some Street", + "locality": "Sometown", + "postcode": "A12 3BC" + }, + "numbers": [ + {"number": "01632960100", "type": "mbn", "action": "port"}, + {"number": "01632960101", "type": "associated", "action": "port"}, + {"number": "01632960102", "type": "associated", "action": "port"}, + {"number": "01632960103", "type": "associated", "action": "port"}, + {"number": "01632960104", "type": "associated", "action": "port"}, + {"number": "01632960105", "type": "associated", "action": "port"}, + {"number": "01632960106", "type": "associated", "action": "port"}, + {"number": "01632960290", "type": "other", "action": "retain"} + + ] + } ``` **Response** -The response will be a JSON similar to the following: +The response will be a JSON similar to the following; ```json -{ - "success": true, - "ref": 12345, - "url": "/v3/porting/{ACCOUNT}/ports/12345" + { + "success": true, + "ref": 12345, + "url": "/v3/porting/{ACCOUNT}/ports/12345" } ``` The *"ref"* value corresponds to the ticket that will be used to track the progress of the porting request. -If any error(s) occurred whilst validating the configuration these will be returned as follows: +If any error(s) occurred whilst validating the configuration these will be returned as follows; ```json -{ - "success": false, - "errors": [ "Message #1", "Message #2" ] + { + "success": false, + "errors": [ "Message #1", "Message #2" ] } ``` @@ -3162,20 +2977,17 @@ Get a list of currently outstanding, or recently completed (within the last 90 d ```json { - "success": true, - "data": [ - { - "ref": "54721", - "mbn": "01632960100", - "date": "2015-02-29", - "crd": "2015-03-14", - "status_code": "submitted_rh", - "status": "Submitted to RH" - },{ - ... - } - ] -} + "success": true, +"data": [ { + "ref": "54721" + "mbn": "01632960100", + "date": "2015-02-29", + "crd": "2015-03-14", + "status_code": "submitted_rh" + "status": "Submitted to RH" +}, { +... } +] } ``` @@ -3200,36 +3012,37 @@ The events element contains a chronological history of the port. { "success": true, "data": { - "mbn": "01632960100", - "status": "Porting Request Received", - "status_code": "rcvd", - "contact_email": "your.name@example.com", - "lcp": "BT", - "rh": "BT", - "account_number": "NA1234B32", - "billing_postcode": "A12 3BC", - "type": "multi", - "lines": "1", - "channels": "1", - "customer": { ... }, - "numbers": [ ... ], - "events": [ - { - "date": "2015-02-29 13:33:51", - "status_code": "submitted_lcp", - "status": "Submitted to LCP", - },{ - "date": "2015-02-29 14:23:51", - "status_code": "accepted", - "status": "Porting Request Accepted", - },{ - "date": "2015-02-29 13:33:51", - "status_code": "rcvd", - "status": "Porting Request Received", - "info": "Order Submitted by API" - } - ] - } + "mbn": "01632960100", + "status": "Porting Request Received", + "status_code": "rcvd", + "contact_email": "your.name@example.com", + "lcp": "BT", + "rh": "BT", + "account_number": "NA1234B32", + "billing_postcode": "A12 3BC", + "type": "multi", + "lines": "1", + "channels": "1", + "customer": { ... }, + "numbers": [ ... ], + "events": [ + { + "date": "2015-02-29 13:33:51", + "status_code": "submitted_lcp", + "status": "Submitted to LCP", + }, { + "date": "2015-02-29 14:23:51", + "status_code": "accepted", + "status": "Porting Request Accepted", + }, + { + "date": "2015-02-29 13:33:51", + "status_code": "rcvd", + "status": "Porting Request Received", + "info": "Order Submitted by API" + } + ] + } } @@ -3256,19 +3069,21 @@ Get list of LCP (Losing Communications Providers) we can port from and the corre ```json { - "success": true, - "cps": [ - { - "cpName": "BT", - "cupid": "1" - },{ + "success": true, + "cps": [ + { + "cpName": "BT", + "cupid": "1" + }, + { "cpName": "Telephony Services", "cupid": "93" - },{ + }, + { "cpName": "Gamma Telecom", "cupid": "31" - } - ] +} ] + } ``` @@ -3315,14 +3130,13 @@ Submit a new Mobile Number port. ```json { - "success": true, - "data": { - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_port": "2016-12-16", - "ref": 43001 - } -} + "success": true, + "data": { + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_port": "2016-12-16", + "ref": 43001 +} } ``` @@ -3350,20 +3164,21 @@ Get a list of currently outstanding, or recently completed mobile number ports ```json { - "success": true, - "data": [ - { - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_added": "2016-12-06", - "date_updated": "2016-12-06", - "date_port": "2016-12-08", - "status_code": "pending" - "status": "Pending" - "ref": 43001 - },{ - ... - } + "success": true, + "data": [ + { + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_added": "2016-12-06", + "date_updated": "2016-12-06", + "date_port": "2016-12-08", + "status_code": "pending" + "status": "Pending" + "ref": 43001 + }, + { + ... + } ] } ``` @@ -3386,16 +3201,17 @@ Get details of an MNP porting request ```json { "success": true, - "data": { - "pac": "ABC1234567", - "msisdn": "447700900123", - "date_added": "2016-12-06", - "date_updated": "2016-12-06", - "date_port": "2016-12-08", - "status_code": "pending", - "status": "Pending", - "ref": 43001 - } +"data": { + + "pac": "ABC1234567", + "msisdn": "447700900123", + "date_added": "2016-12-06", + "date_updated": "2016-12-06", + "date_port": "2016-12-08", + "status_code": "pending" + "status": "Pending" + "ref": 43001 + } } ``` @@ -3426,17 +3242,16 @@ Lists las secen days of inbound faxes (optionally filtered by NUMBER) { "success": true, "data": [ - { - "hash": "7e2bb7bb87300ff83c657b04b07b8261", - "time": "2015-02-30 12:34:56", - "originator": "07700900123", - "destination": "443301223000", - "station": "MYFAX", - "duration": 31, - "pages": 1, - "url": "/v3/..../7e2bb7bb87300ff83c657b04b07b8261.pdf" - } - ] + { + "hash": "7e2bb7bb87300ff83c657b04b07b8261" + "time": "2015-02-30 12;34:56", + "originator": "07700900123", + "destination": "443301223000", + "station": "MYFAX", + "duration": 31, + "pages": 1, + "url": "/v3/..../7e2bb7bb87300ff83c657b04b07b8261.pdf" +} ] } ``` @@ -3485,8 +3300,8 @@ Send an SMS Message flash
[optional] -Defaults to 0. If set to 1 message is sent as a ‘flash' message -(i.e. it will be displayed on the phone screen but not stored in the recipient's inbox, subject to handset and network support) +Defaults to 0. If set to 1 message is sent as a ‘flash’ message +(i.e. it will be displayed on the phone screen but not stored in the recipient’s inbox, subject to handset and network support) replace
[optional] @@ -3501,7 +3316,7 @@ of 1 will truncate your message if it is longer than 160 characters unless you s report
[optional] -URL for delivery report. The following placeholders can be used: +URL for delivery report. The following placeholders can be used; %id% @@ -3526,8 +3341,8 @@ URL for delivery report. The following placeholders can be used: -If successful the message will be queued immediately and an id returned as follows: -If the extended parameter is included, additional information will be included in the response e.g: +If successful the message will be queued immediately and an id returned as follows; +If the extended parameter is included, additional information will be included in the response e.g; ``` @@ -3536,14 +3351,14 @@ If the extended parameter is included, additional information will be included i ```json { - "success":true, - "data": { - "id":"1f40b0ac384cab838acf39a0e3e38bba", - "desc":"SMS - United Kingdom", - "parts":1, - "charge":0.02, - "currency":"GBP" - } + "success":true, + "data":{ + "id":"1f40b0ac384cab838acf39a0e3e38bba", + "desc":"SMS - United Kingdom", + "parts":1, + "charge":0.02, + "currency":"GBP" + } } ``` @@ -3593,7 +3408,7 @@ Despite the inclusion of [] in the name, this parameter cannot be repeated multi report
[optional] URL for delivery report. -The following placeholders can be used: +The following placeholders can be used; %id% Message ID @@ -3612,13 +3427,11 @@ The following placeholders can be used: If submission is successful, the fax will be queued immediately and response returned as an array containing -the number and corresponding id of the submitted fax for each destination number: +the number and corresponding id of the submitted fax for each destination number; -```json -[ - {"number":"441632000123","id":"b902e8e46b91900af276f52995a3082e"}, - {"number":"447700900123","id":"71cea3179fdd13271a2ac14a366941f8"} -] +``` +[{"number":"441632000123","id":"b902e8e46b91900af276f52995a3082e"}, +{"number":"447700900123","id":"71cea3179fdd13271a2ac14a366941f8"}] ``` #### Fax Content Types @@ -3647,13 +3460,13 @@ There are now a number of event-driven webhooks available which provide realtime For more information see https://cdn.simwood.com/docs/simwood_webhooks_beta.pdf ### Received Fax -When a fax is received on a number configured to relay them by HTTP POST you will receive an HTTP POST message with a single parameter payload containing a JSON-encoded representation of the following: +When a fax is received on a number configured to relay them by HTTP POST you will receive an HTTP POST message with a single parameter payload containing a JSON-encoded representation of the following; - @@ -3729,7 +3542,7 @@ You must request the PDF from the URL provided within 5 minutes from successful ### Received Fax (Beta) When a fax is received on a number configured to relay them by the **http_json** method you will receive an -HTTP POST message of Content-type **application/json** with the following JSON body: +HTTP POST message of Content-type **application/json** with the following JSON body; Your endpoint can support (or require) TLSv1.1, TLSv1.2. Please note that SSLv3 and TLSv1 are not supported by this service. @@ -3739,7 +3552,7 @@ Please note that SSLv3 and TLSv1 are not supported by this service. - @@ -3813,7 +3626,7 @@ You must request the PDF from the URL provided within 5 minutes from successful ### Received SMS (http) - Deprecated -When an SMS is received on a number configured to relay them by using the legacy **http** method you will receive an HTTP sPOST message of Content-type **application/x-www-form-urlencoded** with a single parameter payload containing a JSON-encoded representation of the following: +When an SMS is received on a number configured to relay them by using the legacy **http** method you will receive an HTTP sPOST message of Content-type **application/x-www-form-urlencoded** with a single parameter payload containing a JSON-encoded representation of the following; **Please note your endpoint cannot require TLSv1.1 or higher. The legacy SMS service supports SSLv3 and TLSv1 only (or plain http) for TLS support please use the service described below (with type http_json)** @@ -3822,7 +3635,7 @@ When an SMS is received on a number configured to relay them by using the legacy - @@ -3870,11 +3683,198 @@ For your security we do not retain message content after relay to your own platf ### Received SMS (http_json) When an SMS is received on a number configured to relay them by using the **http_json** method you will -receive an HTTP POST message of Content-type **application/json** with the following JSON body:
+receive an HTTP POST message of Content-type **application/json** with the following JSON body;
Your endpoint can support (or require) TLSv1.1, TLSv1.2.
Please note that SSLv3 and TLSv1 are not supported by this service. +
Description
app‘fax_inbound' in this case. +‘fax_inbound’ in this case. This is to facilitate re-use of the same status receiver your side for multiple applications.
Description
app‘fax_inbound' in this case.
+		‘fax_inbound’ in this case.
NB This field exists to facilitate re-use of the same status receiver your side for multiple applications. However as this is a beta this is subject to change and it is strongly recommended to use a dedicated URL to receive HTTP requests.
Description
app‘mvno_inbound_sms' in this case.
+		‘mvno_inbound_sms’ in this case.
This is to facilitate re-use of the same status receiver your side for multiple applications.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Description
app‘sms_inbound’ in this case.
+NB This field exists to facilitate re-use of the same URL for multiple applications. However we strongly recommended to use a dedicated URL where possible. +
idA unique ID representing this request e.g. fi_422296075c882529362765a39aa75b19
dataAn object containing the following parameters: + + +
timeTimestamp of message (in form YYYY-MM-DD HH:mm:ss) Where available from the originating network.
originatorThe MSISDN or Originator of the SMS message
destinationThe destination number (i.e. the Simwood number that received the SMS)
messageThe content of the SMS message +
lengthTThe length (characters) of the SMS message.
+ +An example full message is shown below +```json +{ +"app": "sms_inbound", +"id": "si_422296075c882529362765a39aa75b19", +"data": { + "originator": "447700900321", + "destination": "447700900123", + "length": 12, + "message": "Hello World." +} +} +``` + +**For your security we do not retain message content after relay to your own platform** + + +### Outbound Fax Reports +Where a report field was specified for an outgoing fax, we will make a POST to the URL specified. If present, ‘%id%’ in your URL will be replaced by the message ID returned in the response below and ‘%status%’ will be replaced with the status code.

+Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Description
app‘fax_inbound’ in this case.
+This is to facilitate re-use of the same status receiver your side for multiple applications.
idThe unique id for the fax returned when it was submitted. +
dataAn object containing the following parameters: + +
dtimeThe date/time the status was generated.
statusA numeric indication of status. There will typically be three.
+ 1 Queued: The fax has been queued to the fax server. +For scheduled faxes this will happen at the specified time.
+5 Processing: We have begun conversion and transmission of fax
+10 OK: Fax transmission completed successfully + >10 Fax transmission may not have completed successfully, please +see the status_msg and supplementary fields for more details. +
status_msgA human readable status +
stationIf present, the CSID of the remote fax machine.
durationTThe billable time (in seconds) spent on your fax. Note, as we employ an intelligent retry system this may be the sum of several transmissions.
errorsThe number of transmission errors.
url +The number of retries required. +
+ +### Outbound SMS Delivery Reports (DLRs) +Where a report field was specified for an outgoing SMS, we will make a POST to the URL specified. If present, ‘%id%’ in your URL will be replaced by the message ID returned in the response below and ‘%status%’ will be replaced with the status code. + +Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
app‘sms_send_status’ in this case. This is to facilitate re-use of the same status receiver your side for multiple applications. +
idThe unique id for the SMS returned when it was submitted.
dataAn object containing the following parameters: + + +
dtimeThe date/time the status was generated. Note, this is the time the status was generated or received by Simwood. For example, in the case of a delivery report it will not the time of actual delivery but the time we learned of delivery.
status +A numeric indication of status. There will typically be three for SMS. +

1 Received: This will be raised immediately the SMS is committed to a queue at Simwood. Generally this will be simultaneous with your message submission but messages will be queued between the API and Simwood systems for performance. +

2 Submitted: The SMS has left Simwood. Again, this will generally coincide with your submission and status 1 above but queueing at every stage affords scalability and performance enhancement. +

11 Delivered: Confirmation received from the handset of delivery. Generally this will be 4 seconds or so after the above for a handset in signal. +

12 Rejected: Message was rejected, has not been delivered and will not be retried. +

13 Error: There was a syntax error with the message, usually relating to invalid destination address but in some cases disallowed source address. +

14 Queued: Message has been buffered for delivery in transit. This usually indicates the phone is off or out of service coverage. +

18 SMSCa: Message has been accepted by the SMSC. For networks where delivery reports are unavailable, this is the closest status to a delivery receipt. +

26 SMSCr: Message was rejected by the SMSC and will not be retried. + +
+ + +## Change Log / Document History + + +Please note that SSLv3 and TLSv1 are not supported by this service. + From 3fb8448f9ebb2e58d6bddccf89d3730f9e755488 Mon Sep 17 00:00:00 2001 From: Alex Lane Date: Tue, 10 Oct 2023 15:10:19 +0100 Subject: [PATCH 15/15] Revert again --- docs/wholesale/api/v3.md | 187 --------------------------------------- 1 file changed, 187 deletions(-) diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 14b573d..08d7acf 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -3873,190 +3873,3 @@ A numeric indication of status. There will typically be three for SMS. ## Change Log / Document History -Please note that SSLv3 and TLSv1 are not supported by this service. - -
Description
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Description
app‘sms_inbound' in this case.
-NB This field exists to facilitate re-use of the same URL for multiple applications. However we strongly recommended to use a dedicated URL where possible. -
idA unique ID representing this request e.g. fi_422296075c882529362765a39aa75b19
dataAn object containing the following parameters: - - -
timeTimestamp of message (in form YYYY-MM-DD HH:mm:ss) Where available from the originating network.
originatorThe MSISDN or Originator of the SMS message
destinationThe destination number (i.e. the Simwood number that received the SMS)
messageThe content of the SMS message -
lengthTThe length (characters) of the SMS message.
- -An example full message is shown below -```json -{ - "app": "sms_inbound", - "id": "si_422296075c882529362765a39aa75b19", - "data": { - "originator": "447700900321", - "destination": "447700900123", - "length": 12, - "message": "Hello World." - } -} -``` - -**For your security we do not retain message content after relay to your own platform** - - -### Outbound Fax Reports -Where a report field was specified for an outgoing fax, we will make a POST to the URL specified. If present, ‘%id%' in your URL will be replaced by the message ID returned in the response below and ‘%status%' will be replaced with the status code.

-Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Description
app‘fax_inbound' in this case.
-This is to facilitate re-use of the same status receiver your side for multiple applications.
idThe unique id for the fax returned when it was submitted. -
dataAn object containing the following parameters: - -
dtimeThe date/time the status was generated.
statusA numeric indication of status. There will typically be three.
- 1 Queued: The fax has been queued to the fax server. -For scheduled faxes this will happen at the specified time.
-5 Processing: We have begun conversion and transmission of fax
-10 OK: Fax transmission completed successfully - >10 Fax transmission may not have completed successfully, please -see the status_msg and supplementary fields for more details. -
status_msgA human readable status -
stationIf present, the CSID of the remote fax machine.
durationTThe billable time (in seconds) spent on your fax. Note, as we employ an intelligent retry system this may be the sum of several transmissions.
errorsThe number of transmission errors.
url -The number of retries required. -
- -### Outbound SMS Delivery Reports (DLRs) -Where a report field was specified for an outgoing SMS, we will make a POST to the URL specified. If present, ‘%id%' in your URL will be replaced by the message ID returned in the response below and ‘%status%' will be replaced with the status code. - -Additionally the POSTed data will contain a single parameter called payload, the value of which will be a JSON encoded representation of the following. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
app‘sms_send_status' in this case. This is to facilitate re-use of the same status receiver your side for multiple applications. -
idThe unique id for the SMS returned when it was submitted.
dataAn object containing the following parameters: - - -
dtimeThe date/time the status was generated. Note, this is the time the status was generated or received by Simwood. For example, in the case of a delivery report it will not the time of actual delivery but the time we learned of delivery.
status -A numeric indication of status. There will typically be three for SMS. -

1 Received: This will be raised immediately the SMS is committed to a queue at Simwood. Generally this will be simultaneous with your message submission but messages will be queued between the API and Simwood systems for performance. -

2 Submitted: The SMS has left Simwood. Again, this will generally coincide with your submission and status 1 above but queueing at every stage affords scalability and performance enhancement. -

11 Delivered: Confirmation received from the handset of delivery. Generally this will be 4 seconds or so after the above for a handset in signal. -

12 Rejected: Message was rejected, has not been delivered and will not be retried. -

13 Error: There was a syntax error with the message, usually relating to invalid destination address but in some cases disallowed source address. -

14 Queued: Message has been buffered for delivery in transit. This usually indicates the phone is off or out of service coverage. -

18 SMSCa: Message has been accepted by the SMSC. For networks where delivery reports are unavailable, this is the closest status to a delivery receipt. -

26 SMSCr: Message was rejected by the SMSC and will not be retried. - -
- - -## Change Log / Document History - -