Skip to content

Middleware API

Jump to bottom
Laura Estefanía Corvalán edited this page Aug 6, 2015 · 50 revisions

Complete list

All entry points are relative to /api:

Errors

Very often (precisely when generic errors can be returned), the API will return a status code 400 (or other error code statuses) and the following json format:

  {
    "error": {
      "payload": "account_id,amount,description",
      "description": "missing_parameters"
    }
  }

Be prepared for those messages!

/version

Description

Returns the version number of the middleware and the switch.

Methods

  • GET

Returns

  • 200

Example

$ curl -k https://api.connexo.net/version

{
  "middleware_version": "1",
  "switch_version": "1",
  "webapp_version": "1"
}

In case of errors communicating with the switch, the switch_version field is "error"

/simulate

Description

Simulates a call, returning an array of json calls (1 per route found to terminate the call, see the Call Json Format).

Methods

  • GET

Returns

  • 200

Required Arguments

  • trunk: Trunk ID.
  • from: E164 number. MUST be an existant DID in the system.
  • to: Dialed number, as that particular subscriber would dial (i.e: probably not in E164).
  • call_length: Duration in seconds for the simulated call.

Example

$ curl -k "https://api.connexo.net/simulate? \
       "trunk=1 \
       "from=12035551234 \
       "&to=00154115551122 \
       "&call_length=15"

/cdr

Description

It will return approximately 200 cdr records each time for all the accounts of the customer.
For each record returns the following fields:

  • ani_e164
  • dnis_e164
  • ani_src
  • dnis_src
  • ani_dst
  • dnis_dst
  • date_created
  • id
  • bill_time
  • dial_status
  • trunk_name_dst
  • trunk_ip_dst

Methods

  • GET

Returns

  • 200

Required Arguments

  • from: Date. Format: YYYY-MM-DDTHH:MM:SS
  • scroll_id: Optional.

Example

$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS"

Response Example

{
  "total": 0, 
  "total_rows": 0, 
  "rows": [], 
  "scroll_id": "c2NhbjswOzE7dG90YWxfaGl0czowOw=="
}

/organization/invoices/generate

Description

Creates invoices for postpaid accounts

Methods

  • POST

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 204
  • 400 (if an error occurs while trying to save an invoice or trying to upload the invoice file to amazon s3)

Required Arguments

  • orgz_id: Organization ID.

Example (application/x-www-form-urlencoded)

$ curl -k -v -d "orgz_id=1" https://api.connexo.net/organization/invoices/generate

Example (application/json)

$ curl -k -v -d@req.json -H "content-type: application/json" https://api.connexo.net/organization/invoices/generate

Where req.json is something like this:

  {
    "orgz_id": "1"
  }

/organization/accounts/recharge

Description

Recharges subscriber accounts via authorize net merchant if auto-recharge feature is enabled

Methods

  • POST

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 204
  • 400 (if an error occurs while trying to recharge account)

Required Arguments

  • orgz_id: Organization ID.

Example (application/x-www-form-urlencoded)

$ curl -k -v -d "orgz_id=1" https://api.connexo.net/organization/accounts/recharge

Example (application/json)

$ curl -k -v -d@req.json -H "content-type: application/json" https://api.connexo.net/organization/accounts/recharge

Where req.json is something like this:

  {
    "orgz_id": "1"
  }

/subscriber/list

Description

Returns the complete list of all subscribers.

Methods

  • GET

Optional Arguments

  • include_accounts: No values. If present, will also return the info for the accounts for each subscriber.

Returns

  • 200

Example

$ curl -k "https://api.connexo.net/subscriber/list"

  [
    {
      "id": 1,
      "name": "Vip2Phone",
      "contact_name": "",
      "created": "2013-05-29T09:40:59-03:00"
    }
  ]

Example with accounts

$ curl -k "https://api.connexo.net/subscriber/list?include_accounts"

  [
    {
      "id": 1,
      "name": "Vip2Phone",
      "contact_name": "",
      "created": "2013-05-29T09:40:59-03:00",
      "accounts": [
        {
          "id": 6,
          "funds": "100.0",
          "credit": "0.0",
          "subscriber_id": 1,
          "plan_id": 5,
          "postpaid": false,
          "description": "",
          "created": "2014-10-07T13:36:07Z",
          "settings": {
            
          },
          "enabled": true
        }
      ]
    }
  ]

/subscriber/:subscriber_id/accounts

Description

Returns the complete list of all the accounts known for the given subscriber.

Methods

  • GET

Returns

  • 200
  • 404 (on unknown or invalid subcriber_id)

Required Arguments

  • subscriber_id: Integer > 0

Example

$ curl -k "https://api.connexo.net/subscriber/1/accounts"

  [
    {
      "id": 1,
      "funds": "100000.0",
      "credit": "0.0",
      "subscriber_id": 1,
      "plan_id": 1,
      "postpaid": true,
      "description": "account description"
      "created": "2013-05-29T09:40:59-03:00"
    }
  ]

/subscriber/recharge

Description

Adds a sum of money to the given account.

Methods

  • POST

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 204
  • 400 (on invalid account_id or invalid arguments)

Required Arguments

  • account_id: Integer > 0.
  • amount: String, represents a float, like "12.65".
  • description: String. A message giving additional information about this event.

Example (application/x-www-form-urlencoded)

$ curl -k -v -d "account_id=1&amount=12.33&description=here is some money" https://api.connexo.net/subscriber/recharge

