Getting started with Monite API

This page will help you get started with the Monite API.

Authentication

All API requests to the Monite API platform must be made over HTTPS. Calls made over plain HTTP will fail.

For more information on our authentication structure, see Get started.

HTTP methods, headers, and statuses

Monite services follow the standard CRUD resource models. This maps to the standard HTTP verbs:

HTTP methodDescription
GETTo retrieve a resource.
POSTTo create a resource, or to execute a complex operation on a resource.
PATCHTo update a resource partially.
PUTTo update a resource by providing a full replacement representation.
DELETETo delete a resource.

Date and time

Timestamps are returned in UTC and formatted as YYYY-MM-DDThh:mm:ss[.zzzzzz][Z|±hh:mm] (ISO 8601).

Dates without the time part are formatted as YYYY-MM-DD.

Pagination, sorting, and filtering

You can control what and how data is returned from the Monite API by using the following techniques:

  • pagination
  • sorting
  • filtering

Pagination

Pagination is a process of dividing the resulting set of data into discrete blocks of information (pages). It decreases both the server payload and the network traffic and increases the speed of page loading.

For example, in Monite you may have 1000 Payables registered and want to receive them in groups of 1-100, where 100 is the maximum of documents that can be requested at a time.

Pagination cursor field

For pagination to work, one field (column) in the database table must be selected as a pagination cursor field. By default, the pagination cursor uses the created_at field. Every database table has such a field, so there is no need to specify it explicitly, unlike other cursor fields. Allowed pagination options for the cursor fields are defined for each endpoint independently, see the details in the Reference section.

Pagination is based on just one cursor field and this field cannot be changed during the pagination process. Let's say we have a table with the id, first_name, last_name, email, phone, and created_at fields. If the pagination is initiated with the first_name field, the API consumer won't be allowed to modify the cursor field in/for the second page.

Page size (limit)

To avoid server and network overloading, the number of returned records in GET requests is restricted. In API requests the limit query parameter defines the number of records that the API consumer wants to receive in the response. Possible values are 1 to 100. Values outside of this range will result in the HTTP error 416 (Requested range not satisfiable).

Sorting

Besides selecting a pagination cursor field, you can use the order query parameter to define the order in which the returned records are sorted: asc (ascending) or desc (descending). Default is asc.

Filtering

Very often API consumers may want to retrieve only selected records rather than all available sets of records. For example, a user is interested only in Payables created 10 days ago or later. To achieve this, you can provide filters in the request query string.

Filters can be of two types:

  • Exact match (case-sensitive):

    FIELD=VALUE
    

    For example, name=Acme or price=1000.

  • Comparison filters:

    FIELD__OPERATOR=VALUE
    

    For example, created_at__gte=2022-01-01T00%3A00%3A00 returns items created on or after January 1, 2022. See the list of operators below.

Multiple filters can be combined using & (logical AND).

📘

The supported filter fields and operators vary per endpoint. Refer to the endpoint reference for the exact supported filters.

Filter operators

Operator

Applicable field types

Description

Example

iexact

string

Case-insensitive equals

name__iexact=acme

contains

string

Contains the specified string (case sensitive)

name__contains=Acme

icontains

string

Contains the specified string (case insensitive)

name__icontains=acme

in

string

Represents the value in [a, b, c] condition, that is, checks if the field value equals one of the specified values (case-sensitive). Each value requires a separate in filter, that is:
FIELD__in=VALUE1&FIELD__in=VALUE2&...

status__in=draft&status__in=issued

gte

number, date-time

Greater than or equal to the specified value

price__gte=5000

gt

number, date-time

Greater than the specified value

price__gt=5000

lte

number, date-time

Less than or equal to the specified value

price__lte=5000

lt

number, date-time

Less than the specified value

price__lt=5000

isnull

any

isnull=true finds items where the specified field value is null. isnull=false finds items where the specified field value is not null.

entity_user_id__isnull=false

Query examples

  • No filters. Only the cursor, sorting, and limit fields are specified:
    GET /products?limit=10&cursor_field=was_created_by_user_name&order=desc
    
  • Filtering by date and limiting the result set:
    GET /products?limit=2&created_at__gte=2021-10-05T00:00:00
    
  • Filtering by two fields with the default pagination:
    GET /products?limit=10&was_created_by_user_name=Andrew&status=active
    

Response example

If the data is selected based on the specified conditions, the response will look like this:

{
    "data": [
      // array of records
      { ... },
      { ... },
      ...
    ],
    "prev_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZwcmV2X3Rva2VuPTM=",
    "next_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZuZXh0X3Rva2VuPTQ="
}

The next_pagination_token and prev_pagination_token values can passed in the pagination_token query parameter to receive the next or previous page in the result set.

Error codes

When something goes wrong with pagination or filtering, one of the following HTTP response codes is returned:

  • 406 Not Acceptable
  • 416 Range Not Satisfiable