Collect payables

Learn how to collect an incoming invoice to start the payable flow.

Overview

There are several ways to collect payables into Monite:

  • Create a payable via API by providing the amount, currency, and other details.
  • Upload an invoice in PDF or image format via API.
  • Send an invoice in the PDF or image format by email to the entity's mailbox.

When a payable is created from a PDF or image file, Monite's OCR service automatically extracts the invoice information from the file and fills in the data fields accordingly. During this extraction, if a new counterpart is detected, it is automatically created with the information provided by the OCR.

Once the payable is created, its file property contains the file metadata and the link to access the original source file.

Create a payable from data

If you already have the invoice data (amount in minor units, currency, vendor information, and other details) stored somewhere as individual attributes, you can create a payable with these attributes by calling POST /payables/upload_with_data.

You can provide the base64-encoded contents of the original invoice file in the field base64_encoded_file:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/upload_with_data' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
       -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{
       "currency": "EUR",
       "amount": 11900,
       "description": "Restock office supplies",
       "due_date": "2022-07-15",
       "payment_terms": {
         "name": "2/10, 1/20, net 30",
         "term_1": {
           "number_of_days": 10,
           "discount": 2
         },
         "term_2": {
           "number_of_days": 20,
           "discount": 1
         },
         "term_final": {
           "number_of_days": 30
         }
       },
       "suggested_payment_term": {
         "date": "2022-08-04",
         "discount": 10000
       },
       "issued_at": "2022-06-15",
       "counterpart_bank_id": "DEUTDE2HXXX",
       "counterpart_account_id": "123456789012",
       "counterpart_name": "Acme Inc.",
       "base64_encoded_file": "... Base64-encoded contents of the invoice file ...",
       "tag_ids": []
     }'

📘

If the settings are configured to automatically set suggested_payment_term, this object can be removed from the body.

The successful response returns the id assigned to this payable, along with the information passed in the request. You can use this id in other API calls to update the data of this payable or trigger status transitions:

{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "status": "new",
  "source_of_payable_data": "user_specified",
  "currency": "EUR",
  "amount": 11900,
  "description": "Restock office supplies",
  "due_date": "2022-07-15",
  "payment_terms": {
    "name": "2/10, 1/20, net 30",
    "term_1": {
      "number_of_days": 10,
      "discount": 2
    },
    "term_2": {
      "number_of_days": 20,
      "discount": 1
    },
    "term_final": {
      "number_of_days": 30
    }
  },      
  "suggested_payment_term": {
    "date": "2022-08-04",
    "discount": 10000
  },
  "issued_at": "2022-06-15",
  "counterpart_bank_id": null,
  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
  "counterpart_account_id": null,
  "counterpart_name": "Acme Inc.",
  "payable_origin": "upload",
  "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "was_created_by_external_user_name": null,
  "was_created_by_external_user_id": null,
  "currency_exchange": {
    "default_currency_code": "EUR",
    "rate": 1,
    "total": 0
  },
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2022-04-05T06:31:31.431Z",
    "file_type": "payables",
    "name": "file name",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "application/pdf",
    "url": "https://monite-payables.com/2d14935e.../669bab57c57f.pdf",
    "size": 49463,
    "previews": [],
    "pages": [],
  },
  "tags": [],
  "created_at": "2022-06-17T06:31:31.431Z",
  "updated_at": "2022-06-17T06:31:31.431Z",
  "other_extracted_data": null,
  "line_items": [
    {
      "label": {
        "text": "total",
        "confidence": 99.799
      },
      "value": {
        "text": "€1,125.00",
        "confidence": 96.238,
        "processed_text": 1125
      }
    }
  ],
  "applied_policy": null
}

Automatic calculation of due date

If the due_date is not provided, it is automatically calculated based on the issued_at plus the number of days defined by payment_terms.term_final.number_of_days.

For example, ifissued_at equals to 2022-06-15 and payment_terms.term_final.number_of_days equals to 10, the due_date will be automatically set to 2022-06-25.

Suggested payment date

Once the payable is created, Monite automatically fills the payable's field suggested_payment_term with a suggestion for the payment date and corresponding discount, if available, based on its payment terms (represented by the field payment_terms).

It is possible to choose the payment term (term_1, term_2, or term_final) to be suggested as default by setting the field payment_priority in the entity's settings to one of these values:

  • working_capital: Selects the term with the latest possible payment target.

  • bottom_line: Selects the term with the highest discount.

  • balanced: Selects the intermediate term, that is, a balance between duration and drawn discount.

The suggested_payment_term will be calculated based on the field issued_at added by the term_X.number_of_days. Note that this suggestion does not affect the invoice's due date, which remains the same.

Change the payment priority

To update the payment_priority of in the entity's settings, call PATCH /entities/{entity_id}/settings, passing the new payment_priority in the body:

curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/{entity_id}/settings' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -d '{
    "payment_priority": "working_capital"
  }'

Upload files via API

You can upload invoices in the PDF, PNG, or JPG format to Monite by calling POST /payables. The maximum file size is 10 MB:

curl -X POST 'https://api.sandbox.monite.com/v1/payables' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected];type=application/pdf'

Monite's OCR service automatically scans the details from the uploaded invoice, maps the information from the invoice to the corresponding data field in the system, and returns this information in the response:

{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "status": "new",
  "source_of_payable_data": "ocr",
  "currency": "EUR",
  "amount": 11900,
  "description": "",
  "due_date": "2022-06-30",
  "payment_terms": {
    "name": "string",
    "description": "string",
    "term_final": {
      "number_of_days": 10000
    },
    "term_1": {
      "number_of_days": 10000,
      "discount": 10000
    },
    "term_2": {
      "number_of_days": 10000,
      "discount": 10000
    }
  },
  "suggested_payment_term": {
    "date": "2022-08-04",
    "discount": 10000
  },
  "issued_at": "2022-06-15",
  "counterpart_bank_id": "DEUTDE2HXXX",
  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
  "counterpart_account_id": "123456789012",
  "counterpart_name": "Acme Inc.",
  "payable_origin": "upload",
    "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "was_created_by_external_user_name": null,
  "was_created_by_external_user_id": null,
  "currency_exchange": null,
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2022-04-05T06:31:31.431Z",
    "file_type": "payables",
    "name": "invoice-example.pdf",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "application/pdf",
    "url": "https://monite-payables.com/2d14935e.../669bab57c57f.pdf",
    "size": 49463,
    "previews": [],
    "pages": [
      {
        "id": "ad712600-bab8-4e0d-9da7-5d561484f1b1",
        "mimetype": "image/png",
        "size": 219712,
        "number": 0,
        "url": "https://monite-payables.com/1a95c387.../ac02c56d2a3d.png"
      }
    ]
  },
  "tags": [],
  "created_at": "2022-04-05T06:31:31.431Z",
  "updated_at": "2022-04-05T06:31:31.431Z",
  "other_extracted_data": {
    "summary": [ ... ],
    "line_items": [ ... ]
  },
  "applied_policy": null
}

The other_extracted_data field in the response contains individual text labels and values extracted by OCR, along with the confidence scores (estimated accuracy of character recognition). You can use this data to review and double-check the recognized text:

"other_extracted_data": {
  "summary": [
    {
      "label": {
        "text": "invoice",
        "confidence": 82.47718811035156,
        "processed_text": null
      },
      "value": {
        "text": "#4021",
        "confidence": 82.34294891357422,
        "processed_text": null
      }
    },
    {
      "label": {
        "text": "total",
        "confidence": 99.7991714477539,
        "processed_text": null
      },
      "value": {
        "text": "€1,062.99",
        "confidence": 96.60145568847656,
        "processed_text": 1062.99
      }
    },
    {
      "label": {
        "text": "invoice_due_date",
        "confidence": 98.424560546875,
        "processed_text": null
      },
      "value": {
        "text": "30/6/2022",
        "confidence": 98.33142852783203,
        "processed_text": "2022-06-30T00:00:00"
      }
    },
    ...
  ]
}

Send payables by email

Each entity has a dedicated mailbox in Monite to which the payables can be sent. The entity or entity user can send invoices as attachments in PDF, PNG, JPG, or GIF format to this mailbox (the maximum file size is 10 MB).

The Monite OCR service scans the information inside each email's attachments. Then, Monite automatically creates a draft payable invoice for each occurrence found. The email of the sender of these files is saved in the field sender of the invoice.

To find the mailbox assigned to a specific entity, call GET /v1/mailboxes/mailbox:

curl GET 'https://api.sandbox.monite.com/v1/mailboxes' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

The successful response contains information about the mailbox:

[
  {
    "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
    "entity_id": "68fdd6b5-b60c-4f4d-8642-1cd7f2fa31e8",
    "status": "active",
    "related_object_type": "payable",
    "mailbox_name": "1102737648192968373_payables",
    "mailbox_full_address": "[email protected]",
    "belongs_to_mailbox_domain_id": null
  }
]

📘

By default, the automatically created mailboxes belong to the Monite domain (the web address that comes after @ in an email address), but the partners can set up their own email domain for better convenience.

View all payables

It is possible to view all the payables in the Monite space. To allow the right level of access to the authorized users, Monite allows certain entity users to view them but not change uploads.

To view all payables, call GET /payables:

curl GET 'https://api.sandbox.monite.com/v1/payables?order=asc&limit=100' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

📘

Refer to GET /payables endpoint reference to check all available query parameters for filtering and paginating the results.

The successful response returns a paged series of all payables that the entity has access to. For example:

