PSOhub API - Invoice

In PSOhub, invoices are generated based on contract lines within a project. Because of the complexity of building up the invoice, there is no support for creating invoices via API but you can retrieve them and also update the status to Paid and/or fill in an External ID for your own financial integration.

Get all invoices

To get all invoices, you can use the following endpoint

GET https://www.psohubapp.com/rest/psohubapi/v1/invoices

If you want to filter the invoices on a specific status, include the invoicestatus parameter like below

GET https://www.psohubapp.com/rest/psohubapi/v1/invoices?invoicestatus=draft

You can use the following options:

draft

approved

sent

paid

You can also filter on invoicenumber or filter invoices that do not have an externalinvoiceid yet, see example below

GET https://www.psohubapp.com/rest/psohubapi/v1/invoices?invoicenumber=inv-2024-48

GET https://www.psohubapp.com/rest/psohubapi/v1/invoices?noexternalid=true

If successful, the response will be this (the example shows 1 invoice but there can ofcourse be multiple)

[
{
        "InvoiceName": "Google - IAM Impementations services",
        "InvoiceDate": "2024-10-28T00:00:00.000Z",
        "InvoiceDueDate": "2024-11-28T00:00:00.000Z",
        "InvoiceNote": "If you have any questions about this invoice, feel   free to contact us at any time via volker@deco.nl",
        "InvoiceStatus": "Draft",
        "InvoiceNumber": "INV-2024-33",
        "InvoiceID": 41939771881672249,
        "CustomerID": 14073748838924968,
        "CustomerName": "Google",
        "InvoiceContactID": 21110623256832211,
        "InvoiceContactName": "Chris Rea",
        "InvoiceContactEmail": "chris.rea@google.com",
        "InvoiceCurrencyCode": "USD",
        "TotalAmountExVAT": 27700,
        "TotalAmountIncVAT": 33517,
        "TotalAmountExVATBaseCurrency": 27700,
        "TotalAmountIncVATBase": 33517,
        "InvoicePDF": Base64String,
        "InvoiceLines": [
            {
                "LineNumber": "10.002 ",
                "LineName": "Business Review",
                "LineDescription": " ",
                "GLAccount": "260",
                "TaxPercentage": 21,
                "TaxName": BTW 21%,
                "TaxCode": 2,
                "TotalAmountExVAT": 2700,
                "TotalAmountIncVAT": 3267,
                "TotalAmountIncVATBaseCurrency": 3267,
                "TotalAmountExVATBaseCurrency": 2700,
                "InvoiceDetailLines": [
                    {
                        "AccountID": 39406496739494241,
                        "AccountName": "Martijn vd Hoeden",
                        "BusinessUnit": "Creative",
                        "Date": "2024-10-24T08:00:00.000Z",
                        "Description": "-",
                        "AmountOfHours": 2,
                        "Rate": 225,
                        "RateBase": 0,
                        "TotalAmount": 450,
                        "TotalAmountBase": 450
                    }]
                 ]
}]

Let's look into what data the system is returning when you are requesting an invoice.

Name	Type	Description
InvoiceName	String	The name of the invoice
InvoiceDate	DateTime	Invoice Date
InvoiceDueDate	DateTime	Due date / expiration date
InvoiceNote	String	Note to appear on the invoice
InvoiceStatus	String	Status, can be Draft/Approved/Sent/Paid/Void
InvoiceNumber	String	The unique number in PSOhub for this Invoice
InvoiceID	Integer/Long	Unique ID of the Invoice
CustomerID	Integer/Long	Unique ID of the Invoice Customer/Company
CustomerName	String	Name of the Customer/Company
InvoiceContactID	Integer/Long	Unique ID of the invoice contact
InvoiceContactName	String	Name of the invoice contact
InvoiceContactEmail	String	Email of the invoice contact
InvoiceCurrencyCode	String	ISO code for the Invoice currency
TotalAmountExVAT	Decimal	Total Invoice amount excluding VAT
TotalAmountIncVAT	Decimal	Total Invoice amount including VAT
TotalAmountExVATBaseCurrency	Decimal	Total Invoice amount excluding VAT in the base currency
TotalAmountIncVATBase	Decimal	Total Invoice amount including VAT in the base currency
InvoicePDF	String	A Base64 string for the Invoice PDF. Only available for invoices that are not on Draft

This is the main invoice object, containing all relevant data and the total for the entire invoice. Each invoice will always have one or multiple invoice lines. Let's see what we can find in there

Name	Type	Description
LineNumber	String	Group and linenumber combined , based on the contract line
LineName	String	Name of the invoice line
Description	String	Description to specify the invoice line
TaxPercentage	Decimal	Tax percentage if applicable
TaxName	String	The name of the tax as configured in PSOhub
TaxCode	String	The external identifier for this tax code from your application
GLAccount	String	Name of the linked GL account if applicable
TotalAmountExVAT	Decimal	Total invoice line amount excluding VAT
TotalAmountIncVAT	Decimal	Total Invoice line amount including VAT
TotalAmountIncVATBaseCurrency	Decimal	Total Invoice line amount excluding VAT in the base currency
TotalAmountExVATBaseCurrency	Decimal	Total Invoice line amount including VAT in the base currency

For invoices that have T&M / Expenses and are generated on a detail level, there is a third layer available that shows specifications for all time entries or expenses that are invoiced

Name	Type	Description
AccountID	Integer/Long	Unique ID of the account that booked the hours/expenses
AccountName	String	Name of the account that booked the hours/expenses
BusinessUnit	String	The business unit of the user that booked the hours/expenses
Date	Date/Time	Date of the booking
Description	String	Description to specificy
AmountOfHours	Decimal	Total hours (only for T&M)
Rate	Decimal	Rate based on project team rate for this account
RateBase	Decimal	Rate in base currency
TotalAmount	Decimal	Total Amount for the total hours * rate or the expense total
TotalAmountBase	Decimal	Total amount in base currency

Update Invoice to Paid

You can set an invoice to paid via the API by calling a specific endpoint. At this moment, only Paid is available via the API. Important: Only invoices with a status of approved or sent can be changed to paid

PATCH https://www.psohubapp.com/rest/psohubapi/v1/invoices/paid?invoiceid=41939771862548888

Update Invoice with External Invoice ID

If you are using the API to put the invoices into an external financial integration it might be good to store the ID of that integration within the PSOhub invoice. You can use this specific endpoint to do so.

PATCH https://www.psohubapp.com/rest/psohubapi/v1/invoices/external?invoiceid=41939771862548888&externalid=13

PSOhub API - Invoice

Learn how to retrieve invoices and update the external ID and status via API

Get all invoices

Update Invoice to Paid

Update Invoice with External Invoice ID