NAV undefined
undefined
bash

API Introduction

This is our API Endpoint

https://api.previsto.io

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 through Facebook or Google+.

Authentication

Example Request

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

Previsto uses Basic Authntication to pass an auth token. A sample test API key has been provided in all the examples on the page, so you can test out any example right away.

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

Account

This is an object representing your Previsto account. You can retrieve it to see properties on the account like its current e-mail address etc. You are allowed to change parameters for your own account only.

The account object also holds information about the user's authorizations in the property 'roles'. There are 2 kinds of roles: (1) system-wide roles and (2) organization-specific roles. System-wide roles are prefixed with ROLE_ and organization-specific roles are prefixed with ORGROLE_ followed by the id of the specific organization.

The account object

Example Response

{
    "id": "acct_7B10MYfEnPp6r",
    "login": "john",
    "name": "John Dow",
    "email": "john@doe.com",
    "emailValidated": true,
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location": [11.543540954589844, 56.703469017862034],
    "languageCode": "da",
    "roles": [
        "ROLE_USER",
        "ORGROLE_org-ZW46jOjfA0rpDZ_USER"
    ],
    "meta": {
        "hairColor": "Brown"
    }
}
Field Type Required Description
login string Yes -
password string Yes Cannot not be read. Can only be set via this property when account is created.
name string Yes Full name of user
email string Yes Must have email syntax, fx. 'john@doe.com'
emailValidated boolean No -
languageCode string Yes 2-letter ISO 639-1 code, fx. 'da'
address string No Street and house number
appartment string No Apartment, fx. '1. th.'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
location number[] Yes Array of 2 numbers holding longitude and latitude in specified order according to geojson syntax. (Fx. [11.543540954589844, 56.703469017862034])
roles array No Array of user's system and organization roles.
meta object No Dictionary of meta values.

Retrieve current account

Definition

GET https://api.previsto.io/accounts/current

Example Request

curl https://api.previsto.io/accounts/current \
   -u sk_12345:

Example Response

{
    "id": "acct_7B10MYfEnPp6r",
    "login": "john",
    "name": "John Dow",
    "email": "john@doe.com",
    "emailValidated": true,
    "address": "Kundevej 2",
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location": [11.543540954589844, 56.703469017862034],
    "languageCode": "da",
    "roles": [
        "ROLE_USER",
        "ORGROLE_org-ZW46jOjfA0rpDZ_USER"
    ],
    "meta": {
        "hairColor": "Brown"
    }
}

Retrieves the details of the account.

Arguments

Field Type Required Description
id string Yes The identifier of the account to be retrieved.

Returns

Returns an account object if a valid identifier was provided.

Update current account

Definition

POST https://api.previsto.io/accounts/current

Example Request

curl https://api.previsto.io/accounts/current \
   -u sk_12345: \
   -d email=jane@doe.com

Example Response

{
    "id": "acct_7B10MYfEnPp6r",
    "login": "john",
    "name": "John Dow",
    "email": "jane@doe.com",
    "emailValidated": true,
    "address": "Kundevej 2",
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location": [11.543540954589844, 56.703469017862034],
    "languageCode": "da",
    "roles": [
        "ROLE_USER",
        "ORGROLE_org-ZW46jOjfA0rpDZ_USER"
    ],
    "meta": {
        "hairColor": "Brown"
    }
}

Updates an account by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Field Type Required Description
name string Yes Full name of user
email string No -
languageCode string No 2-letter ISO 639-1 code, fx. 'da'
meta object No Dictionary of meta values.

Returns

Returns the account object if the update succeeded. Returns an error if update parameters are invalid.

Delete an account

Definition

DELETE https://api.previsto.io/accounts/{ACCOUNT_ID}

Example Request

curl https://api.previsto.io/accounts/acct_7B10MYfEnPp6r \
   -u sk_12345: \
   -X DELETE

Permanently deletes an account. It cannot be undone.

Arguments

Field Type Required Description
id string Yes The identifier of the account to be deletes.

Returns

Returns an empty response upon success. If the account ID does not exist, this call returns an error.

Organization

