Assignments

Assignments in Previsto is what the planning evolves around. All work planned is assignments creates in the system. On this page, we'll dive into the different assignments endpoints you can use to manage assignments programmatically. We'll look at how to query, send, update, and delete assignments.

The assignment model

The assignment model contains all the information about the assignment you plan in the system.

The assignment object 

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : "cont-242342DgHH2lkjkj23",
  "accountId" : "acct-dfEfdv3342FD",
  "action" : "None",
  "remoteOrderId" : null,
  "location" : [ 10.5286863, 56.8039035 ],
  "status" : "None",
  "plan": {
    "executionTime" : "2017-05-31T08:05",
    "indicativeDate" : "2017-05-29",
    "accountIds" : [],
    "indicativeDateType" : "Optimal",
  },
  "tasks" : [ {
    "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
    "description" : "Pudsning2",
    "amount" : 20000,
    "duration" : 16,
    "workType" : "WindowCleaning"
  } ],
  "handledDate": "2017-05-31T08:05",
  "address": {
    "street": "Bornholmsgade 57",
    "apartment": null,
    "postalCode": "9000",
    "city": "Aalborg",
    "countryCode": "DK"
  },
  "deliveryAddress": null
}

Properties for Assignment

  • Name
    createdDate
    Type
    date
    Description
    Date of creation.
  • Name
    contactId
    Type
    string
    Required
    required
    Description
    Id of the contact related to this assignment.
  • Name
    contactName
    Type
    string
    Description
    Name of the contact. If not specified but contactId is specified, contactName will be resolved from the contact.
  • Name
    payingContactId
    Type
    string
    Description
    Id of the contact paying for this assignment.
  • Name
    accountId
    Type
    string
    Required
    required
    Description
    Id of the account that reflects the worker that is scheduled to execute the assignment.
  • Name
    action
    Type
    string
    Description
    Action taken on the assignment. None, Skippedor Completed.
  • Name
    remoteOrderId
    Type
    string
    Description
    Id of the order created in the financial system.
  • Name
    location
    Type
    number\[]
    Description
    Array of 2 numbers holding longitude and latitude in specified order according to geojson syntax. (Fx. [11.543540954589844, 56.703469017862034]). This will automatically be resolved by the system from the address or deliveryAddress on the assignment.
  • Name
    status
    Type
    string
    Description
    Financial status of this assignment. None, AppendedToOrder, Invoiced or Fulfilled.
  • Name
    plan
    Type
    plan
    Description
    Planning details for the assignment.
  • Name
    tasks
    Type
    task[]
    Description
    Array of task elements in this assignments.
  • Name
    address
    Type
    address
    Description
    Address of the contact. If not specified, but contactId is specified, address will be resolved from the Contact.
  • Name
    deliveryAddress
    Type
    address
    Description
    Optionan Delivery address.

Properties for plan

  • Name
    executionTime
    Type
    date
    Description
    The planned time for executing this assignment.
  • Name
    indicativeDate
    Type
    date
    Description
    Date for guiding planning of executionTime.
  • Name
    indicativeDateType
    Type
    string
    Description
    Fixed for planning executionTime exact date of indicativeDate or Optimal for flexible planning that allows optimizing routes by planning executionTime some day within the same week as indicativeDate.
  • Name
    accountIds
    Type
    string\[]
    Description
    Ids of accounts reflecting the workers that is allowed to handle this assignment. Empty list allows all accounts. Optimization will plan the assignment to any of the allowed accounts.

Properties for subtask

  • Name
    reference
    Type
    string
    Description
    Reference for this assignment, fx the id of the agreement that is the base of this assignment.
  • Name
    description
    Type
    string
    Description
    Description of the work.
  • Name
    unitPrice
    Type
    number
    Description
    The amount to charge in 1100 of the monetary unit (fx. cents or ore) without VAT.
  • Name
    duration
    Type
    number
    Description
    The duration in minutes of the work. Minimum 3 minutes.
  • Name
    workType
    Type
    string
    Description
    The type of work. Currently only 'WindowCleaning'.

