User Tools

Site Tools


api:sip:account:update

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>
api/sip/account/update.txt · Last modified: 2021/04/08 11:38 by Joakim Andersen

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki