Create Invoice

POST /invoices/{tenant}

This endpoint allows users to create Invoices for the Tasks that are in a status that allows for the Invoice process to proceed.

Any successful documents provided in the Document property will have their details temporarily uploaded to the system and you will be provided with identifiers in return which will then allow you to upload the actual documents against the Invoice using the Upload Document process.

Path	Notes
PurchaseOrderNumber	May be mandatory depending on tenant configuration
SupplierReference	A supplier's reference for the invoice. Must be unique for that contractor on that tenant
SupplierName	The name of the supplier. Must match the record in Urgent.
Lines[]	An array of lines in the invoice
Lines[].Description	Free text, max 255 characters
Lines[].Name	Free text, max 100 characters
Lines[].LineType	One of "labour", "labor", "materials", "travel", "other"
Lines[].Quantity	Decimal
Lines[].UnitCost	Net value of a single unit
Lines[].UnitType	One of "each", "hour"
Lines[].TotalAmountNet	Net value of the line
Lines[].TotalAmountGross	Gross value of the line
Lines[].TotalAmountTax	Tax value of the line
Lines[].TaskReference	Urgent task invoice, must be eligible to invoice for the current api user
Documents[]	An array of documents being uploaded. May be mandatory depending on tenant configuration. Successful documents can be then uploaded using the Upload Document process and the provided identifier. These documents will then be present in the Invoice Documents tab.
Documents[].Filename
Documents[].MimeType
Documents[].ByteSize

Request Example

{
    "PurchaseOrderNumber": "PO-2022-06-09-D",
    "SupplierReference": "Ref-2022-06-09-D",
    "SupplierName": "AMCE Inc",
    "Lines": [
        {
        "Description": "Materials for task",
        "Name": "3 widgets",
        "LineType": "materials",
        "Quantity": 3,
        "UnitCost": 10.00,
        "UnitType": "each",
        "TotalAmountNet": 30.00,
        "TotalAmountGross": 36.00,
        "TotalAmountTax": 6.00,
        "TaskReference": 10123
        }
    ],
    "Documents":
    [
        {
            "Filename": "Inv_10123.pdf",
            "ByteSize": "100000",
            "MimeType": "application/pdf"
        }
    ]
}

Response Examples

Success Example

Indicates that the request was successful and the invoice was created. The document identifiers are then used to upload the raw bytes or the document (see Swagger documentation)

{
  "Messages": [],
  "InvoiceReference": 15974,
  "DocumentIdentifiers": [
    "167e2c46-2670-44fb-a96d-a6ea0ee4a93e",
    "fc222e84-426e-4f00-abf6-369f4352eee9"
  ] 
}

Failure example

Indicates that the invoice was not created

{
  "Messages": [{
    "Key": "BrokenRule_Invoice_Task_NotEligibleForInvoicing",
    "Value": "The selected task is not eligible for invoicing"
  }],
  "InvoiceReference": null,
  "DocumentIdentifiers": [] 
}

Read Invoice

GET /invoices/{tenant}/{reference}

Reads a single invoice

Response

Path	Notes
Reference	The reference of the invoice. Unique across the tenant
Status	The current status of the invoice
PurchaseOrderNumber	The purchase order number for the invoice.
Currency	The three-letter ISO code for the currently
InvoiceType	The type of invoice, one of "task_based" or "fixed_contract"
TotalAmountNet	The total net value of the invoice
TotalAmountGross	The total gross value of the invoice
TotalAmountTax	The total tax value of the invoice
DateInvoiced	The date the contractor input as the tax point
TaskReference	If the tenant has Single Task Invoicing enabled then this will be populated with the reference of the associated task. If not, then it will be null.
SiteCode	If the tenant has Single Task Invoicing enabled then this will be populated with the Site Code of the associated task. If not, it will be null.
Supplier.Name	The name of the supplier that submitted the invoice.
Supplier.Code	The code of the supplier that submitted the invoice
Supplier.VendorNumber	The vendor number in the tenant's financial system representing the supplier
Supplier.TaxCode	The tax number if the tenant's financial system representing the supplier
Lines[]	An array of lines in the invoice
Lines[].TaskReference	The task the line is associated with. Will be null for Fixed Contract invoices
Lines[].SiteCode	The Site Code the line is associated with
Lines[].GlCode	The General Ledger code of the line
Lines[].LineType	One of "labour", "materials", "travel", "other"
Lines[].UnitType	One of "each", "hour"
Lines[].Name	Free text details of the line
Lines[].Description	Free text details of the line
Lines[].Quantity	Decimal representing the quantity of the line
Lines[].UnitCost	Net value of a single unit of the line
Lines[].TaxRate	Calculated tax rate of the line.
Lines[].TotalAmountNet	Net value of the line
Lines[].TotalAmountGross	Gross value of the line
Lines[].TotalAmountTax	Tax value of the line.
Lines[].ContractItem	The tenant may use pre-configured items for selection by the contractor, including labour and travel rates. If so, this property will be poulated.
Lines[].ContractItem.Name	The name of the Contract Item
Lines[].ContractItem.Code	The code representing the Contract Item. Unique across the tenant.
History[]	Information about the status history of the invoice
History[].Status	The name of the status
History[].DateTimeCreatedUtc	The date and time that the invoice was moved into the status.
History[].UserCreated	The name of the user that made the status change
Notes[]	An array of notes associated with the invoice
Notes[].NoteIdentifier	The GUID representing the note. Unique across the platform
Notes[].Text	The text of the note
Notes[].DateTimeCreatedUtc	The date and time that the note was created
Notes[].Author	The name of the note's author
Documents[]	Information about the documents associated with the invoice. See Documents for more info.
Documents[].DocumentIdentifier	The GUID representing the document. Unique across the platform and used to download the document.
Documents[]ByteSize	The size of the document in bytes
Documents[].FileName	The name of the file when it was uploaded
Documents[].MimeType	The mime type of the document that was detected when it was uploaded

