Table of Contents
API : SIP Account Update
Introduction
This request will update an existing SIP account.
When creating or updating a SIP account, you just specify the numbers that it should handle. Numbers the customer already has is assigned to the account, numbers that are available for purchase will be purchased (added to the current invoice) and for numbers that needs to be ported in from another telecom service provider, portings will be created. As a reply to the creation a list of created portings will be returned, so that you may use the porting API to set the requested porting date, create and send/download Power of attorney documents for the customer to sign and add users to notify when the porting progresses. Do note that if a number that has a porting is removed from the SIP account, the porting will be cancelled, unless other numbers are part of it.
When updating a SIP account, you do not need to send the full SIP account object. As little as a single property can be sent, so only send the properties you need to update, and the rest will be untouched.
Request
| URL | https://api.telecomx.dk/sip/ACCOUNT_ID | ||
|---|---|---|---|
| Method | POST | ||
| Access level | MANAGER or OWNER when user belongs to the customer (however MANAGER cannot purchase numbers or create portings). RESELLER if customer belongs to the reseller. ADMIN. |
||
| Param | ACCOUNT_ID | Id of the SIP account (24 hex-char string) | |
| Body | customer | Id | Id of customer the SIP account belongs to. |
| active | Boolean | True if account is enabled and working, false to block all. (ADMIN/RESELLER only) | |
| name | String | Human readable name of the SIP account, or the first number of the account. | |
| numbers | Array | Array of numbers that the account handles in E.164 format. | |
| highRate | Boolean | True if account can be used for calling high rated numbers. | |
| international | Boolean | True if account can be used for calling outside Denmark. | |
| address | Id | Address the SIP account belongs to (for 112/114 emergency routing). If not set, the customers primary address will be used. | |
| ratePlan | Id | Id of the SIP rate plan product this account should be invoiced by. | |
| parentSipAccount | Id | [optional] Id of another SIP account. If set, rating calls made on this account is made as if the calls were made on the other account. |
|
| pbx | Number | Id of hosted PBX cluster to use, null or 0 if not part of hosted PBX. | |
| notes | String | [optional] Notes about the SIP account, only visible to RESELLER and ADMIN. |
|
| custom | Object | [optional] Custom data that 3rd parties may append, max. 4Kb. |
|
| connection | String | Method for the SIP client to connect: IP_AUTH - Calls are sent to the fixed IP address and port, client must use authentication to initiate outbound calls, and can only do so from the fixed IP address. IP_AUTH_REG - Client must be at the fixed IP address, must register to receive calls and must use authentication to initiate outbound calls. IP - Calls are sent to the fixed IP address and port, and outbound calls must be made from the fixed IP address - no authentication is required (Lync mode). Requires ADMIN rights to set. COUNTRY_AUTH_REG - client must register to make and receive calls, and client must come from an IP address in one of the selected countries. |
|
| ipAddress | String | IP address the SIP client must originate from and calls are sent to if connection is not COUNTRY_AUTH_REG. | |
| port | Integer | Port that calls are sent to if connection is IP or IP_AUTH, default 5060. | |
| countries | String | Comma list of ISO3166 2 char country codes from where the SIP client may register, if connection is COUNTRY_AUTH_REG. | |
| clipSA | Boolean | True if SIP client may present any phone number, false if SIP client may only present the numbers in numbers. | |
| stripDkCountryCode | Boolean | True if +45 should be stripped before sending calls to the SIP client. | |
| prefixMobileOriginated | Boolean | True if calls from mobile device should be prefixed with 03 before sending it to the SIP client. | |
| failover | String | [optional] E.164 number or IP address or E.164@IP to redirect to when calls cannot be delivered to the sip client. |
|
| alwaysFailover | Boolean | [optional] True to always use the failover. |
|
| invoicedUntil | Date | [optional] [ADMIN only] The date the account has been invoiced until. On or after this date the account should be invoiced again for the next period, starting on this date. |
|
| defaultNumber | String | Default number for the account (E.164 format) - used as a-number if SIP client does not present a valid phone number. | |
| alwaysDefaultNumber | Boolean | If the default number must always be presented on outbound calls. | |
| alwaysSecretNumber | Boolean | If outbound calls must always be presented with secret number. | |
| usageBlock | Boolean | Set to false to remove a usage block in place. Cannot be set true and can only be used by RESELLER or ADMIN users. | |
| billingCustomer | ObjectID | Alternate customer to bill this SIP account to. | |
Please note that username and password cannot be set, they are auto-generated if needed (a security precaution), but they can be changed using the resetCredentials API. New account are also by default active, but can be changed with an update.
Request body example
{ customer: '1234567890ABCDEF12345678', name: 'Primary trunk CPH', numbers: ['+4570305050','+4570305051','+4570305052','+4580808080','+4578787878'], parentSipAccount: '123457890ABCDEF12345678', clipSA: true, stripDkCountryCode: true, prefixMobileOriginated: false }
Response
The response will be the newly created SIP account, if no errors occurred.
| Json object | ||
|---|---|---|
| _id | Id | Unique SIP account id. |
| customer | Id | Id of customer the SIP account belongs to. |
| active | Boolean | True if the account is active and can handle calls. |
| name | String | Human readable name of the SIP account, or the first number of the account. |
| type | String | Type of account - always 'SIP'. |
| numbers | Array | Array of numbers that the account handles in E.164 format. |
| highRate | Boolean | True if account can be used for calling high rated numbers. |
| international | Boolean | True if account can be used for calling outside Denmark. |
| address | Id | Address the SIP account belongs to (for 112/114 emergency routing). |
| ratePlan | Id | Id of the SIP rate plan product this account should be invoiced by. |
| newRatePlan | Id | If a new rateplan should be applied at end of month, this is the plan (cannot change in mid-month). |
| parentSipAccount | Id | Id of another SIP account. If set, rating calls made on this account is made as if the calls were made on the other account. |
| pbx | Number | Id of hosted PBX cluster to use, null or 0 if not part of hosted PBX. |
| notes | String | Notes about the SIP account, only visible to RESELLER and ADMIN. |
| custom | Object | Custom data that 3rd parties may append, max. 4Kb. |
| status | String | 'ON' if the SIP client is connected/reachable, 'OFF' if unreachable. |
| sipServer | String | IP address of the SIP server currently handling this SIP account. Only visible for ADMIN. |
| userAgent | String | The latest user agent string received from the SIP client. |
| contact | String | The latest registration contact string as received from the SIP client. |
| connection | String | Method for the SIP client to connect: IP_AUTH - Calls are sent to the fixed IP address and port, client must use authentication to initiate outbound calls, and can only do so from the fixed IP address. IP_AUTH_REG - Client must be at the fixed IP address, must register to receive calls and must use authentication to initiate outbound calls. IP - Calls are sent to the fixed IP address and port, and outbound calls must be made from the fixed IP address - no authentication is required (Lync mode). COUNTRY_AUTH_REG - client must register to make and receive calls, and client must come from an IP address in one of the selected countries. |
| username | String | 16 characters auto-generated string. Can only be changed used the resetCredentials API call. |
| password | String | 16 characters auto-generated string. Can only be changed used the resetCredentials API call. |
| ipAddress | String | IP address the SIP client must originate from and calls are sent to if connection is not COUNTRY_AUTH_REG. |
| port | Integer | Port that calls are sent to if connection is IP or IP_AUTH, default 5060. |
| countries | String | Comma list of ISO3166 2 char country codes from where the SIP client may register, if connection is COUNTRY_AUTH_REG. |
| clipSA | Boolean | True if SIP client may present any phone number, false if SIP client may only present the numbers in numbers. |
| stripDkCountryCode | Boolean | True if +45 should be stripped before sending calls to the SIP client. |
| prefixMobileOriginated | Boolean | True if calls from mobile device should be prefixed with 03 before sending it to the SIP client. |
| failover | String | E.164 number or IP address or E.164@IP to redirect to when calls cannot be delivered to the sip client. |
| alwaysFailover | Boolean | True to always use the failover. |
| invoicedUntil | Date | The date the account has been invoiced until. On or after this date the account should be invoiced again for the next period, starting on this date. |
| portings | Array | If the update resulted in portings being created, then this will hold a list of ids for the created portings. Omitted if no portings were created. |
| defaultNumber | String | Default number for the account (E.164 format). Used if the SIP client does not present a valid a-number. |
| alwaysDefaultNumber | Boolean | If the default number must always be presented on outbound calls. |
| alwaysSecretNumber | Boolean | If outbound calls must always be presented with secret number. |
| usageBlock | Boolean | True if highRate and international has been blocked due to high usage. Can only be unset by RESELLER or ADMIN users. |
Note that properties holding no value may be omitted from the object.
Example
{ _id: '1234567890ABCDEF12345678', customer: '1234567890ABCDEF12345678', active: true, name: 'Primary trunk CPH', type: 'SIP', numbers: ['+4570305050','+4570305051','+4570305052','+4580808080','+4578787878'], highRate: true, international: true, address: '1234567890ABCDEF12345678', ratePlan: '1234567890ABCDEF12345678', newRatePlan: null, parentSipAccount: '1234567890ABCDEF12345678', pbx: 0, notes: 'A note about the SIP account', custom: null, status: 'ON', sipServer: 1.2.3.4, userAgent: 'Asterisk 1.8.13', contact: 'fhrtu373utiu38r8@77.66.100.10:5060', connection: 'IP_AUTH_REG', username: 'fhrtu373utiu38r8', password: 'eh378gi2ufvhghug', ipAddress: '77.66.100.10', port: null, countries: null, clipSA: true, stripDkCountryCode: true, prefixMobileOriginated: false, failover: '+4588888888@77.66.100.123', alwaysFailover: false, invoicedUntil: '2014-01-01T00:00:00.000Z', defaultNumber: '+4570305050', alwaysDefaultNumber: false, alwaysSecretNumber: false }
Errors
| Error code | Message | Description |
|---|---|---|
| 400 | bad_request | SIP account not found in body of request |
| 400 | bad_request | SIP account id not found in request URI |
| 403 | access_denied | Insufficient access level |
| 403 | connection | Insufficient access level for choosing IP |
| 422 | name | Name is required |
| 422 | numbers[E.164Number] | The number is invalid |
| 422 | custom | Custom data too large, max 4Kb. |
| 422 | sipServer | SIP server is not valid |
| 422 | connection | Connection method is invalid |
| 422 | ipAddress | IP address is invalid |
| 422 | port | Port number is invalid (1024-65535 only) |
| 422 | countries | No countries specified for connection type that required countries |
| 422 | countries | Country code 'X' is not valid |
| 422 | failover | Failover is invalid - must be E.164 number or IP address or E.164@IP |
| 409 | numbers[E.164Number] | Number is in use on another SIP account |
| 409 | numbers[E.164Number] | Number is being ported to another SIP account |
| 409 | numbers[E.164Number] | Insufficient access level to purchase numbers |
| 409 | numbers[E.164Number] | The number is not available |
| 409 | numbers[E.164Number] | Insufficient access level to authorize porting of number |
| 409 | numbers[E.164Number] | Number cannot be used on a SIP account |
| 409 | numbers[E.164Number] | Number is invalid |
| 409 | numbers[E.164Number] | Number is in use on hosted PBX and cannot be removed (extension) |
| 409 | numbers[E.164Number] | Number is in use on hosted PBX and cannot be removed (trunk) |
| 409 | numbers[E.164Number] | Number is in use on hosted PBX and cannot be removed (pbx settings) |
| 404 | customer | Customer not found |
| 403 | customer | Customer is blocked |
| 404 | address | Address not found |
| 404 | ratePlan | Rate plan not found or not valid |
| 404 | newRatePlan | New rate plan not found or not valid |
| 404 | parentSipAccount | Parent SIP account not found |
| 409 | parentSipAccount | The SIP account cannot be a parent to itself |
| 409 | range | Cannot remove part of a range, must remove all numbers in range |
| 422 | defaultNumber | Number is invalid - must be E.164 number |
| 409 | defaultNumber | Number was not found in list of numbers on account |
| 409 | parentSipAccount | Cannot have a parent SIP account, when account itself is a parent |
| 422 | pbx | Pbx is outside the valid range |
| 422 | billingCustomer | Billing customer and parent SIP account can not both be set |
| 403 | usageBlock | Insufficent access level to remove usage blocking |
| 500 | internal_error | <Unspecified> |