Fetch Invoices

Many types of products examine invoices for a customer and provide feedback on them. A typical product might analyze incoming invoices and add metadata like a credit score for each invoice. This tutorial explains how to iterate through invoices, examine them, and add metadata.

We use the Query Invoices API to retrieve a collection of invoices. To fetch a large number of invoices, we must use filtering and pagination. Here’s how it works.

Step 1 - Query for invoices based on their invoice date

In this example, we will first query for invoices using the invoice date. We will fetch all invoices dated December 1st, 2021, and later. We will specify a page size of 10 which gives us a small number of invoices in each query.

var client = new RestClient("https://api.sbx.lockstep.io/api/v1/Invoices/query?filter=invoiceDate%20ge%202021-12-01&order=invoiceDate%20asc&pageSize=10");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("Api-Key", "REDACTED");
IRestResponse response = client.Execute(request);

The results from this API call will list the first ten invoices, since you specified a page size of 10. Your results will include a field called totalCount, which tells you exactly how many records that matched your filter:

{
  "records": [
    {
      "groupKey": "1c043d8f-ce7e-4cf6-aa8e-a08b0220d327",
      "invoiceId": "23c57f74-b643-47bf-a82b-c90984b1fc1b",
      "companyId": "dab105d3-8fa3-4c4d-990a-c00cac91a064",
      "customerId": "453060e9-393e-4584-a5f6-31d8581c3969",
      "erpKey": "58784FB2-DD9F-4CAB-B672-575922DBFE3F",
      "purchaseOrderCode": "07E9A",
      "referenceCode": "DEMOI000000010",
      ...
    }
  ],
  "totalCount": 1919,
  "pageSize": 10
}

This is “Page Zero” of your results. You can then make additional API calls by specifying ?pageNumber=1 and so on.

Step 2 - Fetch company information

The results we get back include information about the invoice, but they don’t tell us anything about the company that wrote the invoice. We could use the Retrieve Company API to fetch the company. Here’s how that works:

var client = new RestClient("https://api.sbx.lockstep.io/api/v1/Companies/6e5ec64e-efaf-45ca-afe3-9938e92b15cd");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("Api-Key", "REDACTED");
IRestResponse response = client.Execute(request);

The results contain information about the company:

{
  "companyId": "6e5ec64e-efaf-45ca-afe3-9938e92b15cd",
  "companyName": "Almighty Almonds",
  "erpKey": "9F70EA9B-7E5E-4568-87CF-D8BFD1B1685E",
  "companyType": "Customer",
  "companyStatus": "Active",
  ...
}

You can then use this information to make a credit score determination for this company.

Step 3 - Modify query to include companies

If you prefer, you can fetch invoices and companies with the same query rather than making separate API calls. Let’s modify our Query Invoices call to also fetch company data by adding ?include=Company to our request.

var client = new RestClient("https://api.sbx.lockstep.io/api/v1/Invoices/query?filter=invoiceDate%20ge%202021-12-01&order=invoiceDate%20asc&pageSize=10&include=Company");

Now, our results include information about the company that sent the invoice. You could use this information to run a credit score on the company (not shown in this tutorial). Most APIs within Sage Network permit you to fetch additional information in a single API call.

Step 4 - Save a note with the credit score

Our final step is to save a comment indicating the credit score of the company. We will use the Create Notes API to upload this credit score as text for our customer to read. Note that these are sample values, assuming you ran a credit score on the target company and use the invoice key that you queried for earlier.

var client = new RestClient("https://api.sbx.lockstep.io/api/v1/Notes");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/*+json");
request.AddHeader("Api-Key", "REDACTED");
request.AddParameter("application/*+json", "[{\"tableKey\":\"Invoice\",\"objectKey\":\"b9d47e4e-c8ee-4ee1-9e96-26542eecaefb\",\"noteText\":\"The credit risk score is 57/100.\",\"noteType\":\"note\"}]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

When this API call succeeds, this note is now attached to this object. A user can then view this note in any Sage Network product, such as Sage Network Inbox.