This is an object representing an organization in Skveege. You can retrieve it to see properties on the organization like its current e-mail address, physical address etc.

You are only allowed to access the organization your account refers to.

The organization object

Example Response

{
    "id": "acct_123123123",
    "name": "Vinduespudser A/S",
    "url": "http://vinduespudser.nu",
    "address": "Pudservej 111",
    "postalCode": "1234",
    "city": "Pudserby",
    "countryCode": "DK",
    "phone": "+452209876543",
    "email": "vindue@pudser.dk",
    "registrationNo": "12345678",
    "terminated": false,
    "terminationTime": null,
    "createdDate": "2015-01-01T00:00:00Z",
    "trial": true,
    "subscriptionPrice": 0,
    "subscriptionPeriod": "Monthly",
    "subscriptionDiscount": 0.0,
    "subscriptionExpires": null,
    "subscriptionType": "Free",
    "languageCode": "da",
    "baseCurrency": "DKK",
    "locked": false,
    "subjectToVat": true,
    "timeZone": "Europe/Copenhagen"
}
Field Type Required Description
id string No -
name string Yes Name of the business, fx. 'Vinduespudser A/S'
url string No -
address string No The street address, 'fx. Vesterbro 11'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The business's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
terminated boolean No -
terminationTime datetime No -
createdDate datetime No -
trial boolean No -
subscriptionPrice number No Price for subscription in 1⁄100 of the monetary unit (fx. cents or øre)
subscriptionPeriod string No 'Monthly', 'Quarterly', 'SemiAnnually' or 'Annually'. Default is 'Monthly'.
subscriptionDiscount number No -
subscriptionExpires datetime No -
subscriptionType string No 'Free', 'Micro', 'Small', 'Medium' or 'Large'.
languageCode string No 2-letter ISO 639-1 code, fx. 'da'
baseCurrency string Yes 3-letter ISO 4217 code, fx. 'DKK'
locked boolean No -
subjectToVat boolean No -
timeZone string No -
referenceId string No An optional id for other systems to use for refering to this organization.

Create an organization

Definition

