PluggyDocs

Basic concepts

Security protocols, API conventions, environment, request identifiers, and pagination used by the Pluggy API.

View as Markdown

Security protocols#

Pluggy's API enforces the use of HTTPS TLSv1.2 or upper versions for security reasons. Other TLS version requests will be rejected. All communication requires to be in HTTPS.

API verbs and Protocols#

Pluggy's API is a RESTful API based on JSON requests and responses, so all requests must have set the header Content-Type of application/json.

We follow the RESTful standards and all verbs match their specific action for the resource you will be communicating.

API response fields

We evolve our API in a non-breaking way, by adding new fields to our endpoint responses. This makes it simpler since there are no complicated versioning mechanisms, but it also means that your HTTP client must support receiving unknown fields in a response and ignore them. In most libraries this is supported by default, but please review your particular case to check that this is configured correctly.

Environment#

Our production environment is accepting requests in the following host:

https://api.pluggy.ai

Request IDs#

Every response from the Pluggy API carries an x-request-id header — a UUID identifying that single request:

x-request-id: 079482e5-8aa4-4708-9aaa-43c2f2792b4a

It is on every response, successful or not, and it is the one value that lets us find your exact request in our logs. Reading it costs nothing:

bash
curl -i https://api.pluggy.ai/connectors \
  -H 'X-API-KEY: YOUR_API_KEY' | grep -i x-request-id

Log it alongside your own errors. When something fails — a 4xx you did not expect, a request that timed out, a response whose contents look wrong — send us the x-request-id with your report. Without it we search by item, by time window and by endpoint and often find several candidates; with it we go straight to the request you saw, which is usually the difference between an answer the same day and a conversation over several.

Pagination#

Some Pluggy's responses can yield a large amount of data, in which cases the size of the response is limited and divided in pages.

For example, if you make a request to /transaction?accountId={ACCOUNT_ID}, you will receive an object like:

json
{
  "total": 200,
  "totalPages": 15,
  "results": [],
  "page": 1
}
  • total: the size of the data of the request
  • totalPages: the total number of pages encompassing all available records
  • results: the content of the current page
  • page: the number of the current page

For example, /transaction?accountId={ACCOUNT_ID}&page=2 is the second page of transactions results.

By retrieving /transaction?accountId={ACCOUNT_ID}, then /transaction?accountId={ACCOUNT_ID}&page=2, and so on, you may access to all the data available, one page at a time.

To sum up, to obtain all the data from a paginated endpoint, after your first request you should iterate as many times as totalPages, making a new request and changing the page query param.

Was this page helpful?