diff --git a/docs/direct/api/v1.md b/docs/direct/api/v1.md index ade69f5..8306fde 100644 --- a/docs/direct/api/v1.md +++ b/docs/direct/api/v1.md @@ -2,6 +2,8 @@ id: v1 title: Version 1 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; ## Overview @@ -172,15 +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 -HTTP/1.1 200 OK - +```json { "totalItems": 21, "pageSize": 5, @@ -190,23 +195,19 @@ HTTP/1.1 200 OK "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2468", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/1365", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/4775", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2164", ... - }, - { + },{ "type": "did", "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/3647", ... @@ -217,6 +218,8 @@ HTTP/1.1 200 OK } ``` + + #### Query Parameters @@ -254,52 +257,59 @@ 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 - +```json { "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", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", "country": "GB", - "properties": { - "testid" : "abc123", - "test2" : "GB134324" - }, + "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": "999", + "partnerCompany": "Test Partner", + "userEmailUpdatable": false } ``` | Type: *customer* | | -| :----------------------------- | :--------------------------------------------------------------------------------------------- | +|:----------------------------- |:--------------------------------------------------------------------------------------------- | | **Property** | **Description** | | type
*required* | The resource type ("customer").
*String* | +| id
*required* | The unique customer id ("5").
*String* | | uri
*read-only* | URI of this instance.
*String* | | created
*read-only* | UTC time when the resource was created (ISO8601 format).
*String* | | accountType
*read-only* | The account types are:
Business (**business**) - full hosted PBX with all the usual business features (call queues, IVRs etc)
Residential Plus (**residential**) - a cut down version aimed at home users, but still having the concept of extensions and ring groups to enable everyone in the home to have their own extension/number and use the mobile app etc.
Residential (**wlr**) - a basic PSTN replacement service, having just a phone number and voicemail. No concept of extensions or mobile apps.| @@ -314,7 +324,11 @@ The customers resource is the starting point for most account-level operations. | postcode
*required* | Primary location postcode.
*String* | | country
*required* | Primary location country.
*String* | | properties[]
*optional* | A collection of customisable properties that could be used to store varying ids
*Array* | +| enabled
*required* | Enabled or not.
*Boolean* | | 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,15 +337,19 @@ 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 -HTTP/1.1 200 OK + + + +```json { "totalItems": 1, @@ -340,22 +358,48 @@ HTTP/1.1 200 OK "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" + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": {}, + "enabled": true, + "currency": "GBP", + "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": "999", + "partnerCompany": "Test Partner", + "userEmailUpdatable": false } ] } ``` - + + #### Get customer @@ -363,44 +407,146 @@ 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 -HTTP/1.1 200 OK + + + +```json { "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", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "email": "Test@test.com", + "country": "GB", + "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/99999/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/99999/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/99999/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/99999/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/99999/sms" + }, + "partnerId": "999", + "partnerCompany": "Test Partner", + "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. + + + + + +``` +POST https://pbx.sipcentric.com/api/v1/customers +``` + +```json +{ + "type": "customer", + "accountType": "BUSINESS", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": { + "customid": "abc123" + }, + "enabled": true, + "currency": "GBP", + "userEmailUpdatable": false +} +``` + + + + +```json +HTTP/1.1 201 Created + + +{ + "type": "customer", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999", + "created": "2023-05-24T11:18:36Z", + "accountType": "BUSINESS", + "company": "Sipcentric", + "firstName": "Test", + "lastName": "User", + "telephone": "03301201200", + "email": "Test@test.com", + "address1": "Simwood House", + "address2": "Cube M4 Business Park", + "city": "Bristol", + "postcode": "BS16 1FX", + "country": "GB", + "properties": { + "customid": "abc123" + }, + "enabled": true, + "currency": "GBP", + "links": { + "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids", + "endpoints": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints", + "preferences": "https://pbx.sipcentric.com/api/v1/customers/99999/preferences", + "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals", + "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers", + "bargeGroups": "https://pbx.sipcentric.com/api/v1/customers/99999/bargegroups", + "callBundles": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles", + "linkedUsers": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers", + "sounds": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds", + "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook", + "calls": "https://pbx.sipcentric.com/api/v1/customers/99999/calls", + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings", + "sms": "https://pbx.sipcentric.com/api/v1/customers/99999/sms" + }, + "userEmailUpdatable": false } + ``` + + + ### Phone Book @@ -417,14 +563,18 @@ 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 +```json { - "type" : "phonebookentry", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773", - "created" : "2014-03-10T13:38:00.000+0000", - "name" : "Sipcentric", - "phoneNumber" : "01212854400", - "speedDial" : 5 + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@Test.com", + "speedDial": 123, + "priority": 0 } ``` @@ -432,11 +582,15 @@ The phonebook sub-resource allows users to read and organize an account's shared |:------------------------------|:-------------------------------------------------------------------------| | **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 +599,52 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonebook?pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems" : 18, - "pageSize" : 2, - "page" : 1, - "items" : [ + "totalItems": 5, + "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" + "type": "phonebookentry", + "id": "84033", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-03T17:21:14Z", + "name": "Test Contact", + "phoneNumber": "256754999999", + "email": "email@Test.com", + "speedDial": 123, + "priority": -50 + },{ + "type": "phonebookentry", + "id": "84039", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84039", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-04T09:13:08Z", + "name": "Fred Test 3", + "phoneNumber": "256761303030", + "priority": 0 } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook?pageSize=2&page=2" } ``` - + + #### Read phone book entry @@ -485,26 +652,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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/773 ``` -```response + + + +```json 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/99999/phonebook/84033", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "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 +690,42 @@ 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: + + + +``` +POST https://pbx.sipcentric.com/api/v1/customers/99999/phonebook ``` -POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook +```json { - "type" : "phonebookentry", - "name" : "Fred Mobile", - "phoneNumber" : "07902000000", - "speedDial" : 4 + "type": "phonebookentry", + "name": "Fred Mobile", + "phoneNumber": "07902000000", + "priority": 0 } ``` -```response + + + +```json 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", + "id": "84072", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/84072", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-05T10:30:15Z", "name": "Fred Mobile", "phoneNumber": "07902000000", - "speedDial": 4 + "priority": 0 } ``` - + + #### Update phone book entry @@ -545,32 +733,42 @@ 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: + + + ``` -PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716 +PUT https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716 +``` +```json { - "type" : "phonebookentry", - "name" : "Fred Mobile", - "phoneNumber" : "07825000000", - "speedDial" : 12 + "type": "phonebookentry", + "name": "Fred Mobile", + "phoneNumber": "07825000000", + "speedDial": 12 } ``` -```response + + + +```json + HTTP/1.1 200 OK { "type": "phonebookentry", - "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716", - "created" : "2014-03-10T13:38:00.000+0000", + "uri": "http://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716", + "created": "2014-03-10T13:38:00.000+0000", "name": "Fred Mobile", "phoneNumber": "07825000000", "speedDial": 12 } -``` +``` + + #### Delete phone book entry @@ -578,13 +776,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 +DELETE https://pbx.sipcentric.com/api/v1/customers/99999/phonebook/716 ``` -```response + + + +```json HTTP/1.1 204 No Content ``` + + ### SMS @@ -601,34 +807,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`. -``` +```json { - "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/99999/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test 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 +847,58 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sms?pageSize=2&page=1 ``` -```response -HTTP/1.1 200 OK + + +```json +HTTP/1.1 200 OK { - "totalItems": 188, + "totalItems": 3, "pageSize": 2, "page": 1, - "items": [ - { + "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 - }, { + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-05T10:48:45Z", + "direction": "OUT", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", + "sendStatus": "SENT", + "deliveryStatus": 1, + "cost": 0.080, + "creditsUsed": 1 + },{ "type": "smsmessage", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "31414338", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414338", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-05T10:45:07Z", "direction": "OUT", - "from": "01212854400", - "to": "07902000000", - "body": "Hey, this API is awesome!", + "from": "012345678901", + "to": "012345678901", + "body": "second check on you", "sendStatus": "SENT", "deliveryStatus": 1, - "cost": 0.1 - } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=2" + "cost": 0.080, + "creditsUsed": 1 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/?createdBefore=2023-05-05T10:51:13Z&pageSize=2&page=2" } ``` + + #### Get SMS Message @@ -679,58 +906,83 @@ HTTP/1.1 200 OK Returns the instance of a specific `smsmessage`. + + + ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sms/999993368 ``` -```response + + + +```json 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/99999/sms/31408968", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-03T17:27:59Z", + "direction": "OUT", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test 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. + + + ``` -POST https://pbx.sipcentric.com/api/v1/customers/25/sms +POST https://pbx.sipcentric.com/api/v1/customers/99999/sms +``` +```json { "type": "smsmessage", - "to": "07902000000", - "from": "01212854400", - "body": "Hey, this API is awesome!" + "to": "012345678901", + "from": "012345678901", + "body": "This is a test sms" } ``` -```response + + + +```json HTTP/1.1 201 Created { "type": "smsmessage", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368", + "id": "31414341", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sms/31414341", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", "direction": "OUT", - "from": "01212854400", - "to": "07902000000", - "body": "Hey, this API is awesome!", + "from": "012345678901", + "to": "012345678901", + "body": "This is a test sms", "sendStatus": "SENT", - "cost": 0.1 + "cost": 0.080, + "creditsUsed": 1 } ``` + + ### Calls @@ -753,23 +1005,28 @@ The scope of a call can be: - External - to/from an external number on the PSTN. -``` +```json { "type": "call", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592317", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "209925287", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/209925287", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-04-05T12:59:05Z", "scope": "EXTERNAL", - "direction": "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", + "direction": "OUT", + "from": "Test User <123>", + "to": "012345678901", + "callerId": "012345678901", + "callStarted": "2023-04-05T12:58:55Z", + "outcome": "ANSWERED", + "duration": 7, + "cost": 0.010, + "callId": "366e05e5-1680699535.1182575", + "linkedId": "366e05e5-1680699535.1182575", + "srcEndpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069", + "final": true, "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=366e05e5-1680699535.1182575" } } ``` @@ -777,19 +1034,24 @@ The scope of a call can be: | 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 +1073,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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { @@ -825,12 +1093,14 @@ HTTP/1.1 200 OK "items": [ { "type": "call", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592432", - "created" : "2014-03-10T13:47:05.000+0000", + "id": "7592432", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/7592432", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:47:05.000+0000", "scope": "EXTERNAL", "direction": "IN", - "from": "07557000000", - "to": "Sales Group <500>", + "from": "012345678901", + "to": "Test Group <123>", "callStarted": "2014-03-10T13:46:35.000+0000", "outcome": "NO_ANSWER", "duration": 0, @@ -838,16 +1108,18 @@ HTTP/1.1 200 OK "callId": "ast01-1400142051.1562723", "linkedId": "ast01-1400142051.1562723", "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=ast01-1400142051.1562723" } - }, { + },{ "type": "call", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592134", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "7592434", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/calls/7592434", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", "scope": "EXTERNAL", "direction": "OUT", - "from": "Greg Sanderson <103>", - "to": "07557000000", + "from": "Test User <123>", + "to": "012345678901", "callStarted": "2014-03-10T13:35:51.000+0000", "outcome": "ANSWERED", "duration": 60, @@ -855,12 +1127,15 @@ HTTP/1.1 200 OK "callId": "ast01-1401721105.2847099", "linkedId": "ast01-1401721105.2847099", "links": { - "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1401721105.2847099" + "recordings": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?linkedId=ast01-1401721105.2847099" } - } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2" + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/calls?pageSize=2&page=2" } ``` + + #### Originate call @@ -868,22 +1143,31 @@ 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 +POST https://pbx.sipcentric.com/api/v1/customers/99999/calls +``` +```json { "type": "call", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1234", - "to": "07902000000" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/1234", + "to": "012345678901" } ``` -```response + + + +```json 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 +1178,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 + + + +```json { "type": "phonestatus", "id": "94", @@ -909,25 +1198,36 @@ 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 +``` +```json { "type": "phonestatus", "dndActive": true } ``` -```response + + + +```json 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,35 +1289,48 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sounds?pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems" : 6, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "prompt", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046", - "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", - "created" : "2014-03-10T13:37:00.0000+0000", - "name" : "calls-may-be-recorded", - "size" : 69426 - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2" + "totalItems": 6, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "prompt", + "id": "1046", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1046", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:38:00.0000+0000", + "name": "thank-you-for-calling", + "size": 129612 + },{ + "type": "prompt", + "id": "1035", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.0000+0000", + "name": "calls-may-be-recorded", + "size": 69426 + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds?pageSize=2&page=2" } ``` + + #### Get sound @@ -1024,23 +1338,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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035 ``` -```response + + + +```json HTTP/1.1 200 OK { - "type" : "prompt", - "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 + "type": "prompt", + "id": "1035", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/sounds/1035", + "created": "2014-03-10T13:37:00.0000+0000", + "name": "calls-may-be-recorded", + "size": 69426 } ``` + + It is also possible to fetch a copy of the audio file itself, by including the `Accept` header: @@ -1063,18 +1385,20 @@ 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 +```json { "type": "recording", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "1358371", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", "direction": "IN", "partyId": "106", "started": "2014-05-14T15:41:25.000+0000", "size": 9615, "callId": "ast01-1400082083.1542464", "linkedId": "ast01-1400082083.1542464", - "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" } ``` @@ -1108,75 +1432,97 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/recordings?pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems" : 5788, - "pageSize" : 2, - "page" : 1, - "items" : [ + "totalItems": 5788, + "pageSize": 2, + "page": 1, + "items": [ { - "type" : "recording", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372", - "created" : "2014-03-10T14:09:00.0000+0000", - "direction" : "OUT", - "partyId" : "07557000000", - "started" : "2014-03-10T14:07:00.0000+0000", - "size" : 97365, - "callId" : "ast01-1401721105.2847099", - "linkedId" : "ast01-1401721105.2847099", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928" - }, { - "type" : "recording", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "created" : "2014-03-10T13:42:00.0000+0000", - "direction" : "IN", - "partyId" : "07557000000", - "started" : "2014-03-10T13:37:00.0000+0000", - "size" : 9615, - "callId" : "ast01-1400082083.1542464", - "linkedId" : "ast01-1400082083.1542464", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=2" + "type": "recording", + "id": "1358372", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358372", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T14:09:00.0000+0000", + "direction": "OUT", + "partyId": "07557000000", + "started": "2014-03-10T14:07:00.0000+0000", + "size": 97365, + "callId": "ast01-1401721105.2847099", + "linkedId": "ast01-1401721105.2847099", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/1928" + },{ + "type": "recording", + "id": "1358371", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:42:00.0000+0000", + "direction": "IN", + "partyId": "07557000000", + "started": "2014-03-10T13:37:00.0000+0000", + "size": 9615, + "callId": "ast01-1400082083.1542464", + "linkedId": "ast01-1400082083.1542464", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings?pageSize=2&page=2" } ``` + + + #### 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371 ``` -```response + + + +```json HTTP/1.1 200 OK { "type": "recording", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371", - "created" : "2014-03-10T13:42:00.0000+0000", - "direction" : "IN", - "partyId" : "07557000000", - "started" : "2014-03-10T13:37:00.0000+0000", - "size" : 9615, - "callId" : "ast01-1400082083.1542464", - "linkedId" : "ast01-1400082083.1542464", - "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535" + "id": "1358371", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/recordings/1358371", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:42:00.0000+0000", + "direction": "IN", + "partyId": "07557000000", + "started": "2014-03-10T13:37:00.0000+0000", + "size": 9615, + "callId": "ast01-1400082083.1542464", + "linkedId": "ast01-1400082083.1542464", + "endpoint": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/9999935" } ``` + + It is also possible to fetch a copy of the audio file itself, by including the `Accept` header: @@ -1199,34 +1545,38 @@ See [Response Formats](#response-formats) for more information. A time interval (`timeinterval`) defines the single or set of time periods which together, constitute a recurring weekly/yearly event or work pattern - for example, "Out of Hours", "Public Holidays" or "My Cat's Birthday". Time intervals are used for matching against when defining time-based routing or access rules elsewhere on the system. -```exampleRepresentation +```json { "type": "timeinterval", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "431", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "12:15", - "endTime" : "13:14" - } ] + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "TUE", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "WED", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "THU", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "FRI", + "startTime": "12:15", + "endTime": "13:14" + } + ] } ``` @@ -1234,7 +1584,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,62 +1604,80 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals?pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems" : 5, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "timeinterval", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32", - "created" : "2014-03-10T13:37:00.000+0000", - "name" : "Christmas Day", - "repeat" : "YEARLY", - "includedTimes" : [ { - "month" : "DEC", - "dayOfMonth" : 25, - "startTime" : "00:00", - "endTime" : "23:59" - } ] - }, { - "type" : "timeinterval", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31", - "created" : "2014-03-10T13:27:00.000+0000", - "name" : "Office Hours", - "repeat" : "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "09:00", - "endTime" : "17:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "09:00", - "endTime" : "16:59" - } ] - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2" + "totalItems": 5, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "timeinterval", + "id": "32", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/32", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "name": "Christmas Day", + "repeat": "YEARLY", + "includedTimes": [ + { + "month": "DEC", + "dayOfMonth": 25, + "startTime": "00:00", + "endTime": "23:59" + } + ] + },{ + "type": "timeinterval", + "id": "8675", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/31", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:27:00.000+0000", + "name": "Office Hours", + "repeat": "WEEKLY", + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "TUE", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "WED", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "THU", + "startTime": "09:00", + "endTime": "17:29" + },{ + "dayOfWeek": "FRI", + "startTime": "09:00", + "endTime": "16:59" + } + ] + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals?pageSize=2&page=2" } ``` + + + #### Get time interval @@ -1315,46 +1685,58 @@ 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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431 ``` -```response + + + +```json HTTP/1.1 200 OK { "type": "timeinterval", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "431", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/431", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", "name": "Lunchtimes", "repeat": "WEEKLY", - "includedTimes" : [ { - "dayOfWeek" : "MON", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "TUE", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "WED", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "THU", - "startTime" : "12:30", - "endTime" : "13:29" - }, { - "dayOfWeek" : "FRI", - "startTime" : "12:15", - "endTime" : "13:14" - } ] + "includedTimes": [ + { + "dayOfWeek": "MON", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "TUE", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "WED", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "THU", + "startTime": "12:30", + "endTime": "13:29" + },{ + "dayOfWeek": "FRI", + "startTime": "12:15", + "endTime": "13:14" + } + ] } ``` + + + ### Endpoints | Resource Information | | @@ -1363,7 +1745,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 +1826,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 +1838,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 +1859,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 +1873,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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints?pageSize=2&page=1 ``` -```response + + + +```json HTTP/1.1 200 OK { @@ -1499,208 +1892,757 @@ HTTP/1.1 200 OK "pageSize": 2, "page": 1, "items": [ - { + { "type": "ivr", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102", - "created" : "2014-03-10T13:38:00.000+0000", + "id": "83066", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:38:00.000+0000", "shortNumber": "001", "name": "Main IVR", "timeout": 4 }, { "type": "phone", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "created" : "2014-03-10T13:37:00.000+0000", - "shortNumber" : "102", - "name" : "John Simmonds", - "email" : "john@sipcentric.com", - "timeout" : 30, - "callWaiting" : true, - "callRecording" : "ALWAYS", - "voicemailEnabled" : true + "id": "101", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "shortNumber": "102", + "name": "John Simmonds", + "email": "john@sipcentric.com", + "timeout": 30, + "callWaiting": true, + "callRecording": "ALWAYS", + "voicemailEnabled": true } ], - "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=1&page=2" + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/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 +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101 ``` -```response + + + +```json HTTP/1.1 200 OK { "type": "phone", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "created" : "2014-03-10T13:37:00.000+0000", - "shortNumber" : "102", - "name" : "John Simmonds", - "email" : "john@sipcentric.com", - "timeout" : 30, - "callWaiting" : true, - "callRecording" : "ALWAYS", - "voicemailEnabled" : true, - "links" : { - "sip" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/sip", - "voicemail" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/voicemail" + "id": "101", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "shortNumber": "102", + "name": "John Simmonds", + "email": "john@sipcentric.com", + "timeout": 30, + "callWaiting": true, + "callRecording": "ALWAYS", + "voicemailEnabled": true, + "links": { + "sip": "http://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101/sip", + "voicemail": "http://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101/voicemail" } } ``` + + -### Phone Numbers +#### List endpoints filterd by type. -| Resource Information | | -|:-------------------------------|:-------------------------------------| -| Location | /customers/{customerId}/phonenumbers | -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | did | -| Additional Formats | None | +`GET /customers/{customerId}/endpoints?type={endpointType}` -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`. +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. + + + -```exampleRepresentation -{ - "type" : "did", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "support@sipcentric.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false, - "routingRules" : [ { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - } ] -} +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/endpoints?type=phone ``` -| Type: *did* | | -|:-------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("did").
*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* | 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* | -| destination
*optional* | The URI of the internal endpoint to which calls to this number will be routed by default. Valid only if faxEnabled = false.
*String* | -| smsEnabled
*read-only* | Determines whether SMS functionality is supported on this number. Only certain numbers will have SMS capabilities. It is not possible to receive SMS messages on ported numbers.
*Boolean* | -| smsAllowIncoming
*conditionally required* | A user may choose whether to allow or disallow incoming messages. Valid only if smsEnabled = true.
*Boolean* | -| smsNotificationEmail
*optional* | The email address to which we should send incoming SMS notifications. Valid only if smsEnabled = true.
*String* | -| smsNotificationUrl
*optional* | When an SMS is received to this number, we will send a POST to the specified URL and include the following form encoded parameters: "to", "from", "body", "udh" (user data header - used for linking concatenated messages together). Valid only if smsEnabled = true.
*String* | -| faxEnabled
*required* | Whether this number should be designated for fax-to-email. It is not currently possible to receive both voice calls and faxes to a single number - therefore, "faxEnabled" and "destination" are mutually exclusive.
*Boolean* | -| faxNotificationEmail
*optional* | The email address to which we should send incoming faxes (converted to PDF). Valid only if faxEnabled = true. | -| routingRules[]
*optional* | Time-based routing rules (exceptions) that apply to this number.
*Array* | -| routingRules[].timeInterval
*required* | URI of the time interval during which this rule applies.
*String* | -| routingRules[].destination
*required* | URI of endpoint to which calls during the matched time interval should routed.
*String* | + + +```json -#### List phone numbers +{ + "totalItems": 2, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "phone", + "id": "83069", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-01-24T17:12:05Z", + "shortNumber": "100", + "name": "Fred Muteesa", + "timeout": 30, + "callWaiting": false, + "callRecording": "OFF", + "defaultCallerId": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/49610", + "voicemailSettings": { + "autoAnswer": false, + "pin": "0000", + "playEnvelope": false, + "playCallerId": false, + "allowReview": false + }, + "links": { + "sip": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83069/phonestatus" + } + },{ + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "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/99999/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/phonestatus" + } + } + ] +} -`GET /customers/{customerId}/phonenumbers` +``` -Returns a list of all phone numbers on a customer account. + + + +#### Updating an endpoint. + +`PUT /customers/{customerId}/endpoints/{endpointId} ` + +Depending on what property of the end point you want to update, you will need to send a PUT request to the following resrouce. You have to know the endpointID and the endpoint type. Depending on the endpoint type you are updating, some fields are required in the body, hence if you miss difinition of one of the parameters, your request will fail. In the example below I am updating the name of the IVR, but the rest of the fields I have included must be provided for the request to work. -Example request: + + + ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=1 +PUT https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83066 +``` + +```json +{ + "type":"ivr", + "id":"83066", + "name":"Fred-lab-ivr2", + "timeout":5, + "shortNumber":500 +} ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems" : 15, - "pageSize" : 2, - "page" : 1, - "items" : [ { - "type" : "did", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "Main", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@fredbloggs.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false - }, { - "type" : "did", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854411", - "identifier" : "", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "support@sipcentric.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false, - "routingRules" : [ { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - }, { - "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704", - "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102" - } ] - } ], - "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2" + "type": "ivr", + "id": "83066", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/83066", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-01-24T16:43:22Z", + "shortNumber": "500", + "name": "Fred-lab-ivr2", + "timeout": 5, + "items": [] } + ``` + + -#### Get phone number -`GET /customers/{customerId}/phonenumbers/{numberId}` +#### 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. -Retrieves the instance of a specific phone number. -Example request: + + + ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47 +POST https://pbx.sipcentric.com/api/v1/customers/{customerId}/endpoints ``` -```response -HTTP/1.1 200 OK - +```json { - "type" : "did", - "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47", - "created" : "2014-03-10T13:37:00.000+0000", - "number" : "01212854400", - "identifier" : "Main", - "smsEnabled" : true, - "smsAllowIncoming" : true, - "smsNotificationEmail" : "contact@fredbloggs.com", - "smsNotificationUrl" : "https://example.com/sms", - "faxEnabled" : false + "callRecording":"OFF", + "timeout":30, + "name":"Fred", + "shortNumber":"102", + "type":"phone" } ``` + + + +```json + +HTTP/1.1 200 OK + +{ + "type": "phone", + "id": "89937", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-15T19:43:10Z", + "shortNumber": "102", + "name": "Fred", + "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/99999/endpoints/89937/sip", + "forwardingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/forwardingrules", + "status": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937/phonestatus" + } +} +``` + + + + +#### 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/99999/endpoints/83066 +``` + + + + +### Phone Numbers + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/phonenumbers | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| 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`. + +```json +{ + "type": "did", + "id": "50", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "support@sipcentric.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false, + "routingRules": [ + { + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + } + ] +} +``` + +| Type: *did* | | +|:-------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("did").
*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* | +| destination
*optional* | The URI of the internal endpoint to which calls to this number will be routed by default. Valid only if faxEnabled = false.
*String* | +| smsEnabled
*read-only* | Determines whether SMS functionality is supported on this number. Only certain numbers will have SMS capabilities. It is not possible to receive SMS messages on ported numbers.
*Boolean* | +| smsAllowIncoming
*conditionally required* | A user may choose whether to allow or disallow incoming messages. Valid only if smsEnabled = true.
*Boolean* | +| smsNotificationEmail
*optional* | The email address to which we should send incoming SMS notifications. Valid only if smsEnabled = true.
*String* | +| smsNotificationUrl
*optional* | When an SMS is received to this number, we will send a POST to the specified URL and include the following form encoded parameters: "to", "from", "body", "udh" (user data header - used for linking concatenated messages together). Valid only if smsEnabled = true.
*String* | +| faxEnabled
*required* | Whether this number should be designated for fax-to-email. It is not currently possible to receive both voice calls and faxes to a single number - therefore, "faxEnabled" and "destination" are mutually exclusive.
*Boolean* | +| faxNotificationEmail
*optional* | The email address to which we should send incoming faxes (converted to PDF). Valid only if faxEnabled = true. | +| routingRules[]
*optional* | Time-based routing rules (exceptions) that apply to this number.
*Array* | +| routingRules[].timeInterval
*required* | URI of the time interval during which this rule applies.
*String* | +| routingRules[].destination
*required* | URI of endpoint to which calls during the matched time interval should routed.
*String* | + + +#### List phone numbers + +`GET /customers/{customerId}/phonenumbers` + +Returns a list of all phone numbers on a customer account. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers?pageSize=2&page=1 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "totalItems": 15, + "pageSize": 2, + "page": 1, + "items": [ + { + "type": "did", + "id": "47", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "Main", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "contact@Fredbloggs.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false + },{ + "type": "did", + "id": "50", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/50", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "identifier": "", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/101", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "support@sipcentric.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false, + "routingRules": [ + { + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/594", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/625", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + },{ + "timeInterval": "https://pbx.sipcentric.com/api/v1/customers/99999/timeintervals/704", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/102" + } + ] + } + ], + "nextPage": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers?pageSize=2&page=2" +} +``` + + + +#### Get phone number + +`GET /customers/{customerId}/phonenumbers/{numberId}` + +Retrieves the instance of a specific phone number. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "did", + "id": "47", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/47", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854400", + "identifier": "Main", + "smsEnabled": true, + "smsAllowIncoming": true, + "smsNotificationEmail": "contact@Fredbloggs.com", + "smsNotificationUrl": "https://example.com/sms", + "faxEnabled": false +} +``` + + + +#### Add a new Phone Number + +`POST /customers/{customerId}/phonenumbers` + +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. + + + + + +``` +POST https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers +``` + +```json +{ + "createFrom":"4-44-113-4037921", + "type":"did" +} +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/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. + + + + + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/{customerId}/phonenumbers/{phonenumberId}/ +``` + +```json +{ + "type": "did", + "id": "73224", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/{phonenumberId}", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2022-01-06T11:12:46Z", + "number": "01134031453", + "formatted": "0113 403 1453", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/{phonenumberId}/routingrules" + }, + "destination":"89937" +} +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/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. + + + + + + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854 +``` + +```json +{ + "type":"did", + "id":"94854", + "uri":"https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent":"https://pbx.sipcentric.com/api/v1/customers/99999", + "created":"2023-05-12T14:11:06.000Z", + "number":"01134037921", + "formatted":"0113 403 7921", + "smsCapable":false, + "faxEnabled":false, + "links": { + "routingRules":"https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854/routingrules" + } + } +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "did", + "id": "94854", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/phonenumbers/94854", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2023-05-12T14:11:06Z", + "number": "01134037921", + "formatted": "0113 403 7921", + "destination": "https://pbx.sipcentric.com/api/v1/customers/99999/endpoints/89937", + "smsCapable": false, + "faxEnabled": false, + "links": { + "routingRules": "https://pbx.sipcentric.com/api/v1/customers/99999/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/99999/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. + +```json +{ + "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 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "totalItems": 21, + "pageSize": 100, + "page": 1, + "items": [ + { + "type": "availablenumber", + "id": "4-44-113-4037921", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921", + "country": "44", + "areaCode": "113", + "number": "4037921", + "formatted": "0113 403 7921" + },{ + "type": "availablenumber", + "id": "4-44-113-4037924", + "uri": "https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037924", + "country": "44", + "areaCode": "113", + "number": "4037924", + "formatted": "0113 403 7924" + }, + ...... + ] +} +``` + + + +#### Get an available number + +`GET /availablenumber/{availablenumberId}` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/availablenumbers/4-44-113-4037921 +``` + + + + +```json +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 | | @@ -1715,11 +2657,13 @@ HTTP/1.1 200 OK Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an `outgoingcallerid`. -```exampleRepresentation +```json { "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", "number": "07932000000", "allowCalls": false, "allowSms": true @@ -1730,245 +2674,1827 @@ Usually, when making calls or sending SMS messages from an account, the outgoing |:------------------------------|:----------------------------------------------------------------------------------------| | **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 +#### List outgoing caller ids + +`GET /customers/{customerId}/outgoingcallerids` + +Lists the IDs which have been approved for use on the account. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "totalItems": 2, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "outgoingcallerid", + "id": "115", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/115", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "Sipcentric", + "allowCalls": false, + "allowSms": true + },{ + "type": "outgoingcallerid", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "allowCalls": true, + "allowSms": true + } + ] +} +``` + + + +#### Get outgoing caller id + +`GET /customers/{customerId}/outgoingcallerids/{id}` + +Get the instance of a specific caller ID. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "outgoingcallerid", + "id": "114", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/outgoingcallerids/114", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-10T13:37:00.000+0000", + "number": "01212854411", + "allowCalls": true, + "allowSms": true +} +``` + + + +### Credit Status + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/creditstatus | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | creditstatus | +| Additional Formats | None | + +The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. + +```json +{ + "type": "creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999", + "accountType": "PREPAID", + "creditRemaining": 19.571 +} +``` + +| Type: *creditstatus* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("creditstatus")
*String* | +| uri
*read-only* | URI of this instance.
*String* | +| accountType
*read-only* | The type of account.
*Enum: PREPAID, POSTPAID* | +| balance
*read-only* | Balance on the account
*Float* | + +#### Get credit status + +`GET /customers/{customerId}/creditstatus` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "creditstatus", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/creditstatus", + "accountType": "PREPAID", + "balance": 19.571 +} +``` + + + +### Call Bundles + +| Resource Information | | +|:-------------------------------|:------------------------------------| +| Location | /customers/{customerId}/callbundles | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | customerbundle | +| Additional Formats | None | + +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. + +```json +{ + "type": "customerbundle", + "id": "1040", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-01T00:00:00.000+0000", + "name": "1000 Mins - UK Local/National", + "inclusiveMins": 1000, + "priceMonthly": 5, + "validFrom": "2014-03-01T00:00:00.000+0000", + "validTo": "2014-03-31T23:59:59.999+0000", + "usedMins": 57, + "availableMins": 943, + "autoRenew": true, + "status": "ACTIVE" +} +``` + +| Type: *customerbundle* | | +|:---------------------------------|:------------------------------------------------------------------------------------------| +| **Property** | **Description** | +| type
*required* | The resource type ("customerbundle").
*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* | +| priceMonthly
*read-only* | The monthly renewal cost in GBP.
*Integer* | +| validFrom
*read-only* | UTC time from which the bundle is valid (ISO8601 format).
*String* | +| validTo
*read-only* | UTC time when the bundle expires (ISO8601 format).
*String* | +| usedMins
*read-only* | The number of minutes used up.
*Integer* | +| availableMins
*read-only* | The number of minutes remaining.
*Integer* | +| autoRenew
*required* | Whether the bundle is set to automatically renew.
*Boolean* | +| status
*read-only* | The current status of the bundle.
*Enum: ACTIVE, EXPIRED* | + +#### List call bundles + +`GET /customers/{customerId}/callbundles` + +List all bundles added to an account. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/callbundles +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "totalItems": 1, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "customerbundle", + "id": "1040", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-01T00:00:00.000+0000", + "name": "1000 Mins - UK Local/National", + "inclusiveMins": 1000, + "priceMonthly": 5, + "validFrom": "2014-03-01T00:00:00.000+0000", + "validTo": "2014-03-31T23:59:59.999+0000", + "usedMins": 57, + "availableMins": 943, + "autoRenew": true, + "status": "ACTIVE" + } + ] +} +``` + + + + +#### Get call bundle + +`GET /customers/{customerId}/callbundles/{bundleId}` + +Fetches the instance of a specific customer bundle. + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/1040 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customerbundle", + "id": "999999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callbundles/999999", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "created": "2014-03-01T00:00:00.000+0000", + "name": "1000 Mins - Local/National (Free)", + "inclusiveMins": 1000, + "priceMonthly": 5, + "validFrom": "2014-03-01T00:00:00.000+0000", + "validTo": "2014-03-31T23:59:59.999+0000", + "usedMins": 57, + "availableMins": 943, + "autoRenew": true, + "status": "ACTIVE" +} +``` + + + +### Call Charging + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/callcharging | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | callcharging | +| Additional Formats | None | + +The call charging sub-resource returns the current call charging plan for an account, represented by a `callcharging` instance. + +```json +{ + "type": "customercallcharging", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/9999999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + +| 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 https://pbx.sipcentric.com/api/v1/customers/99999/callcharging +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customercallcharging", + "id": "999999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + + + + +#### Updating callcharging plan for a customer + +`PUT /customers/{customerId}/callcharging` + + + + + +``` +PUT https://pbx.sipcentric.com/api/v1/customers/99999/callcharging +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customercallcharging", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/999999/callcharging", + "parent": "https://pbx.sipcentric.com/api/v1/customers/999999", + "chargingPlan": "https://pbx.sipcentric.com/api/v1/chargingplans/999999", + "postpaid": true, + "creditLimit": 50.00, + "warningThreshold": 0.00 +} +``` + + + + +### 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. + +```json +{ + "type": "customerpermissions", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true +} +``` + +| Type: *permissions* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("permissions")
*String* | +| id
*required* | The resource customer id.
*String* | +| uri
*read-only* | URI to get customer permissions.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| incomingCalls
*read-only* | Can account receive calls?
*boolean* | +| outgoingCalls
*read-only* | Can the account make calls?
*boolean* | +| internationalCalls
*read-only* | can the customer make international calls?
*boolean* | +| addFeatures
*read-only* | Can the customer add features?
*boolean* | +| removeFeatures
*read-only* | Can the customer remove features?
*boolean* | +| enableRecording
*read-only* | Can the customer enable recording?
*boolean* | + +#### Get Customer Permissions + +`GET /customers/{customerId}/permissions` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/permissions +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customerpermissions", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/permissions", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "incomingCalls": true, + "outgoingCalls": true, + "internationalCalls": false, + "addFeatures": true, + "removeFeatures": true, + "enableRecording": true +} +``` + + + + +### Billing + +| Resource Information | | +|:-------------------------------|:-------------------------------------| +| Location | /customers/{customerId}/billing | +| Rate Limited? | Yes | +| Requests per rate limit window | 1200/hour | +| Authentication | Basic Auth | +| HTTP Method(s) | [GET](#get) | +| JSON Representation(s) | billing | +| Additional Formats | None | + +The billing sub-resource returns the current billing configuration and pricing plan for different features, represented by a `billing` instance. + +```json +{ + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "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/99999/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/estimate" + } +} +``` + +| Type: *billing* | | +|:-------------------------------|:------------------------------------------------------| +| **Property** | **Description** | +| type
*read-only* | The resource type ("billing")
*String* | +| uri
*read-only* | URI to get customer billing.
*String* | +| parent
*read-only* | URI of this customer account.
*String* | +| paymentsEnabled
*read-only* | is the account being billed?
*boolean* | +| upgradeAllowed
*read-only* | Can the account upgrade
*boolean* | +| downgradeAllowed
*read-only* | can account downgrade?
*boolean* | +| paymentMethodRequired
*read-only* | is payment required for this account?
*boolean* | +| currency
*read-only* | account currency default is GBP
*string* | +| frequency
*read-only* | billing frequence (Monthly)
*string* | +| featurePricing
*read-only* | prices of the features
*string* | + +#### Get Billing + +`GET /customers/{customerId}/billing` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/billing +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "billingaccount", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/billing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "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/99999/billing/invoices", + "paymentMethods": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/paymentmethods", + "estimate": "https://pbx.sipcentric.com/api/v1/customers/99999/billing/estimate" + } +} +``` + + + + +### 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. + + + +```json +{ + "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* | Unit price of resource.
*float* | +| quantity
*read-only* | Number of resources.
*integer* | +| lineTotal
*read-only* | Total of quantity multiplied by unit price.
*float* | +| usage
*read-only* | If this is a usage charge.
*boolean* | + + +#### Get Billing Estimate + +`GET /customers/{customerId}/billing/estimates/` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "invoice", + "id": "E5", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5/billing/estimate", + "created": "2023-05-17T15:22:38Z", + "netAmount": 133.00, + "vatAmount": 26.60, + "total": 159.60, + "lines": [ + { + "description": "Phone Extension", + "unitPrice": 3.00, + "quantity": 31, + "lineTotal": 93.00, + "usage": false + },{ + "description": "Virtual Extension", + "unitPrice": 0.00, + "quantity": 11, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Additional Mailbox", + "unitPrice": 0.00, + "quantity": 3, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Ring Group", + "unitPrice": 0.00, + "quantity": 5, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Call Queue", + "unitPrice": 0.00, + "quantity": 7, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Voice Menu/IVR", + "unitPrice": 0.00, + "quantity": 7, + "lineTotal": 0.00, + "usage": false + },{ + "description": "Public Number", + "unitPrice": 0.00, + "quantity": 34, + "lineTotal": 0.00, + "usage": false + },{ + "description": "500 Mins - UK Mobile", + "unitPrice": 25.00, + "quantity": 1, + "lineTotal": 25.00, + "usage": false + },{ + "description": "250 Mins - UK Mobile", + "unitPrice": 15.00, + "quantity": 1, + "lineTotal": 15.00, + "usage": false + },{ + "description": "1000 Mins - Local/National (Free)", + "unitPrice": 0.00, + "quantity": 1, + "lineTotal": 0.00, + "usage": false + } + ], + "date": "2023-05-17T15:22:38Z", + "credit": false, + "currency": "GBP" +} + +``` + + + + + + + +### 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. + +```json +{ + "type": "customerlimits", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "phone": 50, + "group": 10, + "queue": 10, + "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* | Limit of extensions.
*integer* | +| group
*read-only* | Limit of groups.
*integer* | +| queue
*read-only* | Limit of queues.
*integer* | +| ivr
*read-only* | Limit of ivrs.
*integer* | +| mailbox
*read-only* | Limit of shared mailboxes.
*integer* | +| did
*read-only* | Limit of incoming numbers.
*integer* | +| channel
*read-only* | Channel limit.
*integer* | + +#### Get Account Limits + +`GET /customers/{customerId}/limits` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/limits +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customerlimits", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/limits", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "phone": 50, + "group": 10, + "queue": 10, + "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. + +```json +{ + "type": "customerpricing", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "phone": 2.00, + "virtual": 0.10, + "group": 4.00, + "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 per extension.
*float* | +| group
*read-only* | Price per ring group.
*float* | +| queue
*read-only* | Price per call queue.
*float* | +| ivr
*read-only* | Price per IVR.
*float* | +| mailbox
*read-only* | Price per shared mailbox.
*float* | +| did
*read-only* | Price per incoming number.
*float* | + + +#### Get Pricing + +`GET /customers/{customerId}/pricing` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/pricing +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "customerpricing", + "id": "99999", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/pricing", + "parent": "https://pbx.sipcentric.com/api/v1/customers/99999", + "phone": 2.00, + "virtual": 0.10, + "group": 4.00, + "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 +``` + +```json +{ + "type": "customerpricing", + "phone": 7 +} +``` + + + + +```json +HTTP/1.1 200 OK +``` + + + +### Linkedusers (Web Users) + +| 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. + +```json +{ + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "Fred.muteesa+Test@simwood.com", + "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* | Timestamp for this user's creation.
*date* | +| userId
*read-only* | ID for this user.
*string* | +| email
*read-only* | Email for this user.
*string* | +| username
*read-only* | Username for this user.
*string* | +| accessLevel
*read-only* | This user's access level.
*string* | +| enabled
*read-only* | Whether the user is enabled or not.
*bolean* | +| pending
*read-only* | If the user is still pending activation.
*float* | +| acceptedInvite
*read-only* | If the user has accepted the invitation or not.
*float* | +| owner
*read-only* | Whether this user is the account owner.
*float* | +| recordingAccess
*read-only* | Level of call recording access.
*float* | + + +#### Get Linkedusers + +`GET /customers/{customerId}/linkedusers` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "totalItems": 1, + "pageSize": 20, + "page": 1, + "items": [ + { + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/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/99999/linkedusers/35180 +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "linkeduser", + "id": "35180", + "uri": "https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/35180", + "created": "2023-01-24T13:24:12Z", + "userId": "27068", + "email": "Fred.muteesa+Test@simwood.com", + "username": "fmuteesa", + "accessLevel": "CUSTOMER", + "enabled": true, + "pending": false, + "acceptedInvite": "2023-01-24T13:25:23Z", + "owner": true, + "recordingAccess": "ALL" +} +``` + + + +#### Get own linkeduser details +`GET /customers/{customerId}/linkedusers/me` + + + + + +``` +GET https://pbx.sipcentric.com/api/v1/customers/99999/linkedusers/me +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "linkeduser", + "uri": "https://pbx.sipcentric.com/api/v1/customers/5/linkedusers/me", + "userId": "27062", + "firstName": "Fred", + "lastName": "Muteesa", + "email": "Fred.muteesa@simwood.com", + "username": "Fred@sipcentric", + "accessLevel": "ADMIN", + "enabled": true, + "pending": false, + "owner": false, + "recordingAccess": "NONE" +} +``` + + + +#### 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. + + + +```json + { + "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* | Per minute cost for on-net calls.
*float* | +| roundSeconds
*requried* | How many seconds the call rounds to.
*integer* | +| minDuration
*read-only* | The minimum duration for calls.
*integer* | +| minCharge
*read-only* | Minimum call charge.
*float* | + + + +#### Get chargingplans -`GET /customers/{customerId}/outgoingcallerids` +`GET /chargingplans/` -Lists the IDs which have been approved for use on the account. + + -Example request: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids +GET https://pbx.sipcentric.com/api/v1/chargingplans/ ``` -```response -HTTP/1.1 200 OK + + +```json +HTTP/1.1 200 OK { - "totalItems": 2, + "totalItems": 10, "pageSize": 20, "page": 1, - "items": [ + "items": [ { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "Sipcentric", - "allowCalls": false, - "allowSms": true + "type": "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 }, - { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "01212854411", - "allowCalls": true, - "allowSms": true - } + .... ] } ``` + + -#### Get outgoing caller id +#### Get a charging plan -`GET /customers/{customerId}/outgoingcallerids/{id}` +`GET /chargingplans/{chargingplanId}` -Get the instance of a specific caller ID. + + -Example request: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114 +GET https://pbx.sipcentric.com/api/v1/chargingplans/8 ``` -```response + + + +```json HTTP/1.1 200 OK { - "type": "outgoingcallerid", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114", - "created" : "2014-03-10T13:37:00.000+0000", - "number": "01212854411", - "allowCalls": true, - "allowSms": true + "type": "chargingplan", + "id": "999", + "uri": "https://pbx.sipcentric.com/api/v1/chargingplans/999", + "name": "Test Chargingplan", + "currency": "GBP", + "domainCostMinute": 0.000, + "roundSeconds": 1, + "minDuration": 20, + "minCharge": 0.000 } ``` + + -### Credit Status +## Analytics | Resource Information | | |:-------------------------------|:-------------------------------------| -| Location | /customers/{customerId}/creditstatus | +| Location | /customers/{customerId}/calls/stats | | Rate Limited? | Yes | | Requests per rate limit window | 1200/hour | | Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | creditstatus | +| HTTP Method(s) | [GET](#get) (PUT/POST/DELETE) - not allowed | +| JSON Representation(s) | stats | | Additional Formats | None | -The credit status sub-resource returns the current call credit status of an account, represented by a `creditstatus` instance. +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 + +``` + + + + + + + + +```json +HTTP/1.1 200 OK -```exampleRepresentation { - "type": "creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "accountType": "PREPAID", - "creditRemaining": 19.571 + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=duration", + "columnHeaders": [ + { + "name": "duration", + "columnType": "METRIC" + } + ], + "rows": [ + [ + 108.0 + ] + ], + "totals": { + "duration": 108.0 + } } ``` + + -| Type: *creditstatus* | | -|:-------------------------------|:------------------------------------------------------| -| **Property** | **Description** | -| type
*read-only* | The resource type ("creditstatus")
*String* | -| uri
*read-only* | URI of this instance.
*String* | -| accountType
*read-only* | The type of account.
*Enum: PREPAID, POSTPAID* | -| balance
*read-only* | Balance on the account
*Float* | -#### Get credit status +#### Total cost -`GET /customers/{customerId}/creditstatus` + + + +``` +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 -Example request: +``` + + + + + +```json +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&metric=cost", + "columnHeaders": [ + { + "name": "cost", + "columnType": "METRIC" + } + ], + "rows": [ + [ + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } +} + +``` + + + + +#### Inbound Vs Outbound Duration + + + ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/creditstatus +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=direction&metric=duration ``` -```response + + + +```json HTTP/1.1 200 OK { - "type": "creditstatus", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus", - "accountType": "PREPAID", - "balance": 19.571 + "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 + } } + ``` + + -### Call Bundles -| Resource Information | | -|:-------------------------------|:------------------------------------| -| Location | /customers/{customerId}/callbundles | -| Rate Limited? | Yes | -| Requests per rate limit window | 1200/hour | -| Authentication | Basic Auth | -| HTTP Method(s) | [GET](#get) | -| JSON Representation(s) | customerbundle | -| Additional Formats | None | +#### 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 + +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=endpoint&metric=duration_in&metric=duration_out&endpointType=extension", + "columnHeaders": [ + { + "name": "endpoint", + "columnType": "DIMENSION" + },{ + "name": "duration_in", + "columnType": "METRIC" + },{ + "name": "duration_out", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "Fred Test <102>", + 0.0, + 55.0 + ],[ + "Ivan Example <111>", + 0.0, + 0.0 + ],[ + "Jared Example <215>", + 53.0, + 0.0 + ] + ], + "totals": { + "duration_in": 53.0, + "duration_out": 55.0 + } +} + +``` + + + +#### 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 + +``` + + + + +```json +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 +{ + "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": [ { - type: "customerbundle", - uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - created: "2014-03-01T00:00:00.000+0000", - name: "1000 Mins - UK Local/National", - inclusiveMins: 1000, - priceMonthly: 5, - validFrom: "2014-03-01T00:00:00.000+0000", - validTo: "2014-03-31T23:59:59.999+0000", - usedMins: 57, - availableMins: 943, - autoRenew: true, - status: "ACTIVE" + "name": "endpoint", + "columnType": "DIMENSION" + },{ + "name": "count_in", + "columnType": "METRIC" + },{ + "name": "count_out", + "columnType": "METRIC" } + ], + "rows": [ + [ + "Fred Test <102>", + 1.0, + 5.0 + ],[ + "Ivan Example <111>", + 1.0, + 0.0 + ],[ + "Jared Example <215>", + 3.0, + 1.0 + ] + ], + "totals": { + "count_in": 5.0, + "count_out": 6.0 + } +} ``` + + -| Type: *customerbundle* | | -|:---------------------------------|:------------------------------------------------------------------------------------------| -| **Property** | **Description** | -| type
*required* | The resource type ("customerbundle").
*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* | The bundle name.
*String* | -| inclusiveMins
*read-only* | The number of minutes to predefined destinations included in the bundle.
*Integer* | -| priceMonthly
*read-only* | The monthly renewal cost in GBP.
*Integer* | -| validFrom
*read-only* | UTC time from which the bundle is valid (ISO8601 format).
*String* | -| validTo
*read-only* | UTC time when the bundle expires (ISO8601 format).
*String* | -| usedMins
*read-only* | The number of minutes used up.
*Integer* | -| availableMins
*read-only* | The number of minutes remaining.
*Integer* | -| autoRenew
*required* | Whether the bundle is set to automatically renew.
*Boolean* | -| status
*read-only* | The current status of the bundle.
*Enum: ACTIVE, EXPIRED* | -#### List call bundles +**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 /customers/{customerId}/callbundles` -List all bundles added to an account. +#### Get Calls Outcome +This request gives you visibility into Call dispositions. That is, what happened to the call, was it answered or not? +You are able to see the number Unanswered calls + + + -Example request: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles +GET https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=outcome&metric=count&direction=in + ``` -```response + + + +```json HTTP/1.1 200 OK { - "totalItems": 1, - "pageSize": 20, - "page": 1, - "items": [ - { - type: "customerbundle", - uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - created: "2014-03-01T00:00:00.000+0000", - name: "1000 Mins - UK Local/National", - inclusiveMins: 1000, - priceMonthly: 5, - validFrom: "2014-03-01T00:00:00.000+0000", - validTo: "2014-03-31T23:59:59.999+0000", - usedMins: 57, - availableMins: 943, - autoRenew: true, - status: "ACTIVE" + "type": "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 call bundle + + -`GET /customers/{customerId}/callbundles/{bundleId}` +#### Get Top Callers -Fetches the instance of a specific customer bundle. +You can use the exmaple below to see which number calls your DID's the most. + + + -Example request: ``` -GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040 +GET +https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=callerid&metric=count&sort=-count&scope=external&direction=in&limit=10 + ``` -```response + + + +```json HTTP/1.1 200 OK { - "type": "customerbundle", - "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040", - "created": "2014-03-01T00:00:00.000+0000", - "name": "1000 Mins - Local/National (Free)", - "inclusiveMins": 1000, - "priceMonthly": 5, - "validFrom": "2014-03-01T00:00:00.000+0000", - "validTo": "2014-03-31T23:59:59.999+0000", - "usedMins": 57, - "availableMins": 943, - "autoRenew": true, - "status": "ACTIVE" + "type": "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 + +``` + + + + +```json +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=avg_duration&endpointType=queue", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "avg_duration", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "avg_duration": "NaN" + } +} + +``` + + + +#### 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 + +``` + + + + +```json +HTTP/1.1 200 OK + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=count_in&metric=count_out", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "count_in", + "columnType": "METRIC" + },{ + "name": "count_out", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 2.0, + 6.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0, + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0, + 0.0 + ] + ], + "totals": { + "count_in": 2.0, + "count_out": 6.0 + } +} +``` + + + +#### 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 + +``` + + + + +```json +HTTP/1.1 200 OK + + +{ + "type": "datatable", + "uri": "https://my.nimvelo.com/api/v1/customers/5/calls/stats?startedAfter=2023-05-21T21:00:00.000Z&startedBefore=2023-05-28T20:59:59.999Z&timeZone=%2B03%3A00&dimension=day&metric=cost", + "columnHeaders": [ + { + "name": "day", + "columnType": "DIMENSION" + },{ + "name": "cost", + "columnType": "METRIC" + } + ], + "rows": [ + [ + "2023-05-22T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-23T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-24T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-25T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-26T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-27T00:00:00.000+03:00", + 0.0 + ],[ + "2023-05-28T00:00:00.000+03:00", + 0.0 + ] + ], + "totals": { + "cost": 0.0 + } } ``` + + + ## Global Resources @@ -1981,7 +4507,7 @@ you would normally have to authenticate for. #### Get token -``` +```json GET https://pbx.sipcentric.com/api/v1/tokengenerator { @@ -1992,10 +4518,10 @@ GET https://pbx.sipcentric.com/api/v1/tokengenerator } ``` -You can now use this token to get a call recording using the `tokenid` parameter in the GET request: +You can now use this token to get a call recording using the `tokenid` parameter in the GET Request ``` -https://pbx.sipcentric.com/api/v1/customers/25/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16 +https://pbx.sipcentric.com/api/v1/customers/99999/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16 ``` Anyone that tried to use the request again will get a 401 Unauthorized. This prevents replay attacks from getting any data. @@ -2016,7 +4542,7 @@ Currently the following is available via the streaming API: Example object: -``` +```json { "event": "incomingcall", "location": null, @@ -2042,7 +4568,7 @@ Most HTTP client libraries let you handle the connection as a stream. Which allo All of the event objects are in a standard format: -``` +```json { "event": ..., "location": ..., diff --git a/docs/wholesale.md b/docs/wholesale.md index 510afbd..8a1fbd7 100644 --- a/docs/wholesale.md +++ b/docs/wholesale.md @@ -5,6 +5,6 @@ title: Wholesale ## Customer API documentation -- [v3.19.1
](https://cdn.simwood.com/docs/simwood_apiv3.pdf) (PDF) +- [v3.19.1](https://cdn.simwood.com/docs/simwood_apiv3.pdf) (PDF) Note Please click on the [Carrier Services](/docs/wholesale/introduction) to see the rest of the sidebar menu \ No newline at end of file