API : SIP Account List

Introduction

This request will return the list of SIP accounts (SIP trunks) that belongs to a customer.

Request

URL	https://api.telecomx.dk/sip
Method	GET
Access level	VIEWER, MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller or a sub reseller. ADMIN.
Query	customer	`[optional]` Id of the customer the SIP accounts belongs to, defaults to users own customer.
	reseller	`[optional]` Id of the reseller whose customers to list accounts for.
	offset	`[optional]` Index of the first SIP account to return, default 0.
	limit	`[optional]` The number of SIP accounts to return, default 100, min 1, max 500.
	filter	`[optional]` To filter the SIP accounts, this can be used. Name, numbers IP address, username and notes will be searched.
	full	`[optional]` If true, complete SIP account object will be returned instead of the condensed version.
	up	`[optional]` If true, return only accounts that are up. If false, return only accounts that are down. If not set, return accounts regardless of up/down status.

Query examples

https://api.telecomx.dk/sip?customer=1234567890ABCDEF12345678
https://api.telecomx.dk/sip?customer=1234567890ABCDEF12345678&filter=80808080&offset=10&limit=25&full=true

Response

JSON object
offset	Index of the first SIP account returned.
limit	Number of SIP accounts to return. Note that the actual number of SIP accounts returned may be lower.
total	Number of SIP accounts that can be returned when offset and limit is not considered. This is to be used for paging through the data.
sipAccounts	Array of SIP accounts, see definition below

SIP account object (JSON)
_id	Id	Unique SIP account id.
active	Boolean	True if the account is active and can handle calls.
name	String	Descriptive name for the SIP account (e.g. 'Primary trunk CPH') or perhaps a phone number.
numbers	Array	Array of string with the phone numbers (E.164 format) this SIP account handles.
ratePlan	Id	Id of the rate plan used for billing.
ratePlanName	String	Name/description of the rate plan.
status	String	'ON' if the SIP client is connected/reachable, 'OFF' if unreachable.
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, cannot be changed.
ipAddress	String	IP address the SIP client must originate from and calls are sent to if connection is not COUNTRY_AUTH_REG.
failover	String	Phone number in E.164 format or IP address or E.164@IP to redirect calls to if the SIP client cannot be reached.
alwaysFailover	Boolean	True if failover is always used.
usageBlock	Boolean	True if usage blocking is in effect and highrate and international calls are blocked due to high usage or suspicion of fraud.
pbx	Number	Id of hosted PBX cluster to use, null or 0 if not part of hosted PBX.
voiceUsage	Array	List of voice usage for the last 12 months.
voiceUsage[].date	Date	The date the usage relates to.
voiceUsage[].secsOutHomeland	Number	Number of seconds called out in region homeland.

SIP account object if full=true (JSON)
_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.
usageBlock	Boolean	True if highRate and international has been blocked due to high usage. Can only be unset by RESELLER or ADMIN users.
defaultNumber	String	Default number to present when a client presents an invalid a-number on an outbound call. Automatically set if not specified, and must be one of the numbers on the SIP account.
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.
billingCustomer	ObjectID	Alternate customer to bill this SIP account to.

Note that properties holding no value may be omitted from the object.

If the SIP trunk is a PBX trunk, then the following properties will not be included: status, sipServer, userAgent, contact, connection, username, password, ipAddress, port, countries, clipSA, stripDkCountryCode, prefixMobileOriginated, failover, alwaysFailover, defaultNumber.

Example - normal

{
  offset: 10,
  limit: 20,
  total: 123,
  sipAccounts:
  [
    {
      _id: '1234567890ABCDEF12345678',
      active: true,
      name: 'Primary trunk CPH',
      numbers: ['+4570305050','+4570305051','+4570305052','+4580808080'],
      ratePlan: '1234567890ABCDEF12345678',
      ratePlanName: 'Standard SIP account',
      status: 'ON',
      connection: 'IP_AUTH_REG',
      username: 'fhrtu373utiu38r8',
      ipAddress: '77.66.100.10',
      failover: '+4588888888@77.66.100.123',
      usageBlock: false,
      defaultNumber: '+4570305050'
    },
    ...
  ]
}

Example - full=true

{
  offset: 10,
  limit: 20,
  total: 123,
  sipAccounts:
  [
    {
      _id: '1234567890ABCDEF12345678',
      customer: '1234567890ABCDEF12345678',
      active: true,
      name: 'Primary trunk CPH',
      type: 'SIP',
      numbers: ['+4570305050','+4570305051','+4570305052','+4580808080'],
      highRate: true,
      international: true,
      address: '1234567890ABCDEF12345678',
      ratePlan: '1234567890ABCDEF12345678',
      newRatePlan: null,
      parentSipAccount: null,
      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: true,
      failover: '+4588888888@77.66.100.123',
      alwaysFailover: false,
      invoicedUntil: '2014-01-01T00:00:00.000Z',
      defaultNumber: '+4580808080',
      alwaysDefaultNumber: false,
      alwaysSecretNumber: false
    },
    ...
  ]
}

Errors

Error code	Message	Description
400	customer	Customer not found in arguments
403	access_denied	Insufficient access level - no access to the customer.

WIKI

Table of Contents