Skip to main content

Introduction to Api

Welcome to the Previsto API documentation. This API is also used by the official Previsto web interface as well as our Mobile App.

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.


We would love your feedback at any time. Contact us at


Example Request

$ curl \
-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 CodeMeaning
200 - OKEverything worked as expected.
400 - Bad RequestOften missing a required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedParameters were valid but request failed.
403 - ForbiddenAction not allowed for provided API key.
404 - Not FoundThe requested item doesn't exist.
429 - Too many requestsRequest limit exceeded.
500, 502, 503, 504 - Server ErrorsSomething went wrong on Previsto's end.


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.


typeNoThe type of error returned. Can be invalid_request_error or api_error
messageYesA human-readable message giving more details about the error.
paramYesThe 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.


invalid_request_errorInvalid request errors arise when your request has invalid parameters.
api_errorAPI 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.


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


sizeYesSize of page. Defines the number of objects to be returned. Size can range between 1 and 100 items. Default limit is 20.
pageYesA 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.


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 \
-u sk_12345:


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,desc \
-u sk_12345:


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.