POST https://api.previsto.io/organizations
`

Example Request

curl https://api.previsto.io/organizations \
   -u sk_12345: \
   -d name="Vinduespudser A/S"

Example Response

{
    "id": "acct_123123123",
    "name": "Vinduespudser A/S",
    "url": null,
    "address": null,
    "postalCode": null,
    "city": null,
    "countryCode": "DK",
    "phone": null,
    "email": null,
    "registrationNo": null,
    "terminated": false,
    "terminationTime": null,
    "createdDate": "2015-01-01T00:00:00Z",
    "trial": true,
    "subscriptionPrice": 0,
    "subscriptionPeriod": "Monthly",
    "subscriptionDiscount": 0.0,
    "subscriptionExpires": null,
    "subscriptionType": "Free",
    "languageCode": "da",
    "baseCurrency": "DKK",
    "locked": false,
    "subjectToVat": true,
    "timeZone": "Europe/Copenhagen"
}

Creates a new organization.

A user can only create a new organization if it is not related to an organization yet. When a user creates a new organization it will automatically become related to the created organization.

Arguments

Field Type Required Description
name string Yes Name of the business, fx. 'Vinduespudser A/S'
url string No -
address string No The street address, 'fx. Vesterbro 11'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The business's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
languageCode string No 2-letter ISO 639-1 code, fx. 'da'
baseCurrency string No 3-letter ISO 4217 code, fx. 'DKK'
subjectToVat boolean No -
timeZone string No -

Returns

Returns an organization object if the call succeeded. If a invalid parameters are provided, the call will return an error.

Retrieve an organization

Definition

GET https://api.previsto.io/organization

Example Request

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

Example Response

{
    "id": "acct_123123123",
    "name": "Vinduespudser A/S",
    "url": "http://vinduespudser.nu",
    "address": "Pudservej 111",
    "postalCode": "1234",
    "city": "Pudserby",
    "countryCode": "DK",
    "phone": "+452212341234",
    "email": "vindue@pudser.dk",
    "registrationNo": "12345678",
    "terminated": false,
    "terminationTime": null,
    "createdDate": "2015-01-01T00:00:00Z",
    "trial": true,
    "subscriptionPrice": 0,
    "subscriptionPeriod": "Monthly",
    "subscriptionDiscount": 0.0,
    "subscriptionExpires": null,
    "subscriptionType": "Free",
    "languageCode": "da",
    "baseCurrency": "DKK",
    "locked": false,
    "subjectToVat": true,
    "timeZone": "Europe/Copenhagen"
}

Retrieves the details of the organization.

Arguments

Field Type Required Description
id string Yes The identifier of the organization to be retrieved.

Returns

Returns an organization object if a valid identifier was provided.

Update an organization

Definition

POST https://api.previsto.io/organizations/{organization_ID}

Example Request

curl https://api.previsto.io/organizations/acct_123123123 \
   -u sk_12345: \
   -d phone=+452209876543

Example Response

{
    "id": "acct_123123123",
    "name": "Vinduespudser A/S",
    "url": "http://vinduespudser.nu",
    "address": "Pudservej 111",
    "postalCode": "1234",
    "city": "Pudserby",
    "countryCode": "DK",
    "phone": "+452209876543",
    "email": "vindue@pudser.dk",
    "registrationNo": "12345678",
    "terminated": false,
    "terminationTime": null,
    "createdDate": "2015-01-01T00:00:00Z",
    "trial": true,
    "subscriptionPrice": 0,
    "subscriptionPeriod": "Monthly",
    "subscriptionDiscount": 0.0,
    "subscriptionExpires": null,
    "subscriptionType": "Free",
    "languageCode": "da",
    "baseCurrency": "DKK",
    "locked": false,
    "subjectToVat": true,
    "timeZone": "Europe/Copenhagen"
}

Updates an organization by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Field Type Required Description
name string Yes Name of the business, fx. 'Vinduespudser A/S'
url string No -
address string No The street address, 'fx. Vesterbro 11'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The business's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
languageCode string No 2-letter ISO 639-1 code, fx. 'da'
baseCurrency string No 3-letter ISO 4217 code, fx. 'DKK'
subjectToVat boolean No -
timeZone string No -

Returns

Returns the organization object if the update succeeded. Returns an error if update parameters are invalid.

Delete an organization

Definition

DELETE https://api.previsto.io/organizations/{organization_ID}

Example Request

curl https://api.previsto.io/organizations/acct_123123123 \
   -u sk_12345: \
   -X DELETE

Permanently deletes an organization. It cannot be undone.

Arguments

Field Type Required Description
id string Yes The identifier of the organization to be deletes.

Returns

Returns an empty response upon success. If the organization ID does not exist, this call returns an error.

Contact

A Contact specifies a Customer's information. The Contact can be a private person or a Company.

The contact object

Example Response

{
    "id": "con_123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}
Field Type Required Description
id string No -
name string Yes The name of the contact. Can be either a company name or a person's name.
address string No The street address, 'fx. Vesterbro 11'
appartment string No Apartment, fx. '1. th.'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
location number[] Yes Array of length 2 holding longitude and latitude in specified order. (Fx. [11.543540954589844, 56.703469017862034])
number string No Arbitrary number (or string) that contacts can be referred to by.
remoteId string No Id of the connected contact in financial system or null.
remoteOrderId string No Id of current open order for this contact in financial system or null.
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The contact's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
ean string No The contact's EAN (European Article Number).
accountingMode string No None, AddToDraft or AddToInvoice.
accountingTime string No BeforeWork or AfterWork.
invoiceDelivery string No None or Email.
payingContactId string No Id of another contact that pays assignments for this contact or null.
note string No -
notifyBeforeWork boolean No Flag that defines if contact should be notified of work or not.
archived boolean No -
agentIds string[] No Ids of the agents that takes care of this contact. Currently always account Ids. Empty list means that it is not specified.
meta object No Dictionary of meta value.

Create a contact

Definition

POST https://api.previsto.io/contacts
`

Example Request

curl https://api.previsto.io/contacts \
   -u sk_12345: \
   -d name="Anna Jensen" \
   -d meta[hairColor]=Brown

Example Response

