When integrating with Plecto, we require you to implement an API which we can fetch data from. Additionally, we highly recommend that you implement webhooks that notify us of interesting changes in real-time. You will need an 'api root' per data type you want to send to us - e.g. one for leads and another for opportunities.

Generally speaking, if you implement an API as described below we are happy to add your an integration to your product to Plecto. If you are planning on creating an API as described below, get in touch at support@plecto.com and let us know you are working on it!

PLEASE NOTE!

  • All datetimes must include timezones.
  • All decimals must be either JSON floats or text with no thousand separators and "." as decimal separator.
  • We prefer oauth2, but it's not required.

Authentication test API

We need an endpoint where we can check if the credentials provided are (still) valid.

Data fetch API

Pagination:

All endpoints must allow pagination, preferably where the page_size is customisable. We will at max import 1000 items per GET request.

Modified date:

We require you to keep track of updates in your system. Plecto will query your API with modified-date-start and modified-date-end - make sure these use the appropriate fields on your end.

Example:
https://yourintegration.com/api/plecto/?modified-date-start=2016-08-01T00:00Z&modified-date-end=2016-08-01T00:00Z&page=1&page_size=500

GET /?modified-date-start=2016-08-01T00:00Z&modified-date-end=2016-08-01T00:00Z&page=1&page_size=500

{
   "results": [
     {
       "employee_id": "123",
       "employee_name": "Hans Andersen",
       "date": "2016-08-01T01:00:00Z",
       "id": "123",
       "deleted": true,
       "Stage": "Closed",
       "Amount": 20000
     },
     {
       "employee_id": "123",
       "employee_name": "Hans Andersen",
       "date": "2016-08-01T01:00:00Z",
       "id": "124",
       "deleted": false,
       "Stage": "Commit",
       "Amount": 10000
     }
   ],
   "pages": 5,
   "next_url": "http:////?modified-date-start=2016-08-01T00:00Z&modified-date-end=2016-08-01T00:00Z&page= 2&page_size=500"
}

Metadata API

GET /meta/

{
   "fields": [
       {
         "id": "121",
         "name": "Stage",
         "deleted": true,
         "type": "Choice",
         "choices": ["Won", "Commit", "Lost"]
       },
       {
         "id": "123",
         "name": "Amount",
         "deleted": false,
         "type": "Decimal"
       }
   ]
}

Example: https://yourintegration.com/api/plecto/meta/

Webhooks (optional)

Work in progress

The specs for webhooks are still being drafted. Get in touch if you want to use this feature now!

You will get a unique URL per data source in Plecto where you can send data in the same format as it is returned above. Then you should send updates the the specified url.

Here is an example request:

JSON

{
  "employee_id": "123",
  "employee_name": "Hans Andersen",
  "date": "2016-08-01T01:00:00Z",
  "id": "123",
  "deleted": true,
  "Stage": "Closed",
  "Amount": 20000
}
Did this answer your question?