Table of contents
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.
To create a new employee profile, 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.
How to create an API data source
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#.
Use POST method
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.
Mandatory keys and the request body
There are 3 mandatory keys that must be included in the request body for every request that you send. The keys are the following:
member (or member_api_provider, member_api_id, and member_name), and
The UUID is an alphanumerical string that you can find in the URL when you open a data source.
Choose one or the other
To find the member UUID, go to Organization > Employees and click on a name. You'll see the UUID in the URL.
With this option, Plecto might create new employee profiles when you send the data, and the employee will continue to be managed by your system.
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.
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.
How to update existing data
external_ididentify 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.
member_api_ididentify 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
datefield 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:
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.
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.