Example (application/json)

$ curl -k -v -d@req.json -H "content-type: application/json" https://api.connexo.net/subscriber/recharge

Where req.json is something like this:

  {
    "account_id": 1,
    "amount": "12.33",
    "description": "here is some money"
  }

/plan/list

Description

Returns the complete list of all plans.

Methods

  • GET

Returns

  • 200

Example

$ curl -k "https://api.connexo.net/plan/list"

  [
    {
      "id": 1,
      "name": "Regular",
      "type": 0,
      "dids": 1000,
      "charge_incoming": 1,
      "allow_incoming": 1,
      "created": "2013-06-07T20:39:35-03:00"
     }
  ]

/plan

Description

Creates a plan.

Methods

  • PUT

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 201: Success operation.
  • 409 (If the plan name already exists)

Headers

  • Location: is returned with the url to access the resource.

Required Arguments

  • name: Integer > 0.
  • type: String, "postpaid" or "prepaid".
  • dids: Integer > 0.

Example (application/x-www-form-urlencoded)

$ curl -k -d -vX PUT "name=some_plan&type=postpaid&dids=1&allow_incoming=true&charge_incoming=true" -vX PUT https://api.connexo.net/plan"

Example (application/json)

$ curl -k -X PUT -v -d@req.json -H "content-type: application/json" https://api.connexo.net/plan

Result:

Location: https://api.connexo.net/plan/12
{"id":12}

Where req.json is something like this:

  {
    "name": "Regular",
    "allow_incoming": true,
    "charge_incoming": true,
    "dids": 3,
    "type": "postpaid"
  }

/plan/:plan_id

Description

Returns the plan information, by id.

Methods

  • GET

Returns

  • 200
  • 404 (if the plan id does not exist).

Required Arguments

  • plan_id: Integer > 0

Example

$ curl -k "https://api.connexo.net/plan/11"

  {
    "id": 1,
    "name": "Regular",
    "type": 0,
    "dids": 1000,
    "allow_incoming": 1,
    "charge_incoming": 1,
    "created": "2013-06-07T20:39:35-03:00"
   }

/stats/billing

Description

Income vs cost report.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Optional Arguments

  • type: cost|income. If specified, the report will only contains the specified values.
  • tag: String. If specified, the report will only contain this specific tag.

Example

$ curl -k "https://api.connexo.net/stats/billing? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=daily"

[{
  "name": "Daily income",
  "pointStart": 1371254400,
  "pointInterval": 86400,
  "data": [0,0.01125,0,0,0,0.16875]
}, {
  "name": "Daily cost",
  "pointStart": 1371254400,
  "pointInterval": 86400,
  "data": [0,0.0110,0,0,0,0.2]
}]

/stats/carrier_seconds

Description

Total number of seconds of answered calls through all the known carriers.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/carrier_seconds? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

  [
    {
      "name": "Local",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    },
    {
      "name": "Vitelity",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  ]

/stats/carrier_minutes

Description

Total number of minutes of answered calls through all the known carriers.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/carrier_minutes? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

  [
    {
      "name": "Local",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    },
    {
      "name": "Vitelity",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  ]

/stats/trunk_usage

Description

By trunk type, returns how many channels were used. Trunk type is one of:

  • internal
  • subscriber
  • carrier

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/trunk_usage? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

[
  {
    "name": "internal",
    "title": "internal trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data": [0,0,0,7,0]
  },
  {
    "name": "subscriber",
    "title": "subscriber trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data":[0,0,0,0,0]
  },
  {
    "name": "carrier",
    "title": "carrier trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data": [0,0,0,2,0]
  }
]

/stats/carrier_status

Description

Returns statistics about calls made using carriers, their status and driver_status.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".

Example

$ curl -k "https://api.connexo.net/stats/carrier_status? \
  start=2013-06-15 \
  &end=2013-06-20"

{
  "status": [
    ["error",1], 
    ["finish",1071]
  ],
  "driver_status": [
    ["invalid_number_format",0],
    ["normal_temporary_failure",4],
    ["call_rejected",0],
    ["allotted_timeout",15],
    ["incompatible_destination",0],
    ["answer",704],
    ["normal_clearing",0],
    ["invalid_gateway",0],
    ["invalidargs",0],
    ["unallocated_number",0],
    ["cancel",81],
    ["error",0]
  ]
}

/stats/driver_status_by_carrier

Description

Returns statistics about driver statuses per carrier.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • carrier_id: Integer

Example

$ curl -k "https://api.connexo.net/stats/driver_status_by_carrier? \
  start=2013-06-15 \
  &end=2013-06-20" \
  &carrier_id=4

{
  "carrier": "Conexiant",
  "series": [
    ["invalid_number_format",0],
    ["normal_temporary_failure",4],
    ["call_rejected",0],
    ["allotted_timeout",23],
    ["incompatible_destination",0],
    ["answer",834],
    ["normal_clearing",0],
    ["invalid_gateway",0],
    ["simulated",0],
    ["dontcall",2],
    ["originator_cancel",230],
    ["success",0],
    ["early media",0],
    ["invalidargs",0],
    ["unallocated_number",0],
    ["cancel",85],
    ["error",0],
    ["missing",0],
    ["busy",35],
    ["user_busy",0],
    ["recovery_on_timer_expire",0],
    ["no_user_response",0],
    ["noanswer",48],
    ["user_not_registered",0],
  ]
}

Clone this wiki locally