Voluum API Docs

Voluum exposes REST-type API using secure HTTPS methods as a transport layer and JSON as a format. Our centric API gateway, api.voluum.com, is used to handle all requests to the relevant micro-services by the inclusion of distinct directory suffixes. Full API documentation is available at http://developers.voluum.com.

Caution

Voluum Note:

  • To ensure resources for everyone, the API limits the number of requests a user may make per minute. The limit is not documented and is subject to change.

  • If you want to use the Voluum API using the access key without hard-coding your password in scripts, you need to generate it in the Voluum platform. To learn more, go to the below section explaining how to generate an access key.

Anatomy of a Request URL

Provided below is a breakdown of the different parts included within this example request URL:

url-anatomy.png

Examples of directory suffix:

  • /report

  • /campaign

  • /traffic-source

Certain requests also require a component identifier to be appended after a service directory, those of which are clearly indicated within our API documentation via curly brackets, for example:

/report/live/clicks/{campaignId}

where the {campaignId} token needs to be replaced with a valid ID string of a component from your Voluum account. Additional parameters relevant to a service are then placed in the URL’s query string (after the question mark, ?) to describe the requested data, for example:

?from=2017-05-20T00:00:00Z&to=2017-05-21T00:00:00Z&tz=Etc/GMT?

How to use Voluum API

Basically, if you want to use API for reporting and other purposes, the best way to create a request is to check the request based on our panel’s behavior. As you may not know our entire panel is performed with API, so you can explore behavior for different requests by using a Chrome Developers tools to investigate the set of parameters which you can use in different requests.

So in order to prepare this specific API request, you can perform it in the panel and copy the request. Please follow the example steps (for basic reporting) below:

  1. Within the report choose the reporting columns which you wish to pull data for and click ‘refresh’ in the panel.

  2. Use web dev tools (F12) with the report to view the request URL along with the authentication token needed to perform the API call. This will be visible within the Network (XHR) tab in Chrome’s web dev tools (here’s an exemplary screenshot from our demo account). For Firefox, it will be visible under Net (XHR).

    api1.png
  3. Copy the request URL and auth token needed for the API call.

  4. Based on that you can check any requests performed in the front-end panel.

  5. To authorize requests you have to use the cwauth-token (authentication token). Please make sure that it is valid when you perform your request Values of such tokens are uniquely generated for each login session, so the requests won’t work, if the session expires (up to 4 hours from the last performed request). All possible API endpoints are listed here: http://developers.voluum.com/. Please note that to ensure resources for everyone, the API limits the number of requests a user may make per minute. The limit is not documented and is subject to change.

Voluum API: Generating an Access Key

To improve security and stop hard-coding passwords into your scripts, you can generate an access key (an access key ID and secret access key). The access key is then used to get the session token for your API requests. Therefore, when you need to use the Voluum API, first you need to generate the access key in the Voluum platform.

Keep in mind that not all Voluum endpoints are accessible while using the access key. The following Voluum endpoints deny access for sessions created with the access key:

put.png

/profile/password

post.png

/auth/access

post.png

/payment/coupon

post.png

/profile/emailchange/init

patch.png

/setup

post.png

/payment/coupon/{couponCode}/validate

post.png

/profile/emailchange/resend

post.png

/report/manual-cost

delete.png

/payment/profile

post.png

/profile/emailchange/cancel

put.png

/zeropark/integration

get.png

/payment/profile

put.png

/profile/client

delete.png

/zeropark/integration

put.png

/payment/profile

get.png

/profile/invitation

get.png

/billing/info

delete.png

/payment/profile/clean

post.png

/profile/invitation

put.png

/billing/info

get.png

/payment/token

delete.png

/profile/invitation/{email}

get.png

/billing/invoice

post.png

/payment/topup/execute

post.png

/profile/membership

get.png

/billing/invoice/{invoiceId}

post.png

/payment/topup/init

delete.png

/profile/membership

get.png

/billing/notification

get.png

/plan

delete.png

/profile/member/{userId}

get.png

/billing/plan

get.png

/referral

post.png

/profile/mfa/initialize

put.png

/billing/plan

post.png

/feedback

post.png

/profile/mfa/activate

get.png

/payment/balance

post.png

/profile/mfa/deactivate

get.png

/payment/coupon

To get the access key, follow the steps below:

  1. In Voluum, click the profile_settings.png icon (top right corner of the screen). Your account data view will show up.

  2. Go to the Security tab and scroll down to the ACCESS KEYS section.

  3. Click the Add new key button. The Generate Access Key pop-up window will show up.

    1. Provide the key name.

    2. Provide your account password.

    3. Click the Save button. The secret access key and access client ID will be generated.

    4. Once the secret access key and its ID are generated, click the Copy button - copy both values, the secret access key and access key ID, and save them locally on your machine.

      Caution

      Voluum Note: Once you have generated the access key, you need to copy and save it. This is the only time when the secret access key is visible to you, thus you need to store it locally to be able to use it with the Voluum API.

      access_key_generated.png
  4. Close the Generated key pop-up window. The access key you have created is added to the list of keys in the ACCESS KEYS section.

  5. Once the access key is generated, find out how to create a session with it: https://developers.voluum.com/#!/authentication.

Frequently Asked Questions:

Have more questions about the access keys? You might find the answer below: