Contacts

Contacts are a core part of Previsto — a main reason Previsto exists is to plan work to do for your contacts. On this page, we'll dive into the different contact endpoints you can use to manage contacts programmatically. We'll look at how to query, create, update, and delete contacts.

The contact object

Example Response

{
    "id": "cont-123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the contact.

  • Name
    name
    Type
    string
    Required
    required
    Description

    The name of the contact. Can be either a company name or a person's name.

  • Name
    address
    Type
    string
    Description

    street address, 'fx. Vesterbro 11'

  • Name
    appartment
    Type
    string
    Description
    Apartment, fx. '1. th.'
  • Name
    postalCode
    Type
    string
    Description
    -
  • Name
    city
    Type
    string
    Description
    -
  • Name
    countryCode
    Type
    string
    Description
    2-letter ISO 3166-1 code, fx. 'DK'
  • Name
    location
    Type
    number[]
    Required
    required
    Description
    Array of length 2 holding longitude and latitude in specified order. (Fx. [11.543540954589844, 56.703469017862034])
  • Name
    number
    Type
    string
    Description
    Arbitrary number (or string) that contacts can be referred to by.
  • Name
    phone
    Type
    string
    Description
    Full international phonenumber, fx. '+4522123456'
  • Name
    email
    Type
    string
    Description
    -
  • Name
    registrationNo
    Type
    string
    Description
    The contact's EU VAT number, CVR number in Denmark, TIN/EIN/SSN in US.
  • Name
    ean
    Type
    string
    Description
    The contact's EAN (European Article Number).
  • Name
    accountingMode
    Type
    string
    Description
    None, AddToDraft or AddToInvoice.
  • Name
    accountingTime
    Type
    string
    Description
    BeforeWork or AfterWork.
  • Name
    invoiceDelivery
    Type
    string
    Description
    None or Email.
  • Name
    payingContactId
    Type
    string
    Description
    Id of another contact that pays assignments for this contact or null.
  • Name
    note
    Type
    string
    Description
    -
  • Name
    notifyBeforeWork
    Type
    boolean
    Description
    Flag that defines if contact should be notified of work or not.
  • Name
    archived
    Type
    boolean
    Description
    -
  • Name
    agentIds
    Type
    string[]
    Description
    Ids of the agents that takes care of this contact. Currently always account Ids. Empty list means that it is not specified.
  • Name
    meta
    Type
    object
    Description
    Dictionary of meta value.

GET/contacts

List all contacts

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

Optional attributes

  • Name
    size
    Type
    integer
    Description

    Limit the number of contacts returned.

Request

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

Response

[
  {
      "id": "cont-123123123",
      "name": "Anna Jensen",
      "address": "Kundevej 2",
      "appartment": null,
      "postalCode": "4321",
      "city": "Kundeby",
      "countryCode": "DK",
      "location" : [ 10.5286863, 56.8039035 ],
      "number": null,
      "remoteId": null,
      "remoteOrderId": null,
      "phone": "+452209876543",
      "email": "anna@jensen.dk",
      "registrationNo": null,
      "ean": null,
      "accountingMode": null,
      "accountingTime": null,
      "invoiceDelivery": null,
      "notifyBeforeWork": false,
      "archived": false,
      "agentIds": [],
      "meta": {
          "hairColor": "Brown"
      }
  }
]

POST/contacts

Create a contact

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

Request

POST
/contacts
curl https://api.previsto.io/contacts \
  -u sk_12345 
  -d name="Anna Jensen" \
  -d meta[hairColor]=Brown

Response

{
    "id": "cont-123123123",
    "name": "Anna Jensen",
    "address": null,
    "appartment": null,
    "postalCode": null,
    "city": null,
    "countryCode": null,
    "location" : [ 0, 0 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": null,
    "email": null,
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

GET/contacts/:id

Retrieve a contact

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
/contacts/cont-123123123
curl https://api.previsto.io/contacts/cont-123123123 \
  -u sk_12345

Response

{
    "id": "cont-123123123",
    "name": "Anna Jensen",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

PUT/contacts/:id

Update a contact

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

Optional attributes

  • Name
    display_name
    Type
    string
    Description

    The contact display name in the contact list. By default, this is just the username.

Request

PUT
/contacts/cont-123123123
curl -X PUT https://api.previsto.io/contacts/cont-123123123 \
  -u sk_12345 \
  -d name="Uncle Frank"

Response

{
    "id": "cont-123123123",
    "name": "Uncle Frank",
    "address": "Kundevej 2",
    "appartment": null,
    "postalCode": "4321",
    "city": "Kundeby",
    "countryCode": "DK",
    "location" : [ 10.5286863, 56.8039035 ],
    "number": null,
    "remoteId": null,
    "remoteOrderId": null,
    "phone": "+452209876543",
    "email": "anna@jensen.dk",
    "registrationNo": null,
    "ean": null,
    "accountingMode": null,
    "accountingTime": null,
    "invoiceDelivery": null,
    "notifyBeforeWork": false,
    "archived": false,
    "agentIds": [],
    "meta": {
        "hairColor": "Brown"
    }
}

DELETE/contacts/:id

Delete a contact

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

Request

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