Core Concepts

Important principles our API follows. Please also read the API restrictions which apply in general.

Listing Data

We provide endpoints to list data you have access to. Such as organizations, their cardholders, their cards and their transactions. Just to name a few.

These endpoints are a good starting point into the world of Pliant. They provide an overview of the data you have access to, without too much details.

Getting Details

Details for One Entity

We provide endpoints to then fetch details for a specific entity you have in mind. That could be an organization, a card or a transaction. Whatever it is, with these endpoints we provide you all details we have regarding this one entity.

Details for Multiple Entities

You might have the case that you want to get the details for 10 cards, or 100 or 1000. For this use case we provide special endpoints where you can fetch the details of multiple entities at once. No need to loop on your side, just provide all identifiers and we send back the details belonging to all those identifiers.

Get Informed via Callbacks

We can notify you, when certain events occur in our system. That might be when a new transaction is made or someone uploads a receipt to a transaction. Or even the onboarding status of one of the organizations you follow changes. We will notify you.

To not get overwhelmed with useless notifications, you subscribe to certain types of events and we only send you those then. So you have full control over which information you get and which not.

Mutating Data Happens Asynchronously

One important aspect of our API is that all mutating operations (create, update, delete) are asynchronous from the partner perspective, but synchronous from the perspective of the action triggered.

What does this mean? If you for example issue a new credit card, once you receive the response from the issue card request, the card itself is issued and usable (i.e. doing a transaction with it), but the system as a whole is eventually consistent. Meaning if you want to get details about the card etc. you need to wait until the respective callback is triggered and send to you. Only after receiving the callback of the action you triggered, you can be sure that everything is up-to-date.

The distinction of the action happening immediately but the result after the action happened spreading eventually consistent through the system is important to understand. Another example shows that: imagine you want to lock a card. This action might be time critical. So when calling the endpoint to lock a card, this lock happens immediately and is in place once the HTTP call comes back with a successful response. But the card details endpoint might still show an active card status. Which is not problematic, since the card itself is locked already and cannot be sued anymore. But the data about this action happening is processed by other parts of the system 1-2 seconds after it happened. So if you want to update the data on your end, it is best to wait on the respective callback as stated above.

All our mutating endpoints return HTTP code 202 Accepted or 204 No Content to reflect this behaviour. All synchronous endpoints, like reading data, return HTTP code 200 Ok.