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 Primaryassignments 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
1
{
2
"id": "agt_123123123",
3
"description": "Window Cleaning",
4
"note": "Remember to close the gate.",
5
"amount": 23900,
6
"contactId": "cont_1231231321",
7
"recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
8
"type": "Primary",
9
"workType": "WindowCleaning",
10
"duration": 15,
11
"planningDateType": "Fixed",
12
"planningDate": "2017-12-04",
13
"archived": false,
14
"meta": {
15
"Note": "Good Deal"
16
}
17
}
Copied!
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
1
POST https://api.previsto.io/agreements
2
`
Copied!
Example Request
1
curl https://api.previsto.io/agreements \
2
-u sk_12345: \
3
-d description="Window Cleaning" \
4
-d contactId=cot_1231233123 \
5
-d meta[note]="Good Deal"
Copied!
Example Response
1
{
2
"id": "agt_123123123",
3
"description": "Window Cleaning",
4
"note": "Remember to close the gate.",
5
"amount": 23900,
6
"contactId": "cont_1231231321",
7
"recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
8
"type": "Primary",
9
"workType": "WindowCleaning",
10
"duration": 15,
11
"planningDateType": "Fixed",
12
"planningDate": "2017-12-04",
13
"archived": false,
14
"meta": {
15
"Note": "Good Deal"
16
}
17
}
Copied!
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
1
GET https://api.previsto.io/agreements/{AGREEMENT_ID}
Copied!
Example Request
1
curl https://api.previsto.io/agreements/agt_123123123 \
2
-u sk_12345:
Copied!
Example Response
1
{
2
"id": "agt_123123123",
3
"description": "Window Cleaning",
4
"note": null,
5
"amount": 23900,
6
"contactId": "cont_1231231321",
7
"recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
8
"type": "Primary",
9
"workType": "WindowCleaning",
10
"duration": 15,
11
"planningDateType": "Fixed",
12
"planningDate": "2017-12-04",
13
"archived": false,
14
"meta": {
15
"Note": "Good Deal"
16
}
17
}
Copied!
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
1
POST https://api.previsto.io/agreements/{AGREEMENT_ID}
Copied!
Example Request
1
curl https://api.previsto.io/agreements/agt_123123123 \
2
-u sk_12345: \
3
-d description="Window Cleaning Outside"
Copied!
Example Response
1
{
2
"id": "agt_123123123",
3
"description": "Window Cleaning Outside",
4
"note": null,
5
"amount": 23900,
6
"contactId": "cont_1231231321",
7
"recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
8
"type": "Primary",
9
"workType": "WindowCleaning",
10
"duration": 15,
11
"planningDateType": "Fixed",
12
"planningDate": "2017-12-04",
13
"archived": false,
14
"meta": {
15
"Note": "Good Deal"
16
}
17
}
Copied!
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.
accountId
string
No
Id of the employee that is the caretaker of the agreement.
meta
object
No
Dictionary of meta value.
type
string
No
Type of agreement. 'Primary' or 'Supplementary'.

Returns

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

Delete an agreement

Definition
1
DELETE https://api.previsto.io/agreements/{AGREEMENT_ID}
Copied!
Example Request
1
curl https://api.previsto.io/agreements/agt_123123123 \
2
-u sk_12345: \
3
-X DELETE
Copied!
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
1
GET https://api.previsto.io/agreements
Copied!
Example Request
1
curl https://api.previsto.io/agreements \
2
-u sk_12345:
Copied!
Example Response
1
[
2
{
3
"id": "agt_123123123",
4
"description": "Window Cleaning",
5
"note": "Remember to close the gate.",
6
"amount": 23900,
7
"contactId": "cont_1231231321",
8
"recurrenceRule": "FREQ=WEEKLY;INTERVAL=4;WKST=MO",
9
"type": "Primary",
10
"workType": "WindowCleaning",
11
"duration": 15,
12
"planningDateType": "Fixed",
13
"planningDate": "2017-12-04",
14
"archived": false,
15
"meta": {
16
"Note": "Good Deal"
17
}
18
},
19
{ },
20
{ },
21
"... And then as many results as available or requested"
22
23
]
Copied!
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.