How to make requests to the Voxy Partner API

 

1. What is an HTTP Request?

 

 

The Voxy Partner API is a REST API that accepts HTTP requests and returns JSON responses.

In order to use the Voxy Partner API, you will need to be able to make an HTTP request. HTTP is a request/response protocol where your system sends a request to the Voxy Partner API, and the API sends back a response (i.e. “User successfully created” or “Here is the data you requested”).

All standard programming languages will have native or third-party libraries to enable making HTTP requests.

If you are doing an API integration, you will need to configure your website, LMS, CMS or other system to make HTTP requests to the Voxy Partner API to complete specific tasks or retrieve specific data. Contact your Customer Success Manager to define what tasks are required for your organization’s implementation.

Example: The Voxy Partner API has the following endpoint: https://app.voxy.com/partner_api/partners/segments/. If you make an HTTP GET request to that endpoint, it will return a data object that contains a list of custom segments created in your organization.

 

 

2. Types of HTTP API Requests

 

 

There are different types of HTTP requests you should use with an API depending on what you are trying to accomplish. The Voxy Partner API supports four types of requests: GET, POST, PUT and DELETE.

  • GET is used to retrieve data
  • POST is used to create or insert data
  • PUT is used for updating or editing data
  • DELETE is used for deleting data

All standard programming languages will have native or third-party libraries to enable making HTTP requests, and each will allow you to specify the type of request you are making.

 

Example: The Voxy Partner API has the following endpoint: https://partners/users/{external_user_id}. If you make a HTTP GET request to that endpoint, you can retrieve the user’s profile information. If you make a HTTP POST request to that endpoint with the minimum parameters, you can register a new user.

 

 

3. GET Example

 

 

GET is the most common HTTP request used in web development. When you load a URL in your browser, you are actually making a HTTP GET request to a server that responds with an HTML page that is then rendered in the browser window.

However, in a REST API like the Voxy Partner API, instead of getting an HTML page, the response will be a data object in JSON format.

Example: The Voxy Partner API has the following endpoint: https://partners/users/{external_user_id}. If you make a HTTP GET request to that endpoint, the API will respond with a JSON data object that contains the user’s profile information.

 

 

4. POST Example

 

 

A POST request is used to insert data, for example to create a new user or a new custom segment.

When you make a POST request, you are often expected to submit a data object that contains the information needed to execute the request, sometimes called parameters. Some POST parameters may be required, while others may be optional.

For example, when you create a new user using the Voxy Partner API, you are required to include the first_name, email, and native_language as parameters in the body of your request. Other parameters, such as expiration_date, may be optionally included.

 

 

5. How to generate the required Authorization header

 

 

In order to ensure security and privacy, all requests to the Voxy Partner API require a valid HTTP Authorization header, or else they will be denied.

In order to generate the required Authorization header, you will need an API Key and API Secret that can be provided by your Voxy Customer Success Manager.

The format for the Authorization header is "Voxy {{API_KEY}}:{{REQUEST_SIGNATURE}}" where:

  1. {{API_KEY}} is your API_KEY,
  2. {{REQUEST_SIGNATURE}} is a sha256 hash of your API_SECRET, concatenated with the URL encoded parameters, sorted alphabetically.

A common error is an incorrectly generated REQUEST_SIGNATURE. To generate the signature correctly, your code should execute the following steps:

  1. Get any parameters that were included in the request and sort them alphabetically by parameter name.
  2. URL encode the alphabetically sorted parameters.
  3. Create a text string that is a concatenation of your API signature and the URL encoded parameters from Step #2 (e.g. {{API_SECRET}}+{{URL_ENCODED_PARAMETERS}}.
  4. Encrypt the string using the sha-256 hashing algorithm.

As you can see, if your API request includes any parameters, then those parameters must be used to generate the {{REQUEST_SIGNATURE}}.

If you fail to generate the Authorization header exactly as described above, your request will be denied by the Voxy Partner API, and you will receive a 401 - Unauthorized response, indicating that we could not verify that the request came from a trusted source.

For examples of code for generating the Authorization header generation, visit our Partner API Examples repository in Github (request access from your Voxy Customer Success Manager).  The repository contains example code for making requests in the following languages:

  • PHP
  • Ruby
  • Python
  • Java
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.