How to Send Data to Plecto's API

What is Plecto API?

The Plecto API allows developers to create a custom advanced integration that enables other software to communicate with our platform and export their data to Plecto.

If you want to test the Plecto API manually, you can use a free piece of software like Postman, but any other tool capable of sending HTTP requests is also supported.

Authentication

• The authentication scheme used for the Plecto API is Basic Authentication. It includes sending your email and password along with the request.

• Tip! 💡 We recommend creating a new user (new employee profile) per integration in your Plecto organization – this way, you'll avoid sharing the same password across integrations.

• The user must have access to the relevant areas of Plecto to succeed with most API endpoints. If your Plecto subscription includes advanced permission management, you can create a specific permission profile for the user account.

To create new employees, go to Settings > Employees > New employee in Plecto or add them through an API request.

Base URL and Endpoints

All Plecto API endpoints are listed under the following base URL: https://app.plecto.com/api/v2/

This URL is the basis for all endpoints of the Plecto API. If you are logged into your Plecto account, you can see the list of API endpoints directly in the browser.

How to create an API data source

You can create an API data source in two ways:

• Post a request to this endpoint: https://app.plecto.com/api/v2/datasources/ It is enough to include "title" and "fields" keys in the request to create the data source.

• Or go to Data sources > New data source > Plecto API and create a new data source from the Plecto interface.

You can run a test using the request body from above.

Adding more fields

If you need to add more fields to your API data source, you'll have to do it through the UI in your data source settings. We currently don't support updating fields via the API.

Adding registrations: Mandatory keys

Endpoint: https://app.plecto.com/api/v2/registrations/

The request body above shows how to add multiple registrations at once. If you want to use it, make sure to add the data_source and member UUIDs from your organization.

Mandatory keys to include for each registration

There are 3 mandatory keys that must be included in the request body for every API request that you send. The keys are the following:

1. data_source,

2. member (or member_api_provider, member_api_id, and member_name), and

3. external_id.

Can I use the same external ID?

If you send a request with the same external ID as you have already used, it will overwrite an existing registration in Plecto and display the new updated information.

Naming conventions – don't get confused!

• The member_api_id key in your request body represents the External ID shown in the employee profile in Plecto, and the external_id key represents the Registration ID in a Plecto data source.

Bulk registrations

• If you want to assign multiple registrations to the same user, you can use the same member_api_id. However, the external_id key needs to be different for each registration, unless you want to overwrite an existing registration with new data.

Basic example: Adding registrations via API

Let's send new registrations to a Plecto data source!

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

• The POST request body must include the mandatory keys plus a key called "Value," since the data source in Plecto has a custom field added to it called Value.

If the authentication passes and the request is correct, Plecto will accept the registration and return a successful response. In the response, the "id" is the UUID of the newly-created or updated registration in Plecto.

Bulk insertion

The Plecto API supports sending a list of registrations in a single request body. However, the API also enforces a limit of 100 registrations you can send in a single request.

Above is an example of what a request body could look like.

Note on external IDs

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>" }

Learn how to create employees in Plecto in this article: How to Add Employees to Plecto via API

How to update existing data via API

Endpoint: https://app.plecto.com/api/v2/registrations/

• The data_source and external_id identify a registration in a data source in Plecto. The external_id represents the registration ID in Plecto. If you want to update the registration values, send a request using the same data_source and external_id keys but change the field values.

• The member_api_provider and member_api_id identify an employee in Plecto. If you want to update the employee name, you can send the same request but change the member_name value from, for example, "Employee X" to "Curtis Miller."

• You can send a date field to Plecto (optional). It will show in the Created date field in your data source. Whenever you send a registration, Plecto automatically adds the current date and time to it. If you want to update a registration but keep the original date and time, add the following key to your request body: "date": "2022-12-31T10:22:55"

Date format

If you include a date key in the request body, the date format has to be of the standard ISO 8601 with both date and time.

The format has to look like this: 2018-12-31T22:33:44+00:00 The last part after + is an optional time zone. If not set, the timezone is assumed to be UTC.

Overview of Plecto API Endpoints →