How to Send Data to Plecto's API

The Plecto API allows developers to create a custom advanced integration that enables other software to communicate with Plecto 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 software capable of sending HTTP requests is also supported.

The authentication scheme used for the Plecto API is Basic Authentication. This authentication scheme includes sending your username (email) and password along with the request.

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

1. Go to Organization > Employees > + New employee.

The user must have access to the relevant areas of Plecto to succeed with most API endpoints. If you have access to advanced permission management, you can create a specific permission profile for the user account. We always recommend to create a user with the minimum required level of access for the purpose of your integration.

Plecto API has 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.

Go to Data management > Data sources > + New data source > Plecto API. From there, you can customize your data source settings, add fields (optional), and see example API integration code in Python, Ruby, PHP, and C#.

To send data to the Plecto API, you need to choose an endpoint and use the POST method. A POST request allows you to send information in the request body. The request body contains all the relevant data that allow to create or update a registration.

There are 3 mandatory keys that must be included in the request body for every 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.

Here below we've listed, in detail, what each of the keys consists of.

Mandatory key #1 – Indicate the data source

The data_source key requires your data source's UUID. The UUID is an alphanumerical string that you can find in the URL when you open a data source.

Mandatory key #2 – Provide information about the member (the one sending data)

Each piece of data you send to Plecto needs to be linked to a user. So the member key here refers to the user (an employee profile in Plecto). When sending an API request, choose one of the two options:

• 🔸 Use a combination of member_api_provider, member_api_id, and member_name (will create a new employee profile)

– or –

• 🔹 Use a member UUID (requires an existing employee profile in Plecto)

🔶🔶🔶

The more common way is to use the member_api_provider, member_api_id, and member_name keys. With this option, Plecto will create a new employee profile when you send the data, and the employee will continue to be managed by your system.

• member_api_provider refers to the name of your system. In the image below, the displayed system name is Postman.
• member_api_id refers to the member ID of your system. In Plecto, it is displayed under the External ID field. In the image below, 101032 represents the member_api_id. The member_api_provider and member_api_id together identify an employee in Plecto.
• member_name is the name of the member. This name will be displayed in the Employee field in your Plecto data source and can be updated, provided that you use the same member_api_provider and member_api_id values.

The request body would look like the following (JSON). The values in the request body are relative to our example data source "API Data Source." If you copy the body, make sure to use the values relevant to your organization.

🔷🔷🔷

Using member UUID requires to have an existing employee profile in Plecto. To find the member UUID, go to Organization > Employees and click on a name. You'll see the UUID in the URL.

The request body would look like the following (JSON). The data source and member UUIDs, as well as the external ID value, are relative to our example data source "API Data Source." If you copy the body, make sure to use the values relevant to your organization.

Mandatory key #3 – External ID

The external_id is a number or a string of characters that has to be unique for each 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. The external ID values in your request body are displayed in the "ID" field in your Plecto data source (see the image below).

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

In this example, we will create a registration in a data source in Plecto through Postman.

• 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.

The request body would look like the following (JSON):

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.

Take a look at the requesting process below:

The Plecto API supports sending a list of registrations in a single request body. However, the API also enforces limits for how many registrations you can send in a single request. Go to this article to learn more about API limits.

Here's an example of what a request body could look like: