Querying

 

The Codat API uses a simple, flexible query language to enable filtering of response data.

Data returned from the API can be filtered by including a URL encoded query parameter with your request.

  • The query takes the form of {propertyName}={value}
  • For numeric and date properties greater-than and less-than comparison (>/<) are also available
  • Multiple query clauses can be specified, separated by ampersands (&&) for AND queries or pipes (||) for OR queries.
  • Sub-properties can be accessed by separating with a dot (see example 3 below)

📘

To combine AND and OR queries you will need to use parentheses ({ and }) like so:

query={totalAmount>100 || totalAmount < 50} && status != paid

Example Queries

1. Invoices with amounts outstanding

GET /companies/{companyId}/data/invoices?query=amountDue%3e0

var query = new InvoicesQuery(companyId, 'amountDue>0')
  .run(codat.uat(apiKey));
var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "amountDue>0");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;

2. GBP Invoices

GET /companies/{companyId}/data/invoices?query=currency%3dGBP

var query = new InvoicesQuery(companyId, 'currency=GBP')
  .run(codat.uat(apiKey));
var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "currency=GBP");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;

3. Invoices to a particular customer

GET /companies/{companyId}/data/invoices?query=customerRef.id%3d61

var query = new InvoicesQuery(companyId, 'customerRef.id=61')
  .run(codat.uat(apiKey));
var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "customerRef.id=61");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;

4. Outstanding Invoices of value less than 1000

GET /companies/{companyId}/data/invoices?query=amountDue%3e0%26%26totalAmount%3c1000

var query = new InvoicesQuery(companyId, 'amountDue>0&&totalAmount<1000')
  .run(codat.uat(apiKey));
var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "amountDue>0&&totalAmount<1000");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;