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.

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

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?

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).

   

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.

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:

	/profile/password		/auth/access		/payment/coupon
	/profile/emailchange/init		/setup		/payment/coupon/{couponCode}/validate
	/profile/emailchange/resend		/report/manual-cost		/payment/profile
	/profile/emailchange/cancel		/zeropark/integration		/payment/profile
	/profile/client		/zeropark/integration		/payment/profile
	/profile/invitation		/billing/info		/payment/profile/clean
	/profile/invitation		/billing/info		/payment/token
	/profile/invitation/{email}		/billing/invoice		/payment/topup/execute
	/profile/membership		/billing/invoice/{invoiceId}		/payment/topup/init
	/profile/membership		/billing/notification		/plan
	/profile/member/{userId}		/billing/plan		/referral
	/profile/mfa/initialize		/billing/plan		/feedback
	/profile/mfa/activate		/payment/balance
	/profile/mfa/deactivate		/payment/coupon

To get the access key, follow the steps below:

1. In Voluum, click the  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.

      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.

      

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.

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