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"
}
}
| 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. |
| 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
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",
"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
| 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.