Skip to content

Docs / All tools / Loop III: Assistant

assistant.invoice.start

Read a PDF invoice attached to an email, extract and check its fields, and wait for review.

Charged by the tools it calls. mail.read_get 2, mail.read_attachment 2, doc.extract_fields 25.

Example prompt

Send this to your AI app when Heelo is connected:

Process the latest invoice e-mail from Acme: check the PDF and add a payment reminder to my Outlook calendar after I approve.

Input fields

FieldTypeDescription
account_handlestringThe mail account to read (mail.read's account_handle); the default when omitted.
message_idstringThe invoice email's id from mail.read_list. Give this or subject.
subjectstringText in the invoice email's subject; the newest match is used. Give this or message_id.
attachment_idstringThe invoice attachment's id, from mail.read_get's attachments (not its file name); needed only when the email has two PDFs.
folderstringThe mailbox folder.
calendar"outlook" | "google" | "none"Which connected calendar gets the payment event; none writes no event.
timezonestringIANA timezone of the event, e.g. America/Chicago. Leave it out to use the calendar's own. A Google Calendar places the event in its own timezone, so another one is refused.
notion_parentstringThe Notion page id or URL to create the record under; none writes no page.
end_user_idstringWhich of your end users the mailbox belongs to.
include_confidencebooleanAlso show each field's confidence score in the review. Off by default: compare the values with the invoice (invoice_document in status) instead.

Code

The call with the input fields that the tool needs. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/assistant.invoice.start/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "subject": "Invoice",
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())