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[]
Description
Array of length 2 holding longitude and latitude in specified order. (Fx. [11.543540954589844, 56.703469017862034]). Will be resolved by the system from the specified address.
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