How to send Data to Plecto's API

In a few simple steps, this guide will show you how to send data to Plecto's API.

What is the Plecto API?

The Plecto API is a way for other software to communicate with Plecto. In a nutshell, the API allows Plecto to be integrated directly in other systems.

The Plecto API can be used for posting new data to Plecto. In other words, this means that other systems can export their data to Plecto.

To manually use the Plecto API, a free piece of software like Postman is useful, but any software capable of sending HTTP requests is supported. 

Endpoints:

The Plecto API has the base URL of: https://app.plecto.com/api/v2/ 

If you’re logged in with your account, you can browse the API directly in the browser. This URL is the basis for all endpoints to the Plecto API. 

Send data to Plecto:

It is possible to send any data to Plecto, and we recommend you post data to an API data source.

 

To send data to the Plecto API, a POST method has to be used. A POST request allows you to send additional information in the request body (consider it a multi-row text field). This request body contains all the relevant data to create (or update) a registration.

The request body has a few mandatory fields which all have to be included in every request:

  • Data source: Refers to the unique UUID of a data source. This alphanumerical string can be found in the URL of the data source detail page.
  • Member: Refers to the UUID of an organization member in Plecto. Similarly to the data source, this UUID can be found as the alphanumerical part of the URL of the member detail page.
  • External ID: is a number or string of characters that has to be unique for the registration. It could be something like 123, abc or anything you can think of. This is important as it will be the reference of the created registration. If the external ID is the same as an existing registration, the existing one will be overwritten entirely by the new information.

 

Example of the data source detail page and where to find the unique UUID of a data source.

 

On an API data source you can see example API integration code for Python, Ruby, PHP and C#.

Here is a Pyton example:

 

Screenshot 2019-09-11 at 15.58.54

A simple example:

The request to create a registration for the data source has to use the URL for the registrations endpoint: https://app.plecto.com/api/v2/registrations/

The mandatory fields have to be included in the post body as well as an entry for 'value'.


Assume the data source has a UUID of 0703ac00280e41f8b8ecef57a36e85be, the member has a UUID of 3b7aaf488d774de6804c7a2af1498509 and the external ID is 1337. Then the code for a registration with a 'value' of 100 would become (Python example):

{

        data_source: '0703ac00280e41f8b8ecef57a36e85be', 

        member: '3b7aaf488d774de6804c7a2af1498509',

        date: '2012-13-13T00:00:00', 

        value: '100',

        'external_id': '1337' 

}

 

If the authentication passes and the request is correct, Plecto will accept the registration and return a success response (where 'id' is the UUID of the newly created (or updated) registration).

 

This is what the registration will look like in the registration list of the data source. 


Please note: 
The date format has to be of the standard ISO 8601 with both date and time. The format has to look like: 2018-12-31T22:33:44+00:00
Where the last part after + is an optional time zone. If not set, the timezone is assumed to be UTC.

Bulk insertion

The Plecto API supports sending a list of registrations in a single request body. In effect the request body will look like:

[
{
"data_source": "60577787cc214b6b8d3620920e73bd60",
"member": "fa52aeb5c3fe431ba4affc0be75fd73c",
"external_id": "1337"
},
{
"data_source": "60577787cc214b6b8d3620920e73bd60",
"member": "fa52aeb5c3fe431ba4affc0be75fd73c",
"external_id": "1338"
}
]

The Plecto API enforces limits for how many registrations can be in a single request.

 

Important: You cannot send multiple registrations with the same external_id in the same bulk requisition. If that happens, you will get the following error:

{

”message”: ”Duplicated registrations found”,

”id”: “<your id>”

}