Skip to content

Middleware API

Jump to bottom
Laura Estefanía Corvalán edited this page Jul 12, 2016 · 50 revisions

Endpoint

Your endpoint should look like https://api-.connexo.net/

Please send as an email to support@connexo.net if you don't have this information. In the examples below you will find the endpoint https://api.connexo.net/ as a mere example.

Authentication

Basic HTTP Authentication is supported. To use it, you have to acquire an API key from the backend or frontend interfaces. Then, for each HTTP request sent to the API, include a header like the following:

Authorization: Basic AUTHSTRING

Where AUTHSTRING is a base64 of a string composed like this:

key:secret

Trying it with curl: Use the -uKEY:SECRET switch, like:

$ curl -vXGET https://api.connexo.net/subscriber/list -u4084451d8994f7cb1cafa39eebaae1ea:80013271e873343a6bff7893508e6c700

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
  • dial_end_time
  • id
  • bill_time
  • dial_status
  • account_id_dst
  • account_id_src
  • trunk_name_dst
  • trunk_name_src
  • trunk_ip_dst
  • trunk_ip_src

Methods

  • GET

Returns

  • 200
  • 402 (prepaid account or account without balance and allow_access_to_cdr_api_without_balance flag turned off)
  • 400 (if an error occurs)

Required Arguments

  • from: Date. Format: YYYY-MM-DDTHH:MM:SS. (*)
  • to: Optional. Date. Format: YYYY-MM-DDTHH:MM:SS. Defaults to now.
  • end_from: Date. Format: YYYY-MM-DDTHH:MM:SS. (*)
  • end_to: Optional. Date. Format: YYYY-MM-DDTHH:MM:SS. Defaults to now.
  • scroll_id: Optional.
  • account_id: The account must be enabled. Optional. Can be a comma-separated string to allow filtering by multiple accounts.
  • did: Did number. Optional. Can be a comma-separated string to allow filtering by multiple dids.

(*) You must filter by one of them or both.

Examples

$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS"
$ curl -k "https://api.connexo.net/cdr?end_from=YYYY-MM-DDTHH:MM:SS"
$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS&end_from=YYYY-MM-DDTHH:MM:SS"
$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS&account_id=3"
$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS&account_id=2,110"
$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS&did=50640329000"
$ curl -k "https://api.connexo.net/cdr?from=YYYY-MM-DDTHH:MM:SS&did=50640329000,5078339000"
$ curl -k "https://api.connexo.net/cdr?scroll_id=c2NhbjswOzE7dG90YWxfaGl0czowOw=="

Response Example

{
  "total": 1, 
  "total_rows": 1, 
  "rows": [{
    "id":"a957ecd6-1f58-11e5-45g3-a1d7e9eae771",
    "ani_dst":"17862799916",
    "ani_src":"17862799916",
    "dial_status":"answer",
    "ani_e164":"17862799916",
    "bill_time":7,
    "date_created":1435690136000,
    "dial_end_time":1435690136000,
    "account_id_dst": null,
    "account_id_src": 2,
    "trunk_ip_src":"1.2.3.4",
    "trunk_ip_dst": null,
    "trunk_name_src":"Trunk.1.2.3.4",
    "trunk_name_dst": null,
    "dnis_e164":"14082571500",
    "dnis_src":"14082571500",
    "dnis_dst":"14082571500",
    "date_created_as_string":"2015-06-30T15:48:56-03:00",
    "dial_end_time_as_string":"2015-06-30T15:48:56-03:00"
  }], 
  "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/:subscriber_id/dids

Description

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

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • subscriber_id: Integer.

Example

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

  {
    "total_rows": 1,
    "rows": [{
       "id": 857,
       "number": 1542610044455,
       "account_id": 1,
       "subscriber_id": 1,
       "numplan_id": 1,
       "numplan": "USA",
       "plan": "Inicial",
       "routing_plan_id": 1,
       "routing_plan": "Regular",
       "description": "Prepago",
       "allow_incoming": 1,
       "organization_mrc": "0.01",
       "organization_nrc": "0.01",
       "subscriber_inbound_first_unit_length": 1,
       "subscriber_inbound_first_unit_cost": "2.0",
       "subscriber_inbound_next_unit_length": 3,
       "subscriber_inbound_next_unit_cost": "4.0",
       "country_iso2": "US",
       "country_name": "UNITED STATES",
       "type": "local" 
     }]
  }

/account/list

Description

Returns the complete list of all the accounts known for the organization.

Methods

  • GET

Returns

  • 200

Example

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

  [
    {
      "id": 1,
      "credit": "0.0",
      "subscriber_id": 1,
      "plan_id": 1,
      "description": "account description"
      "created": "2013-05-29T09:40:59-03:00",
      "organization_id": 1,
      "enabled": true,                     
      "postpaid": false,
      "balance": "250.0",
      "available_dids": 10,
      "plan_name": "Inicial",
      "plan_recharge_max_value": 200,
      "plan_recharge_increment_steps": 50,
      "daily_usage_limit_alert": null,
      "allow_access_to_cdr_api_without_balance": false,
      "services_charge_failed_calls": false,
      "services_call_failed_cost": null
    }
  ]

/me/accounts

Description

Returns the complete list of all the accounts known for the authenticated subscriber user.

Methods

  • GET

Returns

  • 200
  • 404 (if an error occurs)
  • 400 (if api keys doesn't belongs to a subscriber user)

Example

$ curl -k "https://api.connexo.net/me/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"
    }
  ]

/me/dids

Description

Returns a paginated list of dids known for the authenticated subscriber user.

Methods

  • GET

Returns

  • 200
  • 404 (if an error occurs)
  • 400 (if api keys doesn't belongs to a subscriber user)

Required Arguments

  • page: Integer > 0. Defines the offset from the first result you want to fetch.
  • limit: Integer. Allows you to configure the maximum amount of rows to be returned.

Example

$ curl -k "https://api.connexo.net/me/dids?page=2&limit=25"

  {
    "total":25,
    "total_rows": 500,
    "rows": [{
      "id": 1,
      "number": 130312345678,
      "plan": "Basic",
      "account": "Description",
      "forward_to": null,
      "tags": [{"name": "TAG_NAME", "color": "FF00FF"}],                
      "subscriber_id": 1,
      "subscriber_inbound_first_unit_length": 120,
      "subscriber_inbound_first_unit_cost": "0.002",
      "subscriber_inbound_next_unit_length": 120,
      "subscriber_inbound_next_unit_cost": "0.004",
      "organization_nrc": "0.01",
      "organization_mrc": "0.01",
      "type": "local",
      "country_iso2": "US",
      "country_name": "UNITED STATES"
   },
   ...

/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