{
    "id": "con_123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

Creates a new contact.

Arguments

Field Type Required Description
name string Yes The name of the contact. Can be either a company name or a person's name.
address string No The street address, 'fx. Vesterbro 11'
appartment string No The apartment, 'fx. 1. th'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
location number[] Yes Array of length 2 holding longitude and latitude in specified order. (Fx. [11.543540954589844, 56.703469017862034])
number integer No Arbitrary number (or string) that contacts can be referred to by.
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The contact's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
ean string No The contact's EAN (European Article Number).
accountingMode string No None, AddToDraft or AddToInvoice.
accountingTime string No BeforeWork or AfterWork.
invoiceDelivery string No None or Email.
payingContactId string No Id of another contact that pays assignments for this contact or null.
note string No -
notifyBeforeWork boolean No Flag that defines if contact should be notified of work or not.
archived boolean No -
meta object No Dictionary of meta value.

Returns

Returns an contact object if the call succeeded.

Retrieve a contact

Definition

GET https://api.previsto.io/contacts/{CONTACT_ID}

Example Request

curl https://api.previsto.io/contacts/con_123123123 \
   -u sk_12345:

Example Response

{
    "id": "con_123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

Retrieves the details of an existing contact. You need only supply the unique contact identifier that was returned with the contact object upon a successfull creation.

Arguments

Field Type Required Description
id string Yes The identifier of the contact to be retrieved.

Returns

Returns a contact object if a valid identifier was provided.

Update a contact

Definition

POST https://api.previsto.io/contacts/{CONTACT_ID}

Example Request

curl https://api.previsto.io/contacts/cot_123123123 \
   -u sk_12345: \
   -d phone=+4522123456

Example Response

{
    "id": "con_123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the address parameter, that becomes the contact's new address.

This request accepts mostly the same arguments as the contact creation call.

Arguments

Field Type Required Description
name string Yes The name of the contact. Can be either a company name or a person's name.
address string No The street address, 'fx. Vesterbro 11'
appartment string No The apartment, 'fx. 1. th'
postalCode string No -
city string No -
countryCode string No 2-letter ISO 3166-1 code, fx. 'DK'
location number[] Yes Array of length 2 holding longitude and latitude in specified order. (Fx. [11.543540954589844, 56.703469017862034])
number integer No Arbitrary number (or string) that contacts can be referred to by.
phone string No Full international phonenumber, fx. '+4522123456'
email string No -
registrationNo string No The contact's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
ean string No The contact's EAN (European Article Number).
accountingMode string No None, AddToDraft or AddToInvoice.
accountingTime string No BeforeWork or AfterWork.
invoiceDelivery string No None or Email.
payingContactId string No Id of another contact that pays assignments for this contact or null.
note string No -
notifyBeforeWork boolean No Flag that defines if contact should be notified of work or not.
meta object No Dictionary of meta value.

Returns

Returns the contact object if the update succeeded. Returns an error if update parameters are invalid.

Delete a contact

Definition

DELETE https://api.previsto.io/contacts/{CONTACT_ID}

Example Request

curl https://api.previsto.io/contacts/con_123123123 \
   -u sk_12345: \
   -X DELETE

Permanently deletes a contact. It cannot be undone.

Arguments

Field Type Required Description
id string Yes The identifier of the contact to be deleted.

Returns

Returns an empty response upon success. If the contact ID does not exist, this call returns an error.

List all contacts

Definition

GET https://api.previsto.io/contacts

Example Request

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

Example Response

[
    {
        "id": "con_123123123",
        "name": "Anna Jensen",
        "address": "Kundevej 2",
        "appartment": null,
        "postalCode": "4321",
        "city": "Kundeby",
        "countryCode": "DK",
        "location" : [ 10.5286863, 56.8039035 ],
        "number": null,
        "remoteId": null,
        "remoteOrderId": null,
        "phone": "+452209876543",
        "email": "anna@jensen.dk",
        "registrationNo": null,
        "ean": null,
        "accountingMode": null,
        "accountingTime": null,
        "invoiceDelivery": null,
        "notifyBeforeWork": false,
        "archived": false,
        "agentIds": [],
        "meta": {
            "hairColor": "Brown"
        }
    },
    {  },
    {  },
    "... And then as many results as available or requested"

]

Returns a list of your contacts.

Arguments

Field Optional Explained
size Yes A limit on the number of objects to be returned. Size can range between 1 and 100 items. Default size 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.
search Yes A free text search field. Cannot be used in combination with nearby.
nearby Yes Sorts the result by the distance to a given coordinate, fx. '?nearby=-7.437336444854736,62.11042750510291'. Cannot be used in combination with search.

Returns

An array of up to limit contacts, starting after offset. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. This request should never return an error.

Agreement

An Agreement is when the Organization and a Contact has agreed upon a specific assignment to be completed for a specific sum of money. The Agreement can be for a single assignment or for a recurring assignment.

The agreements will automatically be reflected in Assignment. For example if an Agreement has been a recurring interval each monday then the system will automatically generate assignments for that agreement each monday. The assignments can be changed as needed, but if the Agreement is updated, new assignments will be generated from that date and forward – overwriting any changes to the assignments.

Fixed planning

If planningDateType for an agreement is set to Fixed then planningDate defines a specific date for the next assignment. This is often used when a customer has been promised that the work will be fulfilled at a specific date or when existing customers are being created in Previsto for the first time.

If recurrenceRule is defined for an agreement with fixed planning, then planningDateType will automatically change to Optimal when work has ben marked as handled for this agreement. (See Assignment)

Optimal planning

If planningDateType for an agreement is set to Optimal then planningDate is ignored. Based on historical data Previsto will create assignments according to the interval defined in recurrenceRule.

If no historical data for the agreement exists yet then Previsto will look for a day within the next month that has work planned close to the contact of the agreement.

Supplementary agreements

By default the type of agreement will be Primary, but it can also be specified as Supplementary. Supplementary agreements will only generate assignments together with Primary assignments at the same Contact. Previsto will find the assignment at the Contact closest to the optimal date and plan it together with it.

This makes it possible to define work that should never be planned by itself, but only when other primary work is planned also. For example a Window Cleaner might clean windows of a house both inside and outside. If the inside windows are done with another interval than the outside windows then 2 agreements should be created to define those intervals. But the window cleaner would want the cleaning of the inside windows to always be planned together with cleaning of the outside windows. He can make sure of that by defining the cleaning of the outside windows as Primary and cleaning of the inside windows as Supplementary.

The agreement object

Example Response

{
    "id": "agt_123123123",
    "description": "Window Cleaning",
    "note": "Remember to close the gate.",
    "amount": 23900,
    "contactId": "cont_1231231321",
    "recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
    "type": "Primary",
    "workType": "WindowCleaning",
    "duration": 15,
    "planningDateType": "Fixed",
    "planningDate": "2017-12-04",
    "archived": false,
    "meta": {
        "Note": "Good Deal"
    }
}
Field Type Required Description
id string No -
description string Yes Short public description of the agreement. Will be used invoices etc.
note string Yes Private description of the agreement. Message only to be shown to employees.
amount number No The amount agreed upon in 1⁄100 of the monetary unit (fx. cents or øre)
contactId string Yes The contact that has entered into agreement with.
recurrenceRule string No The iCal(RFC 2445) RRule specifying optional reccurence.
type string No The type of agreement. 'Primary'(default) or 'Supplementary'.
workType string No The type of work. Currently only 'WindowCleaning'.
duration number Yes The expected duration in minutes of the work. Minimum 3 minutes.
planningDateType string No The type of planning for this agreement. 'Fixed' to specifiy a specific date for next planning or 'Optimal' to have the system find most optimal date.
planningDate date No If planningDateType is 'Fixed' then this property defines the date, otherwise ignored.
archived boolean No -
meta object No Dictionary of meta value.

Create an agreement

Definition

POST https://api.previsto.io/agreements
`

Example Request

curl https://api.previsto.io/agreements \
   -u sk_12345: \
   -d description="Window Cleaning" \
   -d contactId=cot_1231233123 \
   -d meta[note]="Good Deal"

Example Response

{
    "id": "agt_123123123",
    "description": "Window Cleaning",
    "note": "Remember to close the gate.",
    "amount": 23900,
    "contactId": "cont_1231231321",
    "recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
    "type": "Primary",
    "workType": "WindowCleaning",
    "duration": 15,
    "planningDateType": "Fixed",
    "planningDate": "2017-12-04",
    "archived": false,
    "meta": {
        "Note": "Good Deal"
    }
}

Creates a new agreement.

Arguments

Field Type Required Description
description string No Short description of the agreement.
amount number No The amount agreed upon.
currency string Yes 3-letter ISO 4217 code, fx. 'DKK'
contactId string Yes The contact that has entered into agreement with.
recurrenceRule string No The iCal(RFC 2445) RRule specifying optional reccurence.
startDate date Yes The start of the agreement.
endDate date No The end of the agreement.
previousDate date no The previous date work was done, if any.
nextDate date No The next date to accomplish work, if planned.
accountId string No Id of the employee that is the caretaker of the agreement.
meta object No Dictionary of meta value.

Returns

Returns an agreement object if the call succeeded. If a invalid parameters are provided, the call will return an error.

Retrieve an agreement

Definition

GET https://api.previsto.io/agreements/{AGREEMENT_ID}

Example Request

curl https://api.previsto.io/agreements/agt_123123123 \
   -u sk_12345:

Example Response

{
    "id": "agt_123123123",
    "description": "Window Cleaning",
    "note": null,
    "amount": 23900,
    "contactId": "cont_1231231321",
    "recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
    "type": "Primary",
    "workType": "WindowCleaning",
    "duration": 15,
    "planningDateType": "Fixed",
    "planningDate": "2017-12-04",
    "archived": false,
    "meta": {
        "Note": "Good Deal"
    }
}

Retrieves the details of an existing agreement. You need only supply the unique agreement identifier that was returned with the agreement object upon a successfull creation.

Arguments

Field Type Required Description
id string Yes The identifier of the agreement to be retrieved.

Returns

Returns an agreement object if a valid identifier was provided.

Update an agreement

Definition

POST https://api.previsto.io/agreements/{AGREEMENT_ID}

Example Request

curl https://api.previsto.io/agreements/agt_123123123 \
   -u sk_12345: \
   -d description="Window Cleaning Outside"

Example Response

{
    "id": "agt_123123123",
    "description": "Window Cleaning Outside",
    "note": null,
    "amount": 23900,
    "contactId": "cont_1231231321",
    "recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
    "type": "Primary",
    "workType": "WindowCleaning",
    "duration": 15,
    "planningDateType": "Fixed",
    "planningDate": "2017-12-04",
    "archived": false,
    "meta": {
        "Note": "Good Deal"
    }
}

Updates the specified agreement by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the amount parameter, that becomes the agreements's new amount.

This request accepts mostly the same arguments as the agreement creation call.

Arguments

Field Type Required Description
description string No Short description of the agreement.
amount number No The amount agreed upon.
currency string Yes 3-letter ISO 4217 code, fx. 'DKK'
contactId string Yes The contact that has entered into agreement with.
recurrenceRule string No The iCal(RFC 2445) RRule specifying optional reccurence.
startDate date No The start of the agreement.
endDate date No The end of the agreement.
previousDate date no The previous date work was done, if any.
nextDate date No The next date to accomplish work, if planned.
accountId string No Id of the employee that is the caretaker of the agreement.
meta object No Dictionary of meta value.

Returns

Returns the agreement object if the update succeeded. Returns an error if update parameters are invalid.

Delete an agreement

Definition

DELETE https://api.previsto.io/agreements/{AGREEMENT_ID}

Example Request

curl https://api.previsto.io/agreements/agt_123123123 \
   -u sk_12345: \
   -X DELETE

Permanently deletes an agreement. It cannot be undone.

Arguments

Field Type Required Description
id string Yes The identifier of the agreement to be deleted.

Returns

Returns an empty response upon success. If the agreement ID does not exist, this call returns an error.

List all agreements

Definition

GET https://api.previsto.io/agreements

Example Request

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

Example Response

[
    {
        "id": "agt_123123123",
        "description": "Window Cleaning Outside",
        "amount": 23900,
        "currency": "DKK",
        "contactId": "cot_1231231321",
        "recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
        "startDate": "2015-01-01",
        "endDate": null,
        "previousDate": null,
        "nextDate": null,
        "archived": false,
        "accountId": null,
        "meta": {
            "note": "Good Deal"
        }
    },
    {  },
    {  },
    "... And then as many results as available or requested"

]

Returns a list of your agreements.

Arguments

Field Optional Explained
size Yes A limit on the number of objects to be returned. Size can range between 1 and 100 items. Default size 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.

Returns

An array of up to limit agreements, starting after offset. Each entry in the array is a separate agreement object. If no more agreements are available, the resulting array will be empty. This request should never return an error.

Assignment

Assignments are planned work, either autogenerated based on Agreements or manually created. Assignments are kept even after work has completed and then functions as a history of the work that has been executed, by whom, when etc.

If the organization is connected to a financial system then Previsto will do bookkeeping in the financial system for the assignments.

The assignment object

Example Response

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : "cont-242342DgHH2lkjkj23",
  "accountId" : "acct-dfEfdv3342FD",
  "action" : "None",
  "remoteOrderId" : null,
  "timestamp" : "2017-05-31T08:05",
  "location" : [ 10.5286863, 56.8039035 ],
  "status" : "None",
  "planningDate" : "2017-05-29",
  "planningAccountIds" : [],
  "planningDateType" : "Optimal",
  "tasks" : [ {
    "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
    "description" : "Pudsning2",
    "amount" : 20000,
    "duration" : 16,
    "workType" : "WindowCleaning"
  } ]
}
Field Type Required Description
id string No -
createdDate date No Date of creation.
contactId string Yes Id of the contact related to this assignment.
payingContactId string No Id of the contact paying for this assignment.
accountId string Yes Id of the account that reflects the worker that is scheduled to execute the assignment.
action string No Action taken on the assignment. None, Skippedor Completed.
remoteOrderId string No Id of the order created in the financial system.
timestamp date Yes The planned time for handling this assignment.
location number[] Yes Array of 2 numbers holding longitude and latitude in specified order according to geojson syntax. (Fx. [11.543540954589844, 56.703469017862034])
status string No Financial status of this assignment. None, AppendedToOrder, Invoiced or Fulfilled.
planningDate date No Date for guiding planning of timestamp.
planningDateType string No Fixed for planning timestamp exact date of planningDate or Optimal for flexible planning that allows optimizing routes by planning timestamp some day within the same week as planningDate.
planningAccountIds string[] No Ids of accounts reflecting the workers that should handle this assignment. Empty list allows all accounts.
tasks task[] No Array of task elements in this assignments.

The task object

Field Type Required Description
agreementId string No Id of the agreement behind this task.
description string No Description of the work.
amount number No The amount to charge in 1⁄100 of the monetary unit (fx. cents or øre) without VAT.
duration number No The duration in minutes of the work. Minimum 3 minutes.
workType string No The type of work. Currently only 'WindowCleaning'.

Create an assignment

Definition

POST https://api.previsto.io/assignments
`

Example Request

curl -X POST https://api.previsto.io/assignments \
   -u sk_12345: \
   -d contactId="cont-242342DgHH2lkjkj23" \
   -d accountId="acct-dfEfdv3342FD"

Example Response

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : "cont-242342DgHH2lkjkj23",
  "accountId" : "acct-dfEfdv3342FD",
  "action" : "None",
  "remoteOrderId" : null,
  "timestamp" : "2017-05-31T08:05",
  "location" : [ 10.5286863, 56.8039035 ],
  "status" : "None",
  "planningDate" : "2017-05-29",
  "planningAccountIds" : [],
  "planningDateType" : "Optimal",
  "tasks" : [ ]
}

Creates a new assignment.

Arguments

TBD

Returns

Returns an assignment object if the call succeeded. If invalid arguments are provided, the call will return an error.

Retrieve an assignment

Definition

GET https://api.previsto.io/assignments/{assignment_ID}

Example Request

curl https://api.previsto.io/assignments/asgmt-klJ23j4L23j43 \
   -u sk_12345:

Example Response

{
    "id": "asgmt-klJ23j4L23j43",
    "type": "Sale",
    "number": "1344",
    "contactId": null,
    "contactName": null,
    "contactAddress": null,
    "contactCountryCode": null,
    "notes": null,
    "date": "2015-01-01",
    "dueDate": "2015-01-09",
    "creditAssignmentId": null,
    "state": "draft",
    "currency": "DKK",
    "balance": 0,
    "paid": false,
    "assignmentHolderId": null,
    "paymentTermsDays": 14,
    "lines": [ ]
}

Retrieves the details of an existing assignment. You need only supply the unique assignment identifier that was returned with the assignment object upon a successfull creation.

Arguments

Field Type Required Description
id string Yes The identifier of the assignment to be retrieved.

Returns

Returns an assignment object if a valid identifier was provided.

Update an assignment

Definition

POST https://api.previsto.io/assignments/{assignment_ID}

Example Request

curl https://api.previsto.io/assignments/_123123123 \
   -u sk_12345: \
   -d number=1345

Example Response

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : "cont-242342DgHH2lkjkj23",
  "accountId" : "acct-dfEfdv3342FD",
  "action" : "None",
  "remoteOrderId" : null,
  "timestamp" : "2017-05-31T08:05",
  "location" : [ 10.5286863, 56.8039035 ],
  "status" : "None",
  "planningDate" : "2017-05-29",
  "planningAccountIds" : [],
  "planningDateType" : "Optimal",
  "tasks" : [ {
    "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
    "description" : "Pudsning2",
    "amount" : 20000,
    "duration" : 16,
    "workType" : "WindowCleaning"
  } ]
}

Updates the specified assignment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the number parameter, that becomes the assignment's new assignment number.

This request accepts mostly the same arguments as the assignment creation call.

Arguments

TBD

Returns

Returns the assignment object if the update succeeded. Returns an error if update parameters are invalid.

Delete an assignment

Definition

DELETE https://api.previsto.io/assignments/{assignment_ID}

Example Request

curl https://api.previsto.io/assignments/asgmt-klJ23j4L23j43 \
   -u sk_12345: \
   -X DELETE

Permanently deletes an assignment. It cannot be undone.

Arguments

Field Type Required Description
id string Yes The identifier of the assignment to be delete.

Returns

Returns an empty response upon success. If the assignment ID does not exist, this call returns an error.

List all assignments

Definition

GET https://api.previsto.io/assignments

Example Request

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

Example Response

[
    {
        "id" : "asgmt-klJ23j4L23j43",
        "createdDate" : "2017-05-21T20:22:28.110Z",
        "meta" : { },
        "contactId" : "cont-242342DgHH2lkjkj23",
        "payingContactId" : "cont-242342DgHH2lkjkj23",
        "accountId" : "acct-dfEfdv3342FD",
        "action" : "None",
        "remoteOrderId" : null,
        "timestamp" : "2017-05-31T08:05",
        "location" : [ 10.5286863, 56.8039035 ],
        "status" : "None",
        "planningDate" : "2017-05-29",
        "planningAccountIds" : [],
        "planningDateType" : "Optimal",
        "tasks" : [ {
            "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
            "description" : "Pudsning2",
            "amount" : 20000,
            "duration" : 16,
            "workType" : "WindowCleaning"
        } ]
    },
    {  },
    {  },
    "... And then as many results as available or requested"

]

Returns a list of your assignments.

Arguments

Field Optional Explained
size Yes A limit on the number of objects to be returned. Size can range between 1 and 100 items. Default size 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 assignment to fetch the next page of the list.

Returns

An array of up to limit assignments, starting after offset. Each entry in the array is a separate assignment object. If no more assignments are available, the resulting array will be empty. This request should never return an error.

Retrieve summaries

TBD

Get previous assignments for agreements

TBD

Get next assignments for agreements

TBD

Pin assignments

TBD

Defer assignments

TBD

Mark assignments handled

TBD