Skip to main content

Search Invoices

This endpoint allows a user to search for invoices.

Search Payloads and Paginated Lists

Search endpoints are not self-explanatory. Before using this endpoint please read-up on search payloads and response pagination lists in Making a Request.

Request​

URL​

/invoices/search

Best practice is to always include the pagination query string.

Method​

POST

Headers​

Content-Type: application/json
Authorization: Bearer eyy...

Body​

The search payload.

queryTarget fields for partial match search are:

  • id
  • clientId
  • clientName
  • invoiceNumber
  • debtor.id
  • debtor.name

Basic search fields are:

  • query
  • queryTarget
  • id
  • refinancingExternalId
  • clientId
  • clientName
  • debitInvoiceNumber
  • productCode
  • distributionCode
  • reminderProfileCode
  • serviceProviderCode
  • documentTemplateCode
  • invoiceNumber
  • paymentReference
  • statuses.main
  • statuses.ledger
  • statuses.ledgerSubType
  • partPayment.isPartPayment
  • partPayment.partPaymentPlanId
  • dates.invoiceDate
  • dates.expireDate
  • dates.pausedUntilDate
  • dates.latestFinancialDate
  • debtor.id
  • debtor.customerNumber
  • debtor.type
  • debtor.identificationNumber
  • debtor.GLN
  • debtor.FMI
  • debtor.name
  • debtor.email
  • debtor.phone
  • debtor.cellPhone
  • debtor.invoiceAddress.name
  • debtor.invoiceAddress.address
  • debtor.invoiceAddress.address2
  • debtor.invoiceAddress.address3
  • debtor.invoiceAddress.zip
  • debtor.invoiceAddress.city
  • debtor.invoiceAddress.countryCode
  • debtor.deliveryAddress.name
  • debtor.deliveryAddress.address
  • debtor.deliveryAddress.address2
  • debtor.deliveryAddress.address3
  • debtor.deliveryAddress.zip
  • debtor.deliveryAddress.city
  • debtor.deliveryAddress.countryCode
  • currency.invoiceCurrency
  • currency.baseCurrency
  • totals.total
  • totals.totalToPay
  • balances.total
  • type
  • isRecourse
  • useRecourse
  • createdDate
  • createdBy
  • closed
  • activatedDate
  • activatedById

Response​

  • Status code 200
  • Body a list of results (paginated) of invoice objects
  • Headers pagination headers, including link to next page
Response Body

The response is a list of invoice objects. The invoice object has the below data.

