Send Requests to API

Step 3: Get hold of the general rule for your API requests.

Authorize Requests

After acquiring the access token from the authentication endpoint, include the returned access token in header of subsequent requests.

curl -X GET
-H "Authorization: Bearer <access_token>"
...

Data access is restricted to the resource owner only (ie, the client credential owner. or the business profile)

Business Profile ID

Business Profile IDs are critical whenever you issue requests to Pymlo API. It indicates which set of accounting data that you refer to, and if your authentication token has the matching access.

A general Pymlo API endpoint URL looks like this:

https://api.pymlo.com/v1/businesses/<businessid>/<endpoint_path>

You will have to include the Business Profile ID as one of the path parameters to access data that belongs to the business profile correctly.

You can get your Business Profile ID from the Developer Setting page.

Operation Types

Pymlo API provides a series of CRUD functions based on HTTP methods following the general REST pattern.

Operation

HTTP method

Retrieve

GET

Create

POST

Update

PUT

Specific operations (send, data merge, etc.)

POST

Delete

DELETE

Filtering and Pagination

While retrieving list data from Pymlo API, all lists are paginated by default - controlled by page and size parameters in GET calls.

Take the "Get Invoices" endpoint as an example:

curl -X GET
...
"https://api.pymlo.com/v1/businesses/<businessid>/income/invoices?page=0&size=20"

You will get a data page in the following pattern in return, indicating it is only a part of all data found in the storage:

{
"_embedded": {
"invoiceDTOList": [
...
]
},
"_links": {
...
},
"page": {
"size": 20,
"total_elements": 27,
"total_pages": 2,
"number": 0
}
}

Query parameter

Type

Description

page

number

Zero-indexed page number.

size

number

Number of data items to include in the page. Default is 20 and silently capped at 50.

These above paging parameters apply to all list retrieval endpoints. For more details on how the Invoice endpoint works, go here:

Similarly, data filtering is achieved with query parameters attached to the end of endpoint URL when issuing GET requests.

For all available filter fields and usage of each endpoint, please refer to their manual in API Reference section respectively.

HATEOAS Response Structure

Pymlo API adopts HATEOAS architecture, providing self-discoverable links to all JSON data in responses, so you can take a quick look at what are available for each type of resource.

Take the responses from the Invoice endpoint for example:

Sample invoice in response
{
...
"_links": {
"self": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices/a56b4040-cddb-44e4-8a88-04a118ea90d6"
},
"invoice_payments": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices/a56b4040-cddb-44e4-8a88-04a118ea90d6/payments"
}
}
}

For a single invoice, all available endpoints are included to instruct the user to take related actions, such as retrieving payments by accessing the Payment endpoint.

Sample page of multiple invoices
{
"_embedded": {
"invoiceDTOList": [
...
]
},
"_links": {
"first": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices?page=0&size=20&sort=date,id,desc"
},
"self": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices?page=0&size=20&sort=date,id,desc"
},
"next": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices?page=1&size=20&sort=date,id,desc"
},
"last": {
"href": "https://api.pymlo.com/v1/businesses/4f320c75-8674-48a0-8339-7573f89daa66/income/invoices?page=1&size=20&sort=date,id,desc"
}
},
"page": {
...
}
}

For a list (page, in fact) of invoices, the pagination links are included in the response for an easier, consistent navigation experience.

To understand more about HATEOAS, read here: https://en.wikipedia.org/wiki/HATEOAS

Invalid Enum Value in the Request Body

For any body parameter in the enum type, Pymlo API will render as null values if the given string input is not a valid enum constant. If that parameter happens to be required, a 400 Bad Request response is replied since the data in the request is malformed.

To understand our data structure and the possible enum values for respective types. please see the Object section.