Skip to main content

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

{
"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"
}
}
FieldTypeRequiredDescription
idstringNo-
descriptionstringYesShort public description of the agreement. Will be used invoices etc.
notestringYesPrivate description of the agreement. Message only to be shown to employees.
amountnumberNoThe amount agreed upon in 1⁄100 of the monetary unit (fx. cents or øre)
contactIdstringYesThe contact that has entered into agreement with.
recurrenceRulestringNoThe iCal(RFC 2445) RRule specifying optional reccurence.
typestringNoThe type of agreement. 'Primary'(default) or 'Supplementary'.
workTypestringNoThe type of work. Currently only 'WindowCleaning'.
durationnumberYesThe expected duration in minutes of the work. Minimum 3 minutes.
planningDateTypestringNoThe 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.
planningDatedateNoIf planningDateType is 'Fixed' then this property defines the date, otherwise ignored.
archivedbooleanNo-
metaobjectNoDictionary 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

FieldTypeRequiredDescription
descriptionstringNoShort description of the agreement.
amountnumberNoThe amount agreed upon.
currencystringYes3-letter ISO 4217 code, fx. 'DKK'
contactIdstringYesThe contact that has entered into agreement with.
recurrenceRulestringNoThe iCal(RFC 2445) RRule specifying optional reccurence.
startDatedateYesThe start of the agreement.
endDatedateNoThe end of the agreement.
previousDatedatenoThe previous date work was done, if any.
nextDatedateNoThe next date to accomplish work, if planned.
accountIdstringNoId of the employee that is the caretaker of the agreement.
metaobjectNoDictionary 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

FieldTypeRequiredDescription
idstringYesThe 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

FieldTypeRequiredDescription
descriptionstringNoShort description of the agreement.
amountnumberNoThe amount agreed upon.
currencystringYes3-letter ISO 4217 code, fx. 'DKK'
contactIdstringYesThe contact that has entered into agreement with.
recurrenceRulestringNoThe iCal(RFC 2445) RRule specifying optional reccurence.
startDatedateNoThe start of the agreement.
endDatedateNoThe end of the agreement.
accountIdstringNoId of the employee that is the caretaker of the agreement.
metaobjectNoDictionary of meta value.
typestringNoType 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

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

FieldTypeRequiredDescription
idstringYesThe 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",
"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"
}
},
{ },
{ },
"... And then as many results as available or requested"

]

Returns a list of your agreements.

Arguments

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

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.