{
  "id": {
    "type": "String",
    "description": "Internal id of the entity."
  },
  "clientId": {
    "type": "String",
    "description": "Internal client id for the client connected to the invoice."
  },
  "clientName": {
    "type": "String",
    "description": "Your company name."
  },
  "productCode": {
    "type": "String",
    "description": "Product used for the invoice. Can be one of INVOICE_SERVICE, REMINDER_SERVICE, COLLECTION_SERVICE, INVOICE_FACTORING_LOAN or INVOICE_FACTORING_SELL."
  },
  "serviceProviderCode": {
    "type": "String",
    "description": "Which installed service provider will be used to administrate the invoice."
  },
  "invoiceNumber": {
    "type": "String",
    "description": "Your invoice number of the invoice.",
    "required": true
  },
  "paymentReference": {
    "type": "String",
    "description": "Payment reference of the invoice. Used when debtor pay for the invoice."
  },
  "debitInvoiceNumber": {
    "type": "String",
    "description": "Your reference to debit invoice number. This should be provided if the invoice is a credit invoice."
  },
  "statuses": {
    "type": "Nested",
    "Nested": {
      "main": {
        "type": "String",
        "description": null
      },
      "ledger": {
        "type": "String",
        "description": "Ledger status of the invoice. This is how far the invoice is in the reminder process. Can be one of NULL, INVOICE, EXPIRED, EXPIRED_NOTIFICATION, REMINDER, COLLECTION, DELAYED_PENALTY_FEE, MONITORING_DECISION or MONITORING."
      },
      "ledgerSubType": {
        "type": "String",
        "description": null
      }
    }
  },
  "partPayment": {
    "type": "Nested",
    "Nested": {
      "isPartPayment": {
        "type": "Boolean",
        "description": null
      },
      "partPaymentPlanId": {
        "type": "Integer",
        "description": null
      }
    }
  },
  "dates": {
    "type": "Nested",
    "Nested": {
      "invoiceDate": {
        "type": "Date",
        "description": "Invoice date of the invoice.",
        "required": true
      },
      "expireDate": {
        "type": "Date",
        "description": "Expire date of the invoice.",
        "required": true
      },
      "deliveryDate": {
        "type": "Date",
        "description": "Delivery date of the invoice."
      },
      "pausedUntilDate": {
        "type": "Date",
        "description": "Shows for how long the handling of the invoice is paused."
      },
      "ledgerPerformedDate": {
        "type": "Date",
        "description": "Ledger performed date. Shows the performed date of the previous ledger event. "
      },
      "latestFinancialDate": {
        "type": "Date",
        "description": "Financial event date of latest created event.",
        "required": true
      }
    }
  },
  "debtor": {
    "type": "ExtendedNested",
    "description": null
  },
  "document": {
    "type": "Nested",
    "Nested": {
      "attachment": {
        "type": "String",
        "description": "File name of the attachment PDF added to the invoice. Download it with {{API}}/storage/{{fileName}}."
      },
      "invoicePreview": {
        "type": "String",
        "description": "File name of the invoice preview PDF. Download it with {{API}}/storage/{{fileName}}."
      },
      "invoice": {
        "type": "String",
        "description": "File name of the invoice PDF. Download it with {{API}}/storage/{{fileName}}."
      },
      "invoiceWithAttachments": {
        "type": "String",
        "description": "File name of the invoice PDF with attachments. Download it with {{API}}/storage/{{fileName}}."
      },
      "connectedFileCount": {
        "type": "Integer",
        "description": "Count of connected files to the invoice."
      }
    }
  },
  "distributionCode": {
    "type": "ChoiceString",
    "description": "Distribution method used for the invoice. Can be one of LETTER, EMAIL or NULL."
  },
  "documentTemplateCode": {
    "type": "String",
    "description": "Template used on the invoice. Determines how the invoice PDF will appear."
  },
  "currency": {
    "type": "Nested",
    "Nested": {
      "invoiceCurrency": {
        "type": "ChoiceString",
        "description": "Invoice currency. This is what currency we should use in the invoice PDF. Can be one of supported currencies."
      }
    }
  },
  "totals": {
    "type": "Nested",
    "Nested": {
      "totalToPay": {
        "type": "Money",
        "description": "Total amount for debtor to pay to close the invoice."
      },
      "total": {
        "type": "Money",
        "description": "Total amount with VAT of the invoice.",
        "required": true
      }
    }
  },
  "balances": {
    "type": "Nested",
    "Nested": {
      "total": {
        "type": "Money",
        "description": "Total balance of the invoice. This is what's left for your debtor to pay in total to close the invoice."
      },
      "totalLocale": {
        "type": "Money",
        "description": "Total balance of the invoice in locale currency. This is what's left for your debtor to pay in total to close the invoice."
      },
      "capital": {
        "type": "Money",
        "description": "Capital balance of the invoice. This is what's left for your debtor to pay from the original amount."
      },
      "capitalLocale": {
        "type": "Money",
        "description": "Capital balance of the invoice in locale currency. This is what's left for your debtor to pay from the original amount."
      }
    }
  },
  "type": {
    "type": "ChoiceString",
    "description": null
  },
  "isRecourse": {
    "type": "Boolean",
    "description": null
  },
  "useRecourse": {
    "type": "Boolean",
    "description": null
  },
  "createdDate": {
    "type": "DateTime",
    "description": null
  },
  "createdBy": {
    "type": "String",
    "description": null
  },
  "activatedDate": {
    "type": "DateTime",
    "description": null
  },
  "activatedById": {
    "type": "String",
    "description": null
  }
}