{
  "data": [
    {
      "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
      "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf",
      "marked_as_paid_with_comment": null,
      "marked_as_paid_by_entity_user_id": null,
      "status": "new",
      "source_of_payable_data": "ocr",
      "currency": "EUR",
      "amount": 11900,
      "description": null,
      "due_date": "2022-06-30",
      "payment_terms": {
        "name": "string",
        "description": "string",
        "term_final": {
          "number_of_days": 10000
        },
        "term_1": {
          "number_of_days": 10000,
          "discount": 10000
        },
        "term_2": {
          "number_of_days": 10000,
          "discount": 10000
        }
      },
      "suggested_payment_term": {
        "date": "2022-08-04",
        "discount": 10000
      },
      "issued_at": "2022-06-15",
      "counterpart_bank_id": "DEUTDE2HXXX",
      "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
      "counterpart_account_id": "123456789012",
      "counterpart_name": "Acme Inc.",
      "payable_origin": "upload",
      "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
      "was_created_by_external_user_name": null,
      "was_created_by_external_user_id": null,
      "currency_exchange": {
        "default_currency_code": "EUR",
        "rate": 1,
        "total": 0
      },
      "file": {
        "id": "2d14935e-505b-4863-a082-b6a340acabbc",
        "created_at": "2021-11-25T05:10:35.211432+00:00",
        "file_type": "payables",
        "name": "file name",
        "region": "eu-central-1",
        "md5": "623470039566983ed5e5945f769ea873",
        "mimetype": "image/png",
        "url": "https://monite-payables.com/2d14935e.../669bab57c57f.png",
        "size": 49463,
        "previews": [],
        "pages": []
      },
      "tags": [
        {
          "name": "Marketing",
          "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
          "created_at": "2022-09-07T16:35:18.484507+00:00",
          "updated_at": "2022-09-07T16:35:18.484507+00:00",
          "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
        }
      ],
      "created_at": "2021-11-25T05:10:35.211432+00:00",
      "updated_at": "2021-11-25T05:10:35.211447+00:00",
      "other_extracted_data": { ... },
      "applied_policy": "Travel expense approval",
      "document_id": "DE2287",
      "subtotal": 100000,
      "tax": 1900,
      "sender": "[email protected]"
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZuZXh0X3Rva2VuPTQ="
}

Theprev_pagination_token and next_pagination_token fields are pagination tokens.

Review a payable

Once a payable is uploaded, the entity and entity users can review the information extracted from the payable by the OCR system and make changes before validating the payable.

To edit a payable, retrieve the payable by calling GET /payables/{payable_id}:

curl GET 'https://api.sandbox.monite.com/v1/payables/{payable_id}' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

The successful response contains the payable attributes:

{ 
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf",
  "marked_as_paid_with_comment": null,
  "marked_as_paid_by_entity_user_id": null,
  "status": "new",
  "source_of_payable_data": "ocr",
  "currency": "EUR",
  "amount": 11900,
  "description": null,
  "due_date": "2022-06-30",
  "payment_terms": {
    "name": "string",
    "description": "string",
    "term_final": {
      "number_of_days": 10000
    },
    "term_1": {
      "number_of_days": 10000,
      "discount": 10000
    },
    "term_2": {
      "number_of_days": 10000,
      "discount": 10000
    }
  },
  "suggested_payment_term": {
    "date": "2022-08-04",
    "discount": 10000
  },
  "issued_at": "2022-06-15",
  "counterpart_bank_id": "DEUTDE2HXXX",
  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
  "counterpart_account_id": "123456789012",
  "counterpart_name": "Acme Inc.",
  "payable_origin": "upload",
  "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "was_created_by_external_user_name": null,
  "was_created_by_external_user_id": null,
  "currency_exchange": {
    "default_currency_code": "EUR",
    "rate": 1,
    "total": 0
  },
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2021-11-25T05:10:35.211432+00:00",
    "file_type": "payables",
    "name": "file name",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "image/png",
    "url": "https://monite-payables.com/2d14935e.../669bab57c57f.png",
    "size": 49463,
    "previews": [],
    "pages": []
  },
  "tags": [
    {
      "name": "Marketing",
        "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
        "created_at": "2022-09-07T16:35:18.484507+00:00",
      "updated_at": "2022-09-07T16:35:18.484507+00:00",
        "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
    }
  ],
  "created_at": "2021-11-25T05:10:35.211432+00:00",
  "updated_at": "2021-11-25T05:10:35.211447+00:00",
  "other_extracted_data": { ... },
  "applied_policy": "Travel expense approval",
  "document_id": "DE2287",
  "subtotal": 100000,
  "tax": 1900,
    "sender": "[email protected]"
 }

To make changes to a payable, call PATCH /payables/{payable_id}. For example, to update the amount and due_date:

curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/{payable_id}' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -d '{
    "amount": 19000,
    "due_date": "2022-07-12"
  }'

Did this page help you?