Service agreements

Service agreements are an essential part of Previsto — they are used for planning recurring assignments for your customers. On this page, we’ll dive into the different service agreement endpoints you can use to manage them programmatically. We'll look at how to query, create, update, and delete service agreements.

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

The Service agreement model

The Service agreement model contains all the information about the agreement between you and your contacts.

Properties

  • Name
    id
    Type
    string
    Description
    -
  • Name
    description
    Type
    string
    Required
    required
    Description
    Short public description of the agreement. Will be used invoices etc.
  • Name
    note
    Type
    string
    Required
    required
    Description
    Private description of the agreement. Message only to be shown to employees.
  • Name
    amount
    Type
    number
    Description
    The amount agreed upon in 1100 of the monetary unit (fx. cents or ore)
  • Name
    contactId
    Type
    string
    Required
    required
    Description
    The contact that has entered into agreement with.
  • Name
    recurrenceRule
    Type
    string
    Description
    The iCal(RFC 2445) RRule specifying optional reccurence.
  • Name
    type
    Type
    string
    Description
    The type of agreement. 'Primary'(default) or 'Supplementary'.
  • Name
    workType
    Type
    string
    Description
    The type of work. Currently only 'WindowCleaning'.
  • Name
    duration
    Type
    number
    Required
    required
    Description
    The expected duration in minutes of the work. Minimum 3 minutes.
  • Name
    planningDateType
    Type
    string
    Description
    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.
  • Name
    planningDate
    Type
    date
    Description
    If planningDateType is 'Fixed' then this property defines the date, otherwise ignored.
  • Name
    archived
    Type
    boolean
    Description
    -
  • Name
    meta
    Type
    object
    Description
    Dictionary of meta value.
GET/agreements

List all agreements

This endpoint allows you to retrieve a paginated list of all your agreements. By default, a maximum of ten agreements are shown per page.

Optional attributes

  • Name
    size
    Type
    integer
    Description

    Limit the number of agreements returned.

Request

GET
/agreements
curl -G https://api.previsto.io/agreements \
  -u sk_12345 \
  -d size=10

Response

[
  {
      "id": "agrmt-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"
      }
  }
]
POST/agreements

Create an agreement

This endpoint allows you to add a new agreement to your agreement list in Previsto.

Request

POST
/agreements
curl https://api.previsto.io/agreements \
  -u sk_12345 
  -d decription="Window Cleaning"
  -d contactId="cont-1231231321

Response

{
    "id": "agrmt-123123123",
    "description": "Window Cleaning",
    "note": null,
    "amount": 0,
    "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": {
    }
}
GET/agreements/:id

Retrieve an agreement

This endpoint allows you to retrieve a agreement by providing their Previsto id. Refer to the list at the top of this page to see which properties are included with agreement objects.

Request

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

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"
    }
}
PUT/agreements/:id

Update an agreement

This endpoint allows you to perform an update on an agreement.

Request

PUT
/agreements/agrmt-123123123
curl -X PUT https://api.previsto.io/agreements/agrmt-123123123 \
  -u sk_12345 \
  -d description="Thorough Cleaning"

Response

{
    "id": "agt_123123123",
    "description": "Thorough 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"
    }
}
DELETE/agreements/:id

Delete an agreement

This endpoint allows you to delete agreements from your contact list in Previsto.

Request

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