Voipment REST API Overview

This section describes the resources that make up the official Voipment API version 1. If you have any problems or requests please contact us at s...@voipment.com.

The API is only accessible over HTTPS from api.voipment.com. Requests can be sent as HTTP parameters or JSON objects. All the responses are in JSON.

All the dates are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Parameters can be sent either as JSON with Content-Type of application/json or simply form data.

Form Data Example:
curl -X POST https://api.voipment.com/calls \
     -u API_KEY:                            \
     -d from=110                            \
     -d to=360                              \
     -d display_number=14085558899          \
     -d display_name="Call: John Doe"
JSON Example:
curl -X POST https://api.voipment.com/calls \
     -H "Content-type: application/json"    \
     -u API_KEY:                            \
     -d '
     {
        "from": "110",
        "to": "360",
        "display_number": "14085558899",
        "display_name": "Call: John Doe"
     }'

Voipment uses standard HTTP response codes to let the client know wether an API call succeeded or not.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter), and codes in the 5xx range indicate an error with Voipment's servers.

Successful API Call Example:
HTTP/1.1 200 OK

{
  "id": 1304969,
  "url": "/voicemails/1304969",
  "duration": 3,
  "is_new": true,
  "from": {
    "type": "Phone",
    "number": "+14085550000"
  },
  "via_phone_number": {
    "number": "+14081234567",
    "url": "/phone_numbers/+14081234567"
  },
  "download_url": "/voicemails/1304969.mp3",
  "created_at": "2015-06-02T17:24:44Z"
}
Unauthorized API Call:
HTTP/1.1 401 Unauthorized

{
  "message": "Unauthorized"
}
Invalid Parameters:
HTTP/1.1 422 Unprocessable Entity

{
  "message":"Extension 110 not found"
}

GET Used for retrieving resources, information, logs, call status, etc...

POST Used for creating resources and performing telephony actions. For instance if you need to make a call, you should use POST verb.

PUT Used for updating resources or state of your calls. You can use PUT method to update state of an established call, play a file on a call, transfer the call, etc.

DELETE Used for deleting resources or ending telephony actions. For instance, you can hangup a call with DELETE verb

You should generate API Key for your Account or Location. To generate an API Key please go to the account or location, click on Resources then click on API Keys.

If you generate an API Key under account, you can use the key to manage all resources from all locations. If you generate an API Key under a location, only the resource defined for that location are accessible. For instance, if you have extension 110 in Location A and extension 360 in Location B, you can't call ext 360 using the API key generated for Location A.

Currently we only support Basic Authentication:

curl -u API_KEY: https://api.voipment.com

You only need to provide API_KEY as username, password can be blank. Please note for the purpose of testing with cURL, your should use -u flag to send basic authentication credentials. If you don't add a colon : after the API_KEY cURL will ask you for a password.

Requests that return multiple resources will be paginated to 50 items by default. To change the page size, you can pass ?per_page. To navigate to other pages you can pass ?page.

{
    "calls": [
      ...
    ],
    "pagination": {
      "current_page": 1,
      "limit": 50,
      "size": 15,
      "total_pages": 1,
      "total_records": 15
    }
}