Core concepts
Request Format
All VerticalResponse API request calls consist of the following elements:
| Endpoint URL | the fully qualified URL of the endpoint for which to make the call |
| Header parameters |
the authentication credentials include the access token.The access token can either be passed as a header or a url parameter. "Authorization:Bearer <acces_token>" or https://vrapi.verticalresponse.com/api/v1/contacts?access_token=<access_token> |
| Parameters | name/value pairs specific to each API call and type of operation. Parameters are used to create a resource, update a resource, or in the case of a GET operation, narrow the results of a request. |
| (Optional) type | an optional URL parameter specifying the desired level of detail that a GET request should return in the response. Values can be basic, standard, and all whose effect will vary depending on the API call. |
The following are two example requests which demonstrate these fields:
The first snippet shows a POST request to create an email. This request includes header fields for authentication, the desired content type (JSON), and multiple name/value pairs to be sent to the server to create the email (e.g. subject, etc.):
The next example shows a GET request to obtain information about a particular email identified by its ID. In this example, the authentication fields are specified in the header, and the type URL parameter is set to all to request that all possible information be returned:
The response is as follows:
If the application wanted less information, then it could, for example, set type to basic which would return only the basic fields as shown in the following snippet:
For more details on what basic, standard, and all return for each object, consult the API reference docs.
Response Format
The basic response format is similar for each Vertical Response API call. The following example snippet shows a response to a request to obtain information about a contact, which includes all the contact fields:
The "URL" is a copy of the fully qualified endpoint URL which the API call was invoked for. If additional URL parameters such as type were included in the call, they will also be included in the URL returned.
The "attributes" contain the collection of name/value pairs returned when requesting information through a GET request. If the operation is requesting an array of objects (e.g. an array of contacts in a list), then the attributes for each object will be returned in an array called “items”. The section below called Collections and Pagination explains this further.
A response’s "links" collection contains additional, fully qualified URLs which can be used to navigate the endpoint. Most calls will return an up link which is the URL of the container end point. In the example above, the request was to obtain the information about a specific contact, and therefore the up link specifies the container end point for all contacts.
Additional API‑specific URLs may also be included in the links collection allowing an application to further navigate on related information for the specified entity. In the example above, links are provided for obtaining the lists that the contact belongs to, messages that the contact has sent etc. As shown in the example, each of these URLs includes the contact’s ID followed by the respective endpoint name.
Responses to POST and PUT requests will include a status node whose name contains the status itself (e.g. “success”), and its child nodes include the HTTP status code and a related message. This is shown in the following example:
If the request failed, then additional fields may also be included providing information about the error. This will be discussed further in the Error Scenarios section below.
Collections and Pagination
If a GET request is made to return an array of items, then each object will be contained within an items collection, and each will include the endpoint URL for accessing that object. For example, the following snippet shows the response to a request for all contacts:
In this example, the attributes and the corresponding URLs are returned for contacts 2111549 and 1277503.
In many cases the array of records stored on the server may be large and an application may therefore want to perform “pagination” whereby only a subset of those records are returned by the API call and additional records are requested in subsequent calls.
Vertical Response supports pagination on GET requests through two optional URL parameters:
| index | the one‑based index into the result set from where records should be obtained. |
| limit | the maximum number of records that a GET request should return in its response, starting at the index, if specified. |
A GET request can be made without the limit parameter in which case the result set size returned defaults to 50 objects. Also, if index is not specified, then the result set will start at index 1.
The following snippet shows the usage of the limit and index to obtain two contacts starting at index 22:
https://vrapi.verticalresponse.com/api/v1/contacts?index=22&limit=2
The response is shown here:
Of particular interest are the response’s prev and next links which are automatically appended with the index and page size (limit) for the previous and next set of results respectively. Using these links, an application can easily obtain the previous and next result sets.
Also note that if the response contains the first set of objects from the start of the list or the last set of objects from the end of the list, then the response will not contain the prev or next links accordingly, since there is no previous or next set of results to obtain.
