See also:
Shows arguments (and their syntax) that a specific function accepts.
| arg | required? | syntax | info |
|---|---|---|---|
func | Y | string | The name of the function you wish to query |
args | N | assoc | Sample arguments that you might otherwise send to your chosen function |
optfields | N | set:alias | A list of optional fields (that are not returned by default) to request in the returned data |
The name of the function you wish to query. This can be either dot separated or underscore separated,
eg telecoms.num.list
An assoc/object containing some test arguments.
This is useful when the function being queried has a variable-arg-definition. If you supply one of the control arguments that affects the argument definition, then you will see the argument definition that results. The vast majority of our API functions don't have variable arg definitions.
A list of additional fields to return. Note that not all of these are defined for every function; if defined they will be returned, but it is not an error if they do not - they simply won't be returned with the result data if that is the case.
The result can various sections/elements. Not all are applicable to every function.
arglist - the arguments the function accepts, their syntax and any dependenciesallow_undefined_fields - a boolean value; if present and true, the function will accept additional arguments not declared in the arglist section. Functions that do this are old legacy functions and not commonly used.alias - alternative names of arguments for backward compatability reasons (not returned by default)security - if present, lists type-hint information about an argument and restrictions on the scope of values (restrictions that can't be defined by syntax alone). Can also define somealtsyntax - for functions with variable-arg-definitions, this section indicates which arguments influence alternative argument syntax.arglistAn assoc/object keyed by argument name. The values are themselves assoc/objects which will comprise some or all of these parameters:
syntax (string) - a value indicating the format of the argumentbounds (assoc/object) - specifies limits on the value of the argumentdefault (type depends on argument) - the value that will be assumed if the argument is not supplieddefault_if (string; CSV of other argument names) - the default value will only be assumed only if one of these arguments is also supplieddefault_unless (string; CSV of other argument names) - the default value will only be assumed only if one of these arguments is NOT suppliedrequired (string)
- at least one argument with this required value must be supplied; if multiple arguments share the same required value,
supplying any one (or more) will satisfy the dependency
requires (string; CSV of other argument names)
- this takes several forms. In the simplest case, it shows the name of another argument that is also required if this
argument is specified. As a generic example, if the argument was "crisps" (potato chips for US residents), this might then
require a "flavour" argument in which case it would have the value "flavour".
If the specifying of this argument requires multiple additional arguments, then their names will be separated by commas (eg for crisps,
not only do you
need to specify the flavour, but do might also need to specify whether you want a regular bag or a party pack).
If there are several arguments that could satisfy the dependency whilst not all are required, then this parameter will contain a
string in the form n:otherarg1,otherarg2,otherarg3 where n is the number of additional arguments required, and otherarg1,
otherarg2 and otherarg3 are other arguments that will qualify. For example, for the value of 1:name,age,size
then you can supply any of name, age or size in order to satisfy the dependency; or if the value is
2:name,age,size then you can supply any two.
excludes - all arguments listed in the "excludes" list cannot be specified at the same time as this argumentexclusive - all arguments with this "exclusive" value are mutually exclusive from each other; you can only specify one in this exclusive groupdistinct_set - the argument takes a list of values but the values must be unique. If the same "distinct_set" value is shared with other arguments,
then not only can you not specify the same value twice in the set, but you also can't specify any given value in more than one of these arguments. For example,
if two arguments things_to_bring and things_to_leave both have "distinct_set"=>"things" then you cannot
put "toothbrush" into both arguments, nor can you leave or bring more than one toothbrush. Also note that the value of distinct_set can contain
multiple keywords (which will be comma separated). In these cases, the distinct set rules are evaluated for each keyword.
allow_null - the argument can be supplied with a NULL valueallow_null_in_list - the argument contains a list of values, and NULL is allowed as a valid value in the listdef - where the arg syntax is assoc or an array of assocs, def defines the syntax of that assoc (like a whole sub-arg section)
unsint - an unsigned integer, ie an integer value greater or equal to 0; can be supplied as a stringposint - a positive integer, ie an integer value greater or equal to 1; can be supplied as a stringsigint - a signed integer, ie any integer value, positive or negative; can be supplied as a stringfloat - a number that may optional contain a decimal point and additional digits after the point; can be supplied as a string but you cannot use scientific notationfloat.Xdp - same as float except that there must be precisely X decimal places supplied, eg "float.2dp" may be used to define an amount in pounds and penceboolean - a boolean value; any of the following values are considered valid: false, 0, "0", true, 1, "1"boolean - a true boolean value; any of the following values are considered valid: true, 1, "1"string - a generic string value; no specific formatting is requiredisodate - a date string in YYYY-MM-DD formatisotime - a datetime string in YYYY-MM-DD hh:mm:ss formatisomonth - a month string in YYYY-MM formattime - a 24 hour time string with optional seconds, so either HH:MM or HH:MM:SS formattimeHM - a 24 hour time string without seconds, so HH:MM formattimeHMS - a 24 hour time string with seconds, so HH:MM:SS formatemail - an email addressdomain - an Internet domain or host name, eg "google.com" or "www.example.com"ip_host - a valid IP address or Internet domain or host nameip4 - a valid IPv4 addressurl.http - a valid web URL, eg "https://www.google.com/search?q=sausages"arr - an array or assoc/objectTelNum(...flags) - a phone number in your own locale format or E.164 format (if using E.164 format it must start with a "+" character).
This doesn't have to be a complete number (ie can be just the starting digits) unless otherwise specified by the flags. Flags are not always present but if they are then
they will be represtented by a CSV of one or more of the following values:
complete - the value must be a complete phone number, not just the starting digitsnonPrem - must not be a premium rate number (eg UK numbers starting "09")hosted - must be a phone number hosted on our systemTelNumExt(...flags) - the same as TelNum except that the number can optionally have an extension defined, eg
a UK London number with an extension of 324 could be represented (if your locale is set to UK) as "02031231234,324" or "+442031231234,324" or "+442031231234;ext=324".
The same TelNum flags apply.
assoc - an assoc/object. Its definition would be returned in a "def" parameter; this would have the same
format as the main "syntax" section that lists the top level arguments.
You might also see argument syntax prefixed with list: or arr:, eg "list:posint" "arr:posint".
This then means that the argument should contain a list of, or array of, the datatype to the right of the colon. A "list" type argument can be given the values as either
a CSV string or an array of the values (it doesn't matter which) but an "arr" type argument MUST be given the values as an array. So,
"23,12,564,2324" and [23, 12, 564, 2324] could both be given to a "list" type argument, but only the latter could
be given to an "arr" type argument.
Some arguments will have bounds defined, which can limit the scope of the values. These will be in a "bounds" parameter. The format
is an assoc/object with one or more bounds defined. All defined bounds must be obeyed. These can be any of:
len.min - the length, when represented as a string, must be at least thislen.max - the length, when represented as a string, must not be greater than thisval.min - the minimum/lowest permitted value; evaluation is performed numerically for numeric types (even if you supply the number as a string) and alphabetically for string typesval.max - the maximum/highest permitted value; evaluation ... as for val.mincount.min - for list and array arguments, this is the fewest number of elements they may containcount.max - for list and array arguments, this is the greatest number of elements they may containcsvlen.min - the length of the list, when represented as a CSV string, must be at least thiscsvlen.max - the length of the list, when represented as a CSV string, must not be greater than this
Calling func.arg.list to describe its own arguments.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "func.arg.list",
"args" : {
"func" : "func.arg.list"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"arglist" : {
"func" : {
"required" : "func",
"syntax" : "string"
},
"optfields" : {
"default" : [],
"syntax" : "set:alias"
},
"args" : {
"default" : [],
"syntax" : "arr"
}
}
}
}
Here we can see three arguments in the arglist - args, func and optfields.
args argument: "syntax" : "arr" defines it as requiring an array value. This can be an assoc/object
or a plain array/list. There is nothing more specific defined. "default" : [] says that the default value supplied to the
function will be an empty array, so this is what will be passed in to the function unless you supply the argument yourself. There is no required
parameter (and it isn't required by any other argument) so the argument is optional.
func argument: "syntax" : "string" tells you that the argument takes a string value.
"required" : "func" tells you that at least one argument with the required parameter set to "func"
is required. As there are no other arguments with this, that means that this argument must be supplied (as there are no others that could satisfy
this requirement).
optfields argument: "syntax" : "set:alias" tells you that the argument takes a list of values from a
defined set. In this instance, the only possible value is alias but in future there could be others.
Requesting the arguments for whoami.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "func.arg.list",
"args" : {
"func" : "whoami"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"security" : {
"access" : "read"
},
"arglist" : {
"optfields" : {
"default" : [],
"syntax" : "set:env|env.loaded|apimode|permissions|billcompIDs_readable|billcompIDs_writable|url"
}
}
}
}
You can see from the response that this function takes just one argument, and that it is optional (as there is no "required" paramter).
The argument is defined as a set, which means there are specific values it can take, but unlike an enum argument,
the set type argument can be given several of these values, eg ["env","apimode","url"].
Requesting the arguments for timezone.list.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "func.arg.list",
"args" : {
"func" : "timezone.list"
}
}
JSON example response:
{
"results" : {
"arglist" : {
"prefix" : {
"syntax" : "string"
},
"match_fuzzy" : {
"syntax" : "string",
"exclusive" : "searchtype"
},
"browse" : {
"syntax" : "booleantrue",
"exclusive" : "searchtype"
},
"match_start" : {
"exclusive" : "searchtype",
"syntax" : "string"
}
},
"security" : {
"restrictions" : [],
"access" : "read"
}
},
"success" : 1
}
This shows 4 arguments, all optional. prefix takes a string value and is independent of the other arguments. match_start
and match_fuzzy both take string arguments as well, whereas browse can only be supplied as boolean true. Any of the following
values will be accepted as boolean true: true, 1, "1".
Three of the arguments have the exclusive parameter set, and all with the same value. This means that these arguments are mutually
exclusive from each other. You can supply only one of these.
Requesting the arguments for telecoms.zone.edit.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.zone.edit"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"arglist" : {
"parentID" : {
"distinct_set" : "parent",
"syntax" : "posint"
},
"locationIDs_include.del" : {
"excludes" : "locationIDs_include",
"syntax" : "list:posint",
"distinct_set" : "loc_in"
},
"locationIDs_include.add" : {
"syntax" : "list:posint",
"excludes" : "locationIDs_include",
"distinct_set" : "loc_add,loc_in"
},
"zoneID" : {
"required" : "zoneID",
"distinct_set" : "parent",
"syntax" : "posint"
},
"locationIDs_exclude" : {
"syntax" : "list:posint",
"distinct_set" : "loc_add"
},
"locationIDs_include" : {
"distinct_set" : "loc_add",
"syntax" : "list:posint"
},
"name" : {
"bounds" : {
"len.max" : 80,
"len.min" : 1
},
"syntax" : "string"
},
"locationIDs_exclude.add" : {
"excludes" : "locationIDs_exclude",
"syntax" : "list:posint",
"distinct_set" : "loc_add,loc_ex"
},
"locationIDs_exclude.del" : {
"distinct_set" : "loc_ex",
"excludes" : "locationIDs_exclude",
"syntax" : "list:posint"
},
"custID" : {
"default" : 283560,
"syntax" : "posint"
}
},
"security" : {
"restrictions" : {
"custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
},
"access" : "write"
}
}
}
name is an optional argument but if supplied must be a string from 1 to 80 characters in length.
zoneID is a required arg, though parentID is not. However, because both arguments have the same distinct_set
value (ie "parent"), you cannot put the same value into each of these arguments - they must differ.
There are a number of distinct sets:
loc_in - this is defined in args locationIDs_include.del and locationIDs_include.add so you cannot put the same value
into both of these arguments.
loc_add - this is defined in args locationIDs_include.add, locationIDs_exclude, locationIDs_include andlocationIDs_exclude.add
so any given value cannot appear in more than one of these.
loc_ex - this is defined in args locationIDs_exclude.add and locationIDs_exclude.del so you cannot put the same value in
both of these arguments.
Requesting the arguments for telecoms.telecaptcha.create.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.telecaptcha.create"
}
}
JSON example response:
{
"results" : {
"security" : {
"access" : "write",
"restrictions" : {
"custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
}
},
"arglist" : {
"entry_attempts" : {
"bounds" : {
"val.max" : 10,
"val.min" : 1
},
"syntax" : "posint"
},
"callbackURL" : {
"syntax" : "url.http",
"bounds" : {
"len.max" : 255
}
},
"number" : {
"required" : "number",
"syntax" : "TelNumExt(complete)"
},
"type" : {
"default" : "say",
"requires" : {
"read_dtmf" : "callbackURL",
"say" : "PIN"
},
"syntax" : "enum:say|read_dtmf"
},
"PIN" : {
"bounds" : {
"len.min" : 3,
"len.max" : 10
},
"required" : "PIN",
"syntax" : "unsint"
},
"callee_verify" : {
"syntax" : "booleantrue"
},
"cli" : {
"syntax" : "TelNum(complete,nonPrem)",
"required" : "cli"
},
"full_callback_data" : {
"syntax" : "boolean",
"default" : 0
},
"custID" : {
"default" : 283560,
"syntax" : "posint"
},
"secret_salt" : {
"syntax" : "string",
"requires" : "callbackURL",
"bounds" : {
"len.min" : 5,
"len.max" : 50
}
},
"callback_format" : {
"requires" : "callbackURL",
"syntax" : "enum:JSON|URLENC",
"default" : "JSON"
},
"ref" : {
"syntax" : "string",
"bounds" : {
"len.max" : 45
}
}
}
},
"success" : 1
}
Here, entry_attempts is defined as being a positive integer between 1 and 10 inclusive (because of the bounds definition).
callbackURL is a web URL with max length 255 characters; it can contain a query string.
number is a mandatory argument that must contain a complete phone number.
type can take EITHER the string value "say" OR "read_dtmf". If not specified, then
"say" will be assumed. If the value is "say" then the PIN arg is also required,
but if the value is "read_dtmf" then the callbackURL arg is required.
secret_salt is an optional argument taking a string value of between 5 and 50 characters, but if specified then callbackURL
must also be provided.
callback_format can take EITHER the string value "JSON" OR "URLENC". If not specified, then
"JSON" will be assumed. The callbackURL arg is required if this arg is given, regardless of its value.
cliis required and must be a full phone number ("complete" flag) and cannot be a premium rate number ("nonPrem" flag).
Requesting the arguments for telecoms.callback.create.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.callback.create"
}
}
JSON example response:
{
"results" : {
"arglist" : {
"max_deferrals" : {
"syntax" : "unsint",
"bounds" : {
"val.max" : 50
}
},
"destnumber2" : {
"syntax" : "TelNumExt(complete,nonPrem)",
"required" : "party2",
"exclusive" : "party2"
},
"call_deferred_soundclipURL" : {
"syntax" : "url.http"
},
"party1" : {
"required" : "party1",
"exclusive" : "party1",
"def" : {
"arglist" : {
"presentCLI" : {
"syntax" : "TelNum(nonPrem)"
},
"route_as" : {
"syntax" : "TelNum()",
"exclusive" : "dest"
},
"sipargs" : {
"exclusive" : "dest",
"syntax" : "assoc",
"def" : {
"arglist" : {
"ext.pre" : {
"syntax" : "string",
"excludes" : "ext"
},
"ext_format" : {
"default" : "e164",
"default_unless" : "ext",
"syntax" : "enum:uk|ukhybrid|e164|e164bare",
"excludes" : "ext"
},
"pai_name" : {
"syntax" : "string",
"requires" : "pai_number"
},
"auth_realm" : {
"bounds" : {
"len.max" : 40
},
"syntax" : "string",
"requires" : "auth_user"
},
"port" : {
"syntax" : "posint",
"bounds" : {
"val.max" : "65535"
}
},
"ext.suf" : {
"excludes" : "ext",
"syntax" : "string"
},
"auth_user" : {
"bounds" : {
"len.max" : 40
},
"requires" : "auth_pass",
"syntax" : "string"
},
"ext" : {
"syntax" : "string"
},
"ppi_name" : {
"syntax" : "string",
"requires" : "ppi_number"
},
"auth_pass" : {
"syntax" : "string",
"requires" : "auth_user",
"bounds" : {
"len.max" : 80
}
},
"pai_number" : {
"syntax" : "TelNum(complete,nonPrem,owned)"
},
"host" : {
"required" : "host",
"syntax" : "ip_host"
},
"cli_format" : {
"syntax" : "enum:uk|ukhybrid|e164|e164bare"
},
"ppi_number" : {
"syntax" : "TelNum(complete,nonPrem,owned)"
}
},
"security" : {
"access" : "read"
}
}
},
"daypartingID" : {
"syntax" : "posint",
"exclusive" : "dest"
},
"whisper_soundclipID" : {
"syntax" : "posint"
},
"soundclipID" : {
"excludes" : "destnumber,route_as,routeplanID,daypartingID,mailboxID",
"syntax" : "posint"
},
"routeplanID" : {
"syntax" : "posint",
"exclusive" : "dest"
},
"destnumber" : {
"syntax" : "TelNumExt(complete)",
"exclusive" : "dest"
},
"mailboxID" : {
"syntax" : "posint",
"exclusive" : "dest"
},
"callee_verify" : {
"def" : {
"arglist" : {
"default_action" : {
"default" : "reject",
"syntax" : "enum:accept|defer|reject"
},
"prompt_soundclipURL" : {
"syntax" : "url.http"
},
"timeout_accept_soundclipID" : {
"syntax" : "posint"
},
"prompt_soundclipID" : {
"syntax" : "posint"
},
"acceptkeys" : {
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"distinct_set" : "userkeys",
"requires" : "rejectkeys",
"bounds" : {
"count.min" : 1
}
},
"timeout_retry" : {
"syntax" : "posint"
},
"timeout_reject_soundclipURL" : {
"syntax" : "url.http"
},
"max_retries" : {
"bounds" : {
"val.max" : 50
},
"syntax" : "unsint"
},
"simul_whisper_defer_soundclipID" : {
"syntax" : "posint"
},
"timeout_defer_soundclipURL" : {
"syntax" : "url.http"
},
"timeout_absolute" : {
"syntax" : "posint"
},
"timeout_accept_soundclipURL" : {
"syntax" : "url.http"
},
"simul_whisper_reject_soundclipID" : {
"syntax" : "posint"
},
"simul_whisper_defer_soundclipURL" : {
"syntax" : "url.http"
},
"timeout_durs_include_prompt" : {
"syntax" : "boolean"
},
"rejectkeys" : {
"bounds" : {
"count.min" : 1
},
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"distinct_set" : "userkeys",
"requires" : "acceptkeys"
},
"timeout_reject_soundclipID" : {
"syntax" : "posint"
},
"timeout_initial" : {
"syntax" : "posint"
},
"deferkeys" : {
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"distinct_set" : "userkeys",
"requires" : "acceptkeys",
"bounds" : {
"count.min" : 1
}
},
"timeout_defer_soundclipID" : {
"syntax" : "posint"
},
"simul_whisper_reject_soundclipURL" : {
"syntax" : "url.http"
}
}
},
"syntax" : "assoc"
},
"dest_type" : {
"syntax" : "enum:number|mirror|alias|routeplan|dayparting|sip|voicemail|announcement",
"requires" : {
"announcement" : "1:soundclipURL,soundclipID",
"sip" : "sipargs",
"dayparting" : "daypartID",
"number" : "destnumber",
"routeplan" : "routeplanID",
"mirror" : "route_as",
"voicemail" : "mailboxID",
"alias" : "route_as"
},
"required" : "dest_type"
},
"whisper_soundclipURL" : {
"syntax" : "url.http"
},
"soundclipURL" : {
"syntax" : "url.http",
"exclusive" : "dest"
}
}
},
"syntax" : "assoc"
},
"defer_dur" : {
"bounds" : {
"val.max" : 515855450
},
"syntax" : "posint"
},
"deferrals_exceeded_soundclipURL" : {
"syntax" : "url.http"
},
"presentCLI" : {
"syntax" : "TelNum(nonPrem)"
},
"callrec_stereo" : {
"syntax" : "boolean",
"requires" : "callrec_party"
},
"party2" : {
"required" : "party2",
"exclusive" : "party2",
"def" : {
"arglist" : {
"whisper_soundclipURL" : {
"syntax" : "url.http"
},
"soundclipURL" : {
"syntax" : "url.http",
"exclusive" : "dest"
},
"dest_type" : {
"required" : "dest_type",
"requires" : {
"announcement" : "1:soundclipURL,soundclipID",
"dayparting" : "daypartID",
"sip" : "sipargs",
"number" : "destnumber",
"routeplan" : "routeplanID",
"mirror" : "route_as",
"voicemail" : "mailboxID",
"alias" : "route_as"
},
"syntax" : "enum:number|mirror|alias|routeplan|dayparting|sip|voicemail|announcement"
},
"callee_verify" : {
"syntax" : "assoc",
"def" : {
"arglist" : {
"timeout_reject_soundclipURL" : {
"syntax" : "url.http"
},
"max_retries" : {
"bounds" : {
"val.max" : 50
},
"syntax" : "unsint"
},
"timeout_retry" : {
"syntax" : "posint"
},
"acceptkeys" : {
"distinct_set" : "userkeys",
"requires" : "rejectkeys",
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"bounds" : {
"count.min" : 1
}
},
"timeout_accept_soundclipID" : {
"syntax" : "posint"
},
"prompt_soundclipURL" : {
"syntax" : "url.http"
},
"prompt_soundclipID" : {
"syntax" : "posint"
},
"default_action" : {
"syntax" : "enum:accept|defer|reject",
"default" : "reject"
},
"timeout_absolute" : {
"syntax" : "posint"
},
"simul_whisper_defer_soundclipID" : {
"syntax" : "posint"
},
"timeout_defer_soundclipURL" : {
"syntax" : "url.http"
},
"deferkeys" : {
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"requires" : "acceptkeys",
"distinct_set" : "userkeys",
"bounds" : {
"count.min" : 1
}
},
"timeout_initial" : {
"syntax" : "posint"
},
"timeout_reject_soundclipID" : {
"syntax" : "posint"
},
"timeout_durs_include_prompt" : {
"syntax" : "boolean"
},
"rejectkeys" : {
"syntax" : "set:0|1|2|3|4|5|6|7|8|9|*|#",
"distinct_set" : "userkeys",
"requires" : "acceptkeys",
"bounds" : {
"count.min" : 1
}
},
"simul_whisper_defer_soundclipURL" : {
"syntax" : "url.http"
},
"simul_whisper_reject_soundclipID" : {
"syntax" : "posint"
},
"timeout_accept_soundclipURL" : {
"syntax" : "url.http"
},
"simul_whisper_reject_soundclipURL" : {
"syntax" : "url.http"
},
"timeout_defer_soundclipID" : {
"syntax" : "posint"
}
}
}
},
"destnumber" : {
"exclusive" : "dest",
"syntax" : "TelNumExt(complete)"
},
"mailboxID" : {
"syntax" : "posint",
"exclusive" : "dest"
},
"soundclipID" : {
"excludes" : "destnumber,route_as,routeplanID,daypartingID,mailboxID",
"syntax" : "posint"
},
"routeplanID" : {
"syntax" : "posint",
"exclusive" : "dest"
},
"whisper_soundclipID" : {
"syntax" : "posint"
},
"daypartingID" : {
"exclusive" : "dest",
"syntax" : "posint"
},
"sipargs" : {
"def" : {
"arglist" : {
"ppi_number" : {
"syntax" : "TelNum(complete,nonPrem,owned)"
},
"pai_number" : {
"syntax" : "TelNum(complete,nonPrem,owned)"
},
"auth_pass" : {
"requires" : "auth_user",
"syntax" : "string",
"bounds" : {
"len.max" : 80
}
},
"host" : {
"syntax" : "ip_host",
"required" : "host"
},
"cli_format" : {
"syntax" : "enum:uk|ukhybrid|e164|e164bare"
},
"ext" : {
"syntax" : "string"
},
"ppi_name" : {
"syntax" : "string",
"requires" : "ppi_number"
},
"ext.suf" : {
"syntax" : "string",
"excludes" : "ext"
},
"auth_user" : {
"syntax" : "string",
"requires" : "auth_pass",
"bounds" : {
"len.max" : 40
}
},
"auth_realm" : {
"requires" : "auth_user",
"syntax" : "string",
"bounds" : {
"len.max" : 40
}
},
"port" : {
"syntax" : "posint",
"bounds" : {
"val.max" : "65535"
}
},
"ext_format" : {
"default_unless" : "ext",
"syntax" : "enum:uk|ukhybrid|e164|e164bare",
"excludes" : "ext",
"default" : "e164"
},
"pai_name" : {
"syntax" : "string",
"requires" : "pai_number"
},
"ext.pre" : {
"syntax" : "string",
"excludes" : "ext"
}
},
"security" : {
"access" : "read"
}
},
"syntax" : "assoc",
"exclusive" : "dest"
},
"route_as" : {
"syntax" : "TelNum()",
"exclusive" : "dest"
},
"presentCLI" : {
"syntax" : "TelNum(nonPrem)"
}
}
},
"syntax" : "assoc"
},
"callrec_party" : {
"syntax" : "posint",
"bounds" : {
"val.min" : 1,
"val.max" : 2
}
},
"callrec_emailsubj_template" : {
"syntax" : "string",
"requires" : "callrec_mailto",
"bounds" : {
"len.max" : 127
}
},
"call_deferred_soundclipID" : {
"syntax" : "posint"
},
"callrec_mailto" : {
"syntax" : "list:email",
"requires" : "callrec_party",
"bounds" : {
"count.min" : 1
}
},
"destnumber1" : {
"exclusive" : "party1",
"required" : "party1",
"syntax" : "TelNumExt(complete,nonPrem)"
},
"deferrals_exceeded_soundclipID" : {
"syntax" : "posint"
},
"ref" : {
"bounds" : {
"len.max" : 45,
"len.min" : 0
},
"syntax" : "string"
},
"callrec_audio_format" : {
"syntax" : "enum:mp3|wav",
"requires" : "callrec_party"
},
"custID" : {
"default" : 283560,
"syntax" : "posint"
},
"callrec_mailfrom" : {
"syntax" : "email",
"requires" : "callrec_mailto",
"bounds" : {
"count.min" : 1
}
}
},
"security" : {
"access" : "write",
"restrictions" : {
"custID" : {
"scope" : "self/descendant",
"type" : "custID"
}
}
}
},
"success" : 1
}
Here's an example where a few of the args have assoc types with their own sub-definition, nested several levels.
Firstly, the simple version is to use destnumber1 and destnumber2, but if (for example) the first leg of the callback is to go to something
more complex than a single destination number, then it is necessary to define party1 instead of destnumber1. The same is true with regard
to using party2 instead of destnumber2 if the second leg of the callback is not to go to a single phone number. The syntax for
party1 and party2 is the same so for the purposes of discussion there is no need to describe both.
Because both destnumber1 and party1 are defined with "required" : "party1", then one of these arguments
is required. Because they both have the same string value to the "required" parameter, they are treated as a a group and supplying either one will
satisfy the requirement. The fact that the value matches one of the arg names is irrelevant - it could be "stegosaurus" and still work the same.
Because they also both have "exclusive" : "party1", they are part of the same "exclusive" group, which means that they
also are mutually exclusive with each other. This means that you must specify either destnumber1 or party1, but you may not specify both.
The party1 arg is defined as "assoc", so the def parameter defines what it may contain, using the exact same rules
as for the main arguments. This means that within def you must look for arglist to find the names of the elements that will be accepted.
So, within the party1 assoc arg, dest_type is a required sub-argument, and then depending on what value that has, different additional
sub-arguments are required, eg if dest_type is "routeplan", then routeplanID is then required, or if dest_type
is "sip", then sipargs is required.
Within party1/sipargs there is net another assoc definition defining a third level. So all in all, you may see part of the arguments to this function
specified as
"args" : {
"max_deferrals" : 5,
"party1" : {
"dest_type" : "sip",
"sipargs" : {
"auth_user" : "fredbloggs",
"auth_pass" : "nlmnqewqemWEQRWER",
"ext" : "442031231234",
"host" : "mysip.com"
},
.
.
.
}
.
.
.
}
Requesting the arguments for telecoms.cart.checkout.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.cart.checkout"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"altsyntax" : {
"pay_method" : [
"ifval" : [
"interactive",
"stored_card",
"after_invoice"
]
]
},
"security" : {
"restrictions" : {
"custID" : {
"type" : "custID",
"scope" : "self/descendant"
},
"supplier_custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
},
"access" : "write"
},
"arglist" : {
"custID" : {
"default" : 283560,
"syntax" : "posint"
},
"supplier_custID" : {
"syntax" : "posint"
},
"cartID" : {
"required" : "cartID",
"syntax" : "posint"
},
"pay_method" : {
"syntax" : "enum:interactive|stored_card|after_invoice",
"required" : "pay_method"
}
}
}
}
The main thing to note in the response here is that there's an altsyntax section which says there's an "ifval" rule on the
pay_methhod argument; the values listed (in this example, "interactive", "stored_card" and "invoice")
show the values that make a difference. This means that depending on what value that argument has, there could be a change of definition of the other existing
arguments, and/or some additional arguments.
Given that pay_method is an enum field with only three possible values, it's easy to see what else might be required by re-querying whilst supplying
the various values of that as a test argument.
With pay_method being "stored_card":
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.cart.checkout",
"args" : {
"pay_method" : "stored_card"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"altsyntax" : {
"pay_method" : [
"ifval"
]
},
"arglist" : {
"supplier_custID" : {
"syntax" : "posint"
},
"pay_method" : {
"syntax" : "enum:interactive|stored_card|after_invoice",
"required" : "pay_method"
},
"cartID" : {
"required" : "cartID",
"syntax" : "posint"
},
"paymentcardID" : {
"required" : "paymentcardID",
"syntax" : "posint"
},
"custID" : {
"syntax" : "posint",
"default" : 283560
}
},
"security" : {
"restrictions" : {
"supplier_custID" : {
"scope" : "self/descendant",
"type" : "custID"
},
"custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
},
"access" : "write"
}
}
}
Here you can see that by supplying "stored_card" in the pay_method arg, then paymentcardID becomes a required
argument, which makes sense because if you're going to be paying with a stored card then the system is going to know which one to use.
You would find that if you called the telecoms.cart.checkout function and specified "stored_card" as the
value for pay_method but did not provide the paymentcardID argument, the API would respond with an error that paymentcardID
was required.
With pay_method being "after_invoice":
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.cart.checkout",
"args" : {
"pay_method" : "after_invoice"
}
}
JSON example response:
{
"results" : {
"arglist" : {
"supplier_custID" : {
"syntax" : "posint"
},
"pay_method" : {
"syntax" : "enum:interactive|stored_card|after_invoice",
"required" : "pay_method"
},
"custID" : {
"syntax" : "posint",
"default" : 283560
},
"cartID" : {
"required" : "cartID",
"syntax" : "posint"
}
},
"altsyntax" : {
"pay_method" : [
"ifval"
]
},
"security" : {
"access" : "write",
"restrictions" : {
"custID" : {
"type" : "custID",
"scope" : "self/descendant"
},
"supplier_custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
}
}
},
"success" : 1
}
The pay_method of "after_invoice" does not define any new arguments, as can be seen here by the fact that the arg list
looks the same as it did without specifying pay_method at all.
With pay_method being "interactive":
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.zone.list",
"args" : {
"func" : "telecoms.cart.checkout",
"args" : {
"pay_method" : "interactive"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"security" : {
"access" : "write",
"restrictions" : {
"custID" : {
"scope" : "self/descendant",
"type" : "custID"
},
"supplier_custID" : {
"type" : "custID",
"scope" : "self/descendant"
}
}
},
"arglist" : {
"deliveryAddress2" : {
"syntax" : "string",
"requires" : "deliveryCity",
"bounds" : {
"len.max" : 100
}
},
"storeCard" : {
"exclusive" : "paymentcardID",
"syntax" : "boolean"
},
"default" : {
"requires" : "storeCard",
"syntax" : "boolean"
},
"deliveryPostcode" : {
"bounds" : {
"len.max" : 10
},
"requires" : "deliveryCountry",
"syntax" : "string"
},
"abortURL" : {
"required" : "abortURL",
"bounds" : {
"len.max" : 1024,
"len.min" : 0
},
"syntax" : "url.http"
},
"cartID" : {
"required" : "cartID",
"syntax" : "posint"
},
"billingAddress2" : {
"requires" : "billingCity",
"syntax" : "string",
"bounds" : {
"len.max" : 100
}
},
"deliveryCity" : {
"bounds" : {
"len.max" : 40
},
"requires" : "deliveryPostcode",
"syntax" : "string"
},
"deliveryCountry" : {
"syntax" : "string",
"requires" : "deliveryFirstnames",
"bounds" : {
"len.max" : 2,
"len.min" : 2
}
},
"supplier_custID" : {
"syntax" : "posint"
},
"currency" : {
"syntax" : "enum:GBP",
"required" : "currency"
},
"orderID" : {
"syntax" : "unsint",
"bounds" : {
"val.max" : 4294967295,
"len.max" : 10
},
"required" : "orderID"
},
"deliveryFirstnames" : {
"syntax" : "string",
"requires" : "deliverySurname",
"bounds" : {
"len.max" : 20
}
},
"billingState" : {
"bounds" : {
"len.max" : 2,
"len.min" : 2
},
"syntax" : "string",
"requires" : "billingFirstnames"
},
"systemName" : {
"bounds" : {
"len.max" : 10
},
"required" : "systemName",
"syntax" : "string"
},
"successURL" : {
"bounds" : {
"len.max" : 1024,
"len.min" : 0
},
"required" : "successURL",
"syntax" : "url.http"
},
"raisePayment" : {
"syntax" : "boolean",
"default" : 1
},
"callbackURL" : {
"bounds" : {
"len.min" : 0,
"len.max" : 1024
},
"syntax" : "url.http"
},
"billingCountry" : {
"bounds" : {
"len.max" : 2,
"len.min" : 2
},
"requires" : "billingFirstnames",
"syntax" : "string"
},
"label" : {
"requires" : "storeCard",
"syntax" : "string",
"bounds" : {
"len.max" : 15
}
},
"deliverySurname" : {
"bounds" : {
"len.max" : 20
},
"syntax" : "string",
"requires" : "deliveryAddress1"
},
"billingCity" : {
"requires" : "billingPostcode",
"syntax" : "string",
"bounds" : {
"len.max" : 40,
"len.min" : 1
}
},
"deliveryAddress1" : {
"bounds" : {
"len.max" : 100
},
"syntax" : "string",
"requires" : "deliveryCity"
},
"description" : {
"bounds" : {
"len.min" : 1,
"len.max" : 100
},
"default" : "(none)",
"syntax" : "string"
},
"pay_method" : {
"syntax" : "enum:interactive|stored_card|after_invoice",
"required" : "pay_method"
},
"billingPostcode" : {
"syntax" : "string",
"requires" : "billingCountry",
"bounds" : {
"len.max" : 10,
"len.min" : 1
}
},
"billingAddress1" : {
"bounds" : {
"len.max" : 100,
"len.min" : 1
},
"requires" : "billingCity",
"syntax" : "string"
},
"billingFirstnames" : {
"bounds" : {
"len.max" : 20,
"len.min" : 1
},
"required" : "payerInfo",
"requires" : "billingSurname",
"syntax" : "string"
},
"AVSCV2" : {
"bounds" : {
"val.max" : 3
},
"default" : 0,
"syntax" : "unsint"
},
"custID" : {
"default" : 283560,
"syntax" : "posint"
},
"billingSurname" : {
"bounds" : {
"len.min" : 1,
"len.max" : 20
},
"requires" : "billingAddress1",
"syntax" : "string"
},
"accountType" : {
"syntax" : "enum:E|M|C"
},
"3DSecure" : {
"bounds" : {
"val.max" : 3
},
"default" : 0,
"syntax" : "unsint"
}
},
"altsyntax" : {
"pay_method" : [
"ifval"
]
}
}
}
Whoa! Using the "interactive" value for pay_method suddenly defines a large number of additional arguments.