Properties for address

  • Name
    street
    Type
    string
    Description
    Street and housenumber.
  • Name
    apartment
    Type
    string
    Description
    Apartment information.
  • Name
    postalCode
    Type
    string
    Description
    Postal code for address
  • Name
    city
    Type
    string
    Description
    Nam eof city.
  • Name
    countryCode
    Type
    string
    Description
    Countrycode in ISO 3166-1 alpha-2 format (Fx. US, DK, NO etc.).
GET/assignments

List all assignments

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

Optional attributes

    • Name
      size
      Type
      integer
      Description

      Limit the number of assignments returned.

Request

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

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,
    "location" : [ 10.5286863, 56.8039035 ],
    "status" : "None",
    "plan": {
      "executionTime" : "2017-05-31T08:05",
      "indicativeDate" : "2017-05-29",
      "accountIds" : [],
      "indicativeDateType" : "Optimal",
    },
    "tasks" : [ {
      "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
      "description" : "Pudsning2",
      "amount" : 20000,
      "duration" : 16,
      "workType" : "WindowCleaning"
    } ],
    "handledDate": "2017-05-31T08:05",
    "address": {
      "street": "Bornholmsgade 57",
      "apartment": null,
      "postalCode": "9000",
      "city": "Aalborg",
      "countryCode": "DK"
    },
    "deliveryAddress": null
  }
]
POST/assignments

Create a assignment

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

Request

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

Response

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : null,
  "accountId" : "acct-dfEfdv3342FD",
  "action" : "None",
  "remoteOrderId" : null,
  "location" : [ 0, 0],
  "status" : "None",
  "plan": {
    "executionTime" : "2017-05-31T08:05",
    "indicativeDate" : "2017-05-31",
    "accountIds" : [],
    "indicativeDateType" : "Optimal",
  },
  "tasks" : [  ],
  "handledDate": "2017-05-31T08:05",
  "address": {
    "street": "Bornholmsgade 57",
    "apartment": null,
    "postalCode": "9000",
    "city": "Aalborg",
    "countryCode": "DK"
  },
  "deliveryAddress": null
}
GET/assignments/:id

Retrieve a assignment

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

Request

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

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,
    "location" : [ 10.5286863, 56.8039035 ],
    "status" : "None",
    "plan": {
      "executionTime" : "2017-05-31T08:05",
      "indicativeDate" : "2017-05-29",
      "accountIds" : [],
      "indicativeDateType" : "Optimal",
    },
    "tasks" : [ {
      "agreementId" : "agrmt-DOKwO3VLJ6Sy3YxnlWop",
      "description" : "Pudsning2",
      "amount" : 20000,
      "duration" : 16,
      "workType" : "WindowCleaning"
    } ],
    "handledDate": "2017-05-31T08:05",
    "address": {
      "street": "Bornholmsgade 57",
      "apartment": null,
      "postalCode": "9000",
      "city": "Aalborg",
      "countryCode": "DK"
    },
    "deliveryAddress": null
  }
]
PUT/assignments/:id

Update a assignment

This endpoint allows you to perform an update on a assignment.

Request

PUT
/assignments/asgmt-klJ23j4L23j43
curl -X PUT https://api.previsto.io/assignments/asgmt-klJ23j4L23j43 \
  -u sk_12345 \
  -d accountId="acct-1234321"

Response

{
  "id" : "asgmt-klJ23j4L23j43",
  "createdDate" : "2017-05-21T20:22:28.110Z",
  "meta" : { },
  "contactId" : "cont-242342DgHH2lkjkj23",
  "payingContactId" : null,
  "accountId" : "acct-1234321",
  "action" : "None",
  "remoteOrderId" : null,
  "location" : [ 0, 0],
  "status" : "None",
  "plan": {
    "executionTime" : "2017-05-31T08:05",
    "indicativeDate" : "2017-05-31",
    "accountIds" : [],
    "indicativeDateType" : "Optimal",
  },
  "tasks" : [  ],
  "handledDate": "2017-05-31T08:05",
  "address": {
    "street": "Bornholmsgade 57",
    "apartment": null,
    "postalCode": "9000",
    "city": "Aalborg",
    "countryCode": "DK"
  },
  "deliveryAddress": null
}
DELETE/assignments/:id

Delete a assignment

This endpoint allows you to delete assignments from your assignment list in Previsto.

Request

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