diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index ade69f5..edb0bfe 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 @@ -38,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 @@ -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 @@ -254,45 +263,52 @@ 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 | 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", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25", - "created" : "2014-03-10T13:37:00.000+0000", - "company": "Bloggs co", + "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": "Bloggs", + "lastName": "Test", "telephone": "07557000000", - "email": "contact@fredbloggs.com", - "address1": "60 Cleveland St", - "address2": "Fitzrovia", - "city": "London", - "postcode": "W1T 4JZ", - "country": "GB", - "properties": { - "testid" : "abc123", - "test2" : "GB134324" - }, + "email": "support@sipcentric.com", + "address1": "The Oaks", + "address2": "Ribbesford", + "city": "Bewdley", + "postcode": "98999", + "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 +316,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 +331,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 @@ -323,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 { @@ -338,24 +365,50 @@ 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": "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": { + "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 + } +] } ``` - + + #### Get customer @@ -363,44 +416,145 @@ 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 { - "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. + + + + + +```bash +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 +} +``` + + + + +```bash +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 } + ``` + + + ### Phone Book @@ -417,26 +571,34 @@ 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 -} +```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 + } ``` | 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 @@ -445,39 +607,53 @@ 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 { - "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" } ``` - + + #### Read phone book entry @@ -485,26 +661,37 @@ 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 { - "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 } ``` - + + #### Create phone book entry @@ -512,32 +699,40 @@ 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 { "type" : "phonebookentry", "name" : "Fred Mobile", "phoneNumber" : "07902000000", - "speedDial" : 4 + "priority" : 0 } ``` -```response + + + +```bash 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 } ``` - + + #### Update phone book entry @@ -545,9 +740,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 { @@ -558,7 +756,11 @@ PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 } ``` -```response + + + +```bash + HTTP/1.1 200 OK { @@ -569,8 +771,10 @@ HTTP/1.1 200 OK "phoneNumber": "07825000000", "speedDial": 12 } -``` +``` + + #### Delete phone book entry @@ -578,13 +782,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 @@ -601,34 +813,39 @@ 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", - "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 @@ -636,42 +853,59 @@ 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 -HTTP/1.1 200 OK + + +```bash +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" } ``` + + #### Get SMS Message @@ -679,34 +913,49 @@ 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 { - "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 } ``` - + + #### Send SMS `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. + + + + +```bash POST https://pbx.sipcentric.com/api/v1/customers/25/sms { @@ -717,20 +966,28 @@ POST https://pbx.sipcentric.com/api/v1/customers/25/sms } ``` -```response + + + +```bash 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 } ``` + + ### Calls @@ -753,43 +1010,53 @@ The scope of a call can be: - External - to/from an external number on the PSTN. -``` -{ - "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" - } -} +```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" + }, + } ``` | 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 @@ -811,11 +1078,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 { @@ -825,7 +1098,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 +1117,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", @@ -861,6 +1138,8 @@ HTTP/1.1 200 OK "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2" } ``` + + #### Originate call @@ -868,7 +1147,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 @@ -881,9 +1162,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. @@ -894,13 +1180,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", @@ -909,13 +1200,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 @@ -925,9 +1220,14 @@ PUT https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus "dndActive": true } ``` -```response + + + +```bash HTTP/1.1 200 OK ``` + + ### Sounds @@ -962,6 +1262,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* | @@ -988,13 +1289,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 { @@ -1003,13 +1309,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 @@ -1017,6 +1327,8 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" } ``` + + #### Get sound @@ -1024,23 +1336,31 @@ 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 { "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 } ``` + + It is also possible to fetch a copy of the audio file itself, by including the `Accept` header: @@ -1063,10 +1383,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. -```exampleRepresentation +```bash 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", @@ -1108,13 +1430,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 { @@ -1124,7 +1451,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 +1464,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", @@ -1149,24 +1480,34 @@ 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 { "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", @@ -1177,6 +1518,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: @@ -1199,10 +1542,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. -```exampleRepresentation +```bash 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 +1579,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* | @@ -1252,13 +1599,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 { @@ -1267,7 +1619,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 +1633,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", @@ -1308,6 +1664,9 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" } ``` + + + #### Get time interval @@ -1315,19 +1674,26 @@ 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 { "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", @@ -1355,6 +1721,9 @@ HTTP/1.1 200 OK } ``` + + + ### Endpoints | Resource Information | | @@ -1363,7 +1732,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 +1813,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 +1825,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 +1846,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* | @@ -1485,13 +1860,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 { @@ -1501,7 +1881,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 +1891,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", @@ -1523,23 +1907,33 @@ 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 { "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", @@ -1554,6 +1948,202 @@ 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 +``` + + + + +```bash + +{ + "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. + + + + + +``` +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 +} + +``` + + + + +```bash +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. + + + + + + +``` +POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints + +Body +{"callRecording":"OFF","timeout":30,"name":"Fred","shortNumber":"102","type":"phone"} + +``` + + + + +```bash + +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 @@ -1563,16 +2153,18 @@ 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 | 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", "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 +2191,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* | @@ -1621,13 +2215,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 { @@ -1636,18 +2235,22 @@ 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", "smsEnabled" : true, "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@fredbloggs.com", + "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" : "", @@ -1671,6 +2274,8 @@ HTTP/1.1 200 OK "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" } ``` + + #### Get phone number @@ -1678,78 +2283,396 @@ 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 { "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", + "smsNotificationEmail" : "contact@Fredbloggs.com", "smsNotificationUrl" : "https://example.com/sms", "faxEnabled" : false } ``` + + -### 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 + + + + +``` +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* | + + +```bash +HTTP/1.1 200 OK -#### List outgoing caller ids +{ + "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 + +`PUT /customers/{customerId}/phonenumbers/{phonenumberId}` + +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. + +NB: This phone number should already be added to the account. Please see , adding Phone numbers. + + + + + +```bash +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" +} +``` + + + + +```bash +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" + } +} +``` + + + + +#### UN-Linking Phone Number and extension + + +`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. + + + + + + +```bash +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" + } + } +``` + + + + +```bash +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" + } +} +``` + + + +#### 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}/availablenumber | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | availablenumber | +| Additional Formats | None | + +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 +{ + "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* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| 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` + + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/availablenumbers?areaCode=113&country=44&pageSize=100&location=GB +``` + + + + +```bash +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}` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921 +``` + + + + +```bash +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`. + +```bash 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 + + + +```bash HTTP/1.1 200 OK { @@ -1759,7 +2682,9 @@ HTTP/1.1 200 OK "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, @@ -1767,7 +2692,9 @@ 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, @@ -1776,6 +2703,8 @@ HTTP/1.1 200 OK ] } ``` + + #### Get outgoing caller id @@ -1783,24 +2712,33 @@ 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 { "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 @@ -1816,10 +2754,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. -```exampleRepresentation +```bash 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 } @@ -1837,13 +2776,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 { @@ -1853,6 +2797,8 @@ HTTP/1.1 200 OK "balance": 19.571 } ``` + + ### Call Bundles @@ -1868,10 +2814,12 @@ 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" 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 +2837,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* | @@ -1907,13 +2857,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 { @@ -1923,7 +2878,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, @@ -1938,6 +2895,9 @@ HTTP/1.1 200 OK ] } ``` + + + #### Get call bundle @@ -1945,18 +2905,25 @@ 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 { "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, @@ -1969,80 +2936,1668 @@ HTTP/1.1 200 OK "status": "ACTIVE" } ``` + + -## Global Resources +### Call Charging -### Token Generator +| 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 | -In some situations it's not possible to use basic authentication in a GET request, such as downloading a call recording in a client's browser. +The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. -To solve this issue we have added a token generator for pre-authenticating these requests. This will return a single-use token for accessing any readonly resources -you would normally have to authenticate for. +```bash 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` + + + -#### Get token ``` -GET https://pbx.sipcentric.com/api/v1/tokengenerator +GET https://pbx.sipcentric.com/api/v1/customers/25/callcharging +``` + + + + +```bash +HTTP/1.1 200 OK { - "type": "authtoken", - "id": "318f9a6d-162e-4d46-89d2-3d7cb2f4db16", - "created": "2014-07-11T15:11:12.477+0000", - "expires": "2014-07-11T16:11:12.477+0000" + "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 } ``` + + + + +#### Updating callcharging plan for a customer + +`PUT /customers/{customerId}/callcharging` + + + -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 +PUT https://pbx.sipcentric.com/api/v1/customers/25/callcharging ``` -Anyone that tried to use the request again will get a 401 Unauthorized. This prevents replay attacks from getting any data. + + -### Stream +```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 +} ``` -GET https://pbx.sipcentric.com/api/v1/stream + + + + +### 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. + +```bash 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 +} ``` -You can create a standing HTTP connection to our API for live streaming events. This means you can process events in near real time, without having to poll other resources and potentially avoid hitting request limits. Data is returned as JSON objects. +| 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* | -Currently the following is available via the streaming API: +#### Get Customer Permissions -- Incoming call notifications -- Incoming SMS messages -- SMS delivery receipts +`GET /customers/{customerId}/permissions` -Example object: + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/permissions ``` + + + + +```bash +HTTP/1.1 200 OK + { - "event": "incomingcall", - "location": null, - "values": { - "callerIdNumber": "01234567890", - "callerIdName": "Support", - "endpoint": "/customers/325/endpoints/6874" - } + "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 } ``` + + -#### Connecting -To work with the streaming API you will need to create an indefinite HTTP GET request and process the data as it is received. Our API will hold the connection open as long as possible. But if the connection does disconnect due to network / client issues you should handle this by reconnecting as soon as possible. We also send a heartbeat object every 60 seconds which helps keep the connection open and you can also check for this object and reconnect if it isn't received within a suitable time period. +### billing -The streaming API requires you to authenticate with Basic Authentication. The stream data you receive depends on the user you authenticate with. +| 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 best way to work with the Stream in JavaScript/Node.js is to use the [Atmosphere client](https://github.com/Atmosphere/atmosphere-javascript) which establishes the connection and handles disconnects automatically. +The billing sub-resource returns the current billing configuration and pricing plan for different features, represented by a `billing` instance. -Most HTTP client libraries let you handle the connection as a stream. Which allows you to process the data as it is received. +```bash 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" + } +} +``` -#### Responses +| 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* | -All of the event objects are in a standard format: +#### Get billing +`GET /customers/{customerId}/billing` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/billing +``` + + + + +```bash +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. + + + +```bash 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/` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate +``` + + + + +```bash +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. + +```bash 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` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/limits +``` + + + + +```bash +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. + +```bash 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` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/pricing +``` + + + + +```bash +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. + + + + + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/5/pricing + +{ + "type" : "customerpricing", + "phone" : 7 +} +``` + + + + +```bash +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), [DELETE](#delete) | +| 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. + +```bash 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` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers +``` + + + + +```bash +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}` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/35180 +``` + + + + +```bash +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` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/25/linkedusers/me +``` + + + + +```bash +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" +} +``` + + + +#### 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 | | +|:-------------------------------|:-------------------------------------| +| 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. + + + +```bash 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/` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/chargingplans/ +``` + + + + +```bash +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}` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/chargingplans/8 +``` + + + + +```bash +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?` + + + + + + +``` +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 + +``` + + + + + + + + +```bash +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 + + + + +``` +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 + +``` + + + + + +```bash +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 + + + + +``` +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 +``` + + + + +```bash +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. + + + + +``` +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 + +``` + + + + +```bash +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 + } +} + +``` + + +**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. + + + + + +``` +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 + +``` + + + + +```bash +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 + } +} +``` + + + + +**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. + + +#### 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 + + + + + +``` +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 + +``` + + + + +```bash +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. + + + + + +``` +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 + +``` + + + + +```bash +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 + + + + + +``` +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 + +``` + + + + +```bash +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. + + + + + +``` +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 + +``` + + + + +```bash +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. + + + + + +``` +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 + +``` + + + + +```bash +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 + +In some situations it's not possible to use basic authentication in a GET request, such as downloading a call recording in a client's browser. + +To solve this issue we have added a token generator for pre-authenticating these requests. This will return a single-use token for accessing any readonly resources +you would normally have to authenticate for. + +#### Get token + +```bash +GET https://pbx.sipcentric.com/api/v1/tokengenerator + +{ + "type": "authtoken", + "id": "318f9a6d-162e-4d46-89d2-3d7cb2f4db16", + "created": "2014-07-11T15:11:12.477+0000", + "expires": "2014-07-11T16:11:12.477+0000" +} +``` + +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 +``` + +Anyone that tried to use the request again will get a 401 Unauthorized. This prevents replay attacks from getting any data. + +### Stream + +``` +GET https://pbx.sipcentric.com/api/v1/stream +``` + +You can create a standing HTTP connection to our API for live streaming events. This means you can process events in near real time, without having to poll other resources and potentially avoid hitting request limits. Data is returned as JSON objects. + +In order to run stream the authenticating user should be an admin in that particular account. + +example below should work +```bash + +curl -X GET -u "user:pass" --no-buffer "https://pbx.sipcentric.com/api/v1/stream" + +``` + +Currently the following is available via the streaming API: + +- Incoming call notifications +- Incoming SMS messages +- SMS delivery receipts + +Example object: + +```bash +{ + "event": "incomingcall", + "location": null, + "values": { + "callerIdNumber": "01234567890", + "callerIdName": "Support", + "endpoint": "/customers/325/endpoints/6874" + } +} ``` + + + +#### Connecting + +To work with the streaming API you will need to create an indefinite HTTP GET request and process the data as it is received. Our API will hold the connection open as long as possible. But if the connection does disconnect due to network / client issues you should handle this by reconnecting as soon as possible. We also send a heartbeat object every 60 seconds which helps keep the connection open and you can also check for this object and reconnect if it isn't received within a suitable time period. + +The streaming API requires you to authenticate with Basic Authentication. The stream data you receive depends on the user you authenticate with. + +The best way to work with the Stream in JavaScript/Node.js is to use the [Atmosphere client](https://github.com/Atmosphere/atmosphere-javascript) which establishes the connection and handles disconnects automatically. + +Most HTTP client libraries let you handle the connection as a stream. Which allows you to process the data as it is received. + +#### Responses + +All of the event objects are in a standard format: + +```bash { "event": ..., "location": ..., diff --git a/docs/wholesale/api/v3.md b/docs/wholesale/api/v3.md index 08d7acf..c1ea76a 100644 --- a/docs/wholesale/api/v3.md +++ b/docs/wholesale/api/v3.md @@ -3226,6 +3226,57 @@ At this time it is not possible to generate a PAC from the API. Please raise a t ## Fax and SMS Messaging +### LHR Request +If you want to get the LHR of a number, you can send a POST. +You can perform the LHR request easily through the API and you will get the Number's current Mobile Network Codes (MNCs) back in the response. This can help you know which Mobile Network the number is currently on. This is helpful in case the number was ported to another provider. + +`v3/messaging/{ACCOUNT}/hlr` + +`POST v3/messaging/{{ACCOUNT}}/hlr?number={Number}` + + + + + + +
POST +Returned Example + +```json +{ + "success": true, + "data": { + "detected_telephone_number": "44152733XXXX", + "original_network": "AVAILABLE", + "original_network_details": { + "name": "Simwood eSMS Limited", + "mccmnc": "234SW", + "country_name": "United Kingdom", + "country_iso3": "GBR", + "area": "Redditch", + "country_prefix": "44" + }, + "telephone_number_type": "LANDLINE", + "live_status": "NO_COVERAGE", + "current_network": "AVAILABLE", + "current_network_details": { + "name": "Simwood eSMS Limited", + "mccmnc": "234SW", + "country_name": "United Kingdom", + "country_iso3": "GBR", + "country_prefix": "44" + }, + "is_ported": "NO", + "unit_price": 0.0035, + "units": 1, + "currency": "GBP", + "charge": 0.0035 + } +} +``` + +
+ ### Inbound Fax Retrieval Faxes received on your Simwood numbers can be retrieved via the API for a period of seven days from receipt and can be queried via the API