How to Send Data to Plecto's API

A guide on how to set up a custom integration and send data to Plecto's API.

Last updated: July 12, 2021

What is Plecto 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.

Note: For custom API integrations, you must use basic auth.

Authentication

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 employee per integration in your Plecto organization - this way you will avoid sharing the same password across integrations. Creating employees in Plecto is free and will not cost anything. To create an employee, go to Organization > Employees > + New employee.

The employee must have admin access to succeed with most API endpoints.

Endpoints

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.

Create a Plecto API data source

It is possible to send any data to Plecto, and we recommend you post data to an API data source. To add a Plecto API data source, go to Data management > Data sources+ New data source and select Plecto API from the list.

send-data-to-api.png

From there, you can customize your data source settings, add fields (optional), and see example API integration code in Python, Ruby, PHP, and C#.

Add API data source.png

An example of an API data source settings.

Send data to Plecto

To send data to the Plecto API, you need to 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 mandatory keys that must be included in the request body for every request that you send. They are the following: data_source, member, and external_id.

Data source

The data_source key requires the unique UUID of a data source. This alphanumerical string can be found in the URL when you open a data source.

Data Source UUID.png

An example of where to locate the UUID of a data source. The highlighted string in the URL is the UUID of the data source.

Member

The member key refers to the employee credentials. Here you can use either a member UUID or member_api_provider, member_api_id, and member_name. Let's look at both key options in more detail.


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 because the member ID comes from an external system, meaning - yours. 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.

Be aware: The member_api_id key in your request body represents the employee's external ID in Plecto, and the external_id key represents the registration ID in Plecto. You can use the same member_api_id for multiple registrations if you want to assign them to the same member (employee). The external_id key, however, needs to be different for each registration, unless you intend to update an existing registration with new field values.

Data Source_External Accounts.png

An example of an employee page. At the bottom of the page, you can see the external accounts the employee is connected to.

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.

{
    "data_source": "70a0d1kg780a4cd98f541c214601030e",
    "member_api_provider": "Postman",
    "member_api_id": "101032",
    "member_name": "Employee X",
    "external_id": "0p23oi5"
}


Using member UUID requires to have an existing employee profile in Plecto. The member UUID can be found in the URL of an employee page. Go to Organization > Employees and click on the employee name to open their employee page and see the UUID.

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.

{
    "data_source": "70a0d1kg780a4cd98f541c214601030e",
    "member": "d40b0139bc7a48e09128521ac5ed089d",
    "external_id": "0p23oi5"
}
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).

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.

Data Source_Plecto API.png

An example of a data source in Plecto.

Update registrations or employee names

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

Basic example

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

Empty Data Source.png

An example of a data source that has no registrations.

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

{
    "data_source": "70a0d1ef780a4cd98f541c214601030e",
    "member_api_provider": "Postman",
    "member_api_id": "101032",
    "member_name": "Employee X",
    "external_id": "12345",
    "Value": "100"
}

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:

Note: 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.

Bulk insertion

The Plecto API supports sending a list of registrations in a single request body. Such request body could look like the following:

[
{
    "data_source": "70a0d1kg780a4cd98f541c214601030e",
    "member_api_provider": "Postman",
    "member_api_id": "101032",
    "member_name": "Employee X",
    "external_id": "0p23oi5",
    "Value": "100"
},
{
    "data_source": "70a0d1kg780a4cd98f541c214601030e",
    "member_api_provider": "Postman",
    "member_api_id": "101032",
    "member_name": "Employee X",
    "external_id": "3ae89oq",
    "Value": "150"
}
]

Be aware: 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>"
}

The Plecto API enforces limits for how many registrations can be in a single request. Go to this article to learn more about API limits.

Was this article helpful?