Overview/Requests
Overview

Requests

You interact with AzoraOne by sending HTTP requests. A request contains headers and, for most methods, a JSON body.

Syntax

A request URL will look like this:

https://api.azora.one/{api}/{version}/{resource}/{identifier}

A request URL might also contain two sets of resources and identifiers:

https://api.azora.one/{api}/{version}/{resource}/{identifier}/{resource}/{identifier}

{api} is the short name of your API and can be found under any operation on the API Explorer pages. {version} is the API version, currently v1. {resource} and {identifier} are the name and unique ID of the object you are acting on, for example suppliers and 12.

Query parameters

Some endpoints accept optional query parameters, appended to the URL after a ? and separated by &, to filter or extend the response. For example, to restrict extraction to a specific verification series when retrieving a supplier invoice:

https://api.azora.one/{api}/{version}/companies/123/files/456/supplierInvoices?verificationSeries=A

Available query parameters vary by endpoint. Commonly used ones include:

  • verificationSeries: restricts extraction to a specific verification series. Decreases extraction time and can improve accuracy, since false positives from other series won't interfere with the result. Must be formatted according to RFC 1738; an invalid value returns a 400 response.
  • extended: when set to true, includes extended data in the response.
  • origin: when set to true, includes origin data in the response.

See each operation's page in the API Explorer for the full list of query parameters it accepts.

Pagination

List operations that return many items, such as retrieving all companies, files, customers or patterns, support pagination with pageNumber and pageSize:

https://api.azora.one/{api}/{version}/companies/123/files?pageNumber=1&pageSize=10

If either pageNumber or pageSize is supplied, both must be. Supplying only one returns a 400 response. Files, customers and patterns default to page 1 at a standard page size when neither is supplied. Companies is the exception: without pageNumber/pageSize, Retrieve all companies returns every matching company unpaginated; the two become required together only when the metrics query parameter is also set to true. pageSize has a maximum, which varies by operation, for example 30 for company metrics and 100 for files, customers and patterns. See each operation's page in the API Explorer for its specific default and maximum.

Acquiring resources

The HTTP GET method is used to retrieve resources from AzoraOne. To get the representation of a specific resource, add the identifier to the URL. For example, to retrieve the supplier with ID 12 at company with ID 123, send a GET request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/suppliers/12

Creating resources

The HTTP POST method is used to create new resources. For example, to create a new supplier, send a POST request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/suppliers

Most requests to AzoraOne will contain resource IDs. According to the RFC1738 specification, only alphanumerics, the special characters $-_.+!*'(), and reserved characters used for their reserved purposes may be used unencoded within a URL. Although safe when used for their defined purpose, reserved characters (; / ? : @ = &) should not be used unencoded for other purposes, including resource IDs. So, when posting new resources, make sure the resource ID only contains safe characters as specified in RFC1738, with no reserved characters present:

Alphanumerics [0-9a-zA-Z], special characters $-_.+!*'(),

Resource IDs containing characters not considered safe will generate an error message.

Creating multiple resources

It is possible to create more than one resource in a single API call for some resource groups. Compared to multiple requests, a single bulk request can improve your application's performance by decreasing network round trips and increasing throughput. Monitor performance when implementing bulk requests, and consider limiting your call to 100 or fewer items in the beginning. Creating multiple entities via a single request is limited to suppliers, customers and progenitors in the current API version. To create multiple suppliers in a single request, send a POST request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/suppliers/multiple

Each entry in the list is processed independently and is not transactional: if one entry fails, entries that already succeeded are not rolled back. This is reflected in the response:

  • A 200 response means every entry succeeded.
  • A 409 response means some entries succeeded and some failed. Both cases share the same shape, a list called objectList with one result per entry, in the order submitted.
  • A 400 response can mean two different things: either the request itself was malformed, for example an invalid companyID or a missing body, in which case you get the standard error response, or every entry in the list individually failed validation, in which case you get the same objectList shape as the 200 and 409 responses, just with a 400 status. Check whether the body has an objectList to tell these apart, rather than relying on the status code alone.

Updating resources

The HTTP PUT method is used to update existing resources, and to submit bookkeeping data to a file for the first time. PUT assumes you are sending the complete object, and that complete object replaces any existing object at that URI. For example, to update the supplier with ID 12 at company with ID 123, send a PUT request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/suppliers/12

Once you have received the response, check it to confirm the resource was updated correctly.

Partially updating resources

The HTTP PATCH method is used to modify a selection of properties on a resource, rather than the complete object. Unlike PUT, PATCH only changes the properties included in the request body, leaving everything else unchanged. For example, to update a file's type and verificationSeries, send a PATCH request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/files/456

Only the properties supplied in the request body are changed. Properties left out are unaffected.

Deleting resources

The HTTP DELETE method is used to delete existing resources. Add the identifier to the URL to delete that resource. For example, to delete the supplier with ID 12 at company with ID 123, send a DELETE request to the following URL:

https://api.azora.one/{api}/{version}/companies/123/suppliers/12

Some resources, such as memories, are deleted at the company level and do not take an additional identifier: a DELETE request to /companies/{companyID}/memories deletes all memories for that company.

Date formatting

Parameters like invoiceDate use a format based on ISO-8601:

Date: 2020-09-02

Date and time: 2020-09-02 08:30:00

Errors

For the full list of error codes and what each one means, see the Responses page.