Introduction to Api

Last updated 16 days ago

Integrate with Previsto using our Rest Api.

Welcome to the Previsto API documentation. This is the API used by the official Previsto web interface as well as our Mobile App, so everything the web ui is able to do can also be accomplished via the API.

The Previsto API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code). JSON will be returned in all GET, PUT and POST responses from the API, including errors. Only exception is DELETE requests which returns an empty response upon success.

Feedback

We would love your feedback at any time. Contact us at support@previsto.com.

Authentication

Example Request

$ curl https://api.previsto.io/account \
-u sk_12345:

You authenticate to the Previsto API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via a Token given in the HTTP headers. Provide your API key as the username of Basic Authentication.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

HTTP Status Codes

Previsto uses conventional HTTP response codes to indicate success or failure of an API request. 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 was missing etc.), and codes in the 5xx range indicate an error with Previsto's servers.

HTTP Status Code Summary

HTTP Code

Meaning

200 - OK

Everything worked as expected.

400 - Bad Request

Often missing a required parameter.

401 - Unauthorized

No valid API key provided.

402 - Request Failed

Parameters were valid but request failed.

403 - Forbidden

Action not allowed for provided API key.

404 - Not Found

The requested item doesn't exist.

429 - Too many requests

Request limit exceeded.

500, 502, 503, 504 - Server Errors

Something went wrong on Previsto's end.

Errors

Example Response

{
"type": "invalid_request",
"message": "'name' must be specified.",
"param": "name"
}

When an error occurs the response will always contain a JSON object as shown to the right. The following is the explanation of the Error object.

Attributes

Field

Optional

Explained

type

No

The type of error returned. Can be invalid_request_error or api_error

message

Yes

A human-readable message giving more details about the error.

param

Yes

The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

Types

Value

Explained

invalid_request_error

Invalid request errors arise when your request has invalid parameters.

api_error

API errors cover any other type of problem (e.g. a temporary problem with Previsto's servers) and should turn up only very infrequently.

Request Limit

The Previsto API will rate limit requests on a per-API key basis. Each key will by default have a limit of 120 requests per minute. If you exceed your rate limit you will receive an API response with a 429 HTTP status code and a brief message indicating you have exceeded your rate limit.

To increase your rate limit, contact sales.

Pagination

All top-level Previsto API resources have support for bulk fetches — "list" API methods. For instance you can list contacts, list assignments, and list agreements. These list API methods share a common structure. Previsto utilizes cursor-based pagination, using the parameter page. Pass page to dictate where in the list you would like to begin (see below).

Arguments

Field

Optional

Explained

size

Yes

Size of page. Defines the number of objects to be returned. Size can range between 1 and 100 items. Default limit is 20.

page

Yes

A zero-based cursor for use in pagination. Page is a number that defines your place in the list. For instance, if you make a list request and receive 100 objects, your subsequent call can set page=1 in order to fetch the next page of the list.

Filtering

All top-level Previsto API resources have support for filtering by its properties. All properties can be used as a query parameter and simple equality methods are available. The example to the right shows how to request assignments that has been invoiced.

curl https://api.previsto.io/assignments?status=Invoiced \
-u sk_12345:

Sorting

All top-level Previsto API resources have support for sorting by its properties. Sorting can be done ascending or descending. The example to the right shows how to request assignments sorted by its timestamp in descending order.

curl https://api.previsto.io/assignments?sort=timestamp,desc \
-u sk_12345:

Metadata

Most updatable Previsto objects support a user-specified metadata parameter.

You can use the metadata parameter to attach key-value data. This is useful for storing additional structured information about an object. As an example, you could store your user's full name, favorite color, and their corresponding unique identifier from your system on a Previsto customer object.

Note: You can have up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.