Response Example

 {
  "Reference": 620901,
  "Status": "Approved for Payment",
  "PurchaseOrderNumber": "PO-TCN-2023-001",
  "Currency": "EUR",
  "InvoiceType": "Task_Based",
  "TotalAmountNet": 552,
  "TotalAmountGross": 460,
  "TotalAmountTax": 92,
  "DateInvoiced": "2023-06-17T00:00:00Z",
  "TaskReference": null,
  "SiteCode": null,
  "Supplier": {
    "Name": "Techniche EMEA Limited",
    "Code": "TCNEMEA",
    "VendorNumber": "63839",
    "TaxCode": "GB-7623893292"
  },
  "Lines": [
    {
    "TaskReference": 197389,
    "SiteCode": "WTNSTD",
    "GlCode": "GL-001343",
    "LineType": "labour",
    "UnitType": "each",
    "Name": "Labour",
    "Description": "2 x technical resources",
    "Quantity": 2,
    "UnitCost": 200,
    "TaxRate": 20,
    "TotalAmountNet": 400,
    "TotalAmountGross": 480,
    "TotalAmountTax": 80,
    "ContractItem": null
    },
    {
    "TaskReference": 197389,
    "SiteCode": "WTNSTD",
    "GlCode": "GL-001343",
    "LineType": "other",
    "UnitType": "each",
    "Name": "Travel",
    "Description": "Mileage from base",
    "Quantity": 60,
    "UnitCost": 1,
    "TaxRate": 20,
    "TotalAmountNet": 60,
    "TotalAmountGross": 72,
    "TotalAmountTax": 12,
    "ContractItem": null
    }
  ],
  "History": [
    {
    "Status": "Pending Approval",
    "DateTimeCreatedUtc": "2023-06-17T00:00:00Z",
    "UserCreated": "John Doe"
    },
    {
    "Status": "Approved for Payment",
    "DateTimeCreatedUtc": "2023-06-20T07:05:28.9589447Z",
    "UserCreated": "Joe Bloggs"
    }
  ],
  "Notes": [
    {
    "NoteIdentifier": "4af30815-a9d1-41d5-b4d1-46085787942c",
    "Text": "This invoice has been approved",
    "DateTimeCreatedUtc": "2023-06-20T07:05:28.9589447Z",
    "Author": "John Doe"
    }
  ],
  "Documents": [
    {
    "DocumentIdentifier": "8d054d17-c341-4b3a-a1f1-c454b65ecd61",
    "ByteSize": 1000000,
    "FileName": "620901_Invoice.pdf",
    "MimeType": "application/pdf"
    }
  ]
}

Search Invoices

POST /invoices/{tenant}/search

The following are search criteria that can be used to search for invoices in the Urgent platform. Search results are only returned for sites and suppliers that your user has access to.

Path	Notes
TaskReferences[]	An Array of Urgent Task References
InvoiceReferences[]	An Array of Urgent Invoice Handling References
Statuses[]	An array of statuses that the invoice is in. See Workflow endpoints
Suppliers[]	An array of Supplier Names
Sites[]	An array of Site Codes. See Site endpoints
Dates	Searching by dates
Dates.CreatedFromUtc	Search by the date the invoice was created in Urgent. Time is adjusted to 00:00:00 UTC
Dates.CreatedToUtc	Search by the date the invoice was created in Urgent. Time is adjusted to 23:59:59 UTC
Dates.ModifiedFromUtc	Search by the date the invoice was last modified in Urgent. Time is adjusted to 00:00:00 UTC
Dates.ModifiedToUtc	Search by the date the invoice was last modified in Urgent. Time is adjusted to 23:59:59 UTC
StartIndex	Zero-based search index
EndIndex	A max of 100 results can be returned.

Response

The response is an array of the response from the Read Invoice method.

Change External Invoice Reference

PUT /financial/{tenant}/{urgentId}/ExternalInvoiceReference

This method allows you to update the External Reference of a given Invoice.

Property	Notes
externalId	The number for the external reference to be updated to.

Request Example

{
  "externalId": 123456
}

Change Invoice Status

PUT /financial/{tenant}/{urgentId}/status

This method allows you to update the status of a given Invoice which is currently in a closed status.

Property	Notes
status	The name of the status to transition to. It must be a valid destination status from the current status and be of a closed type.

Request Example

{
  "status": "Invoice Paid"
}