Responses

A request returns a response that indicates the result in two ways: with the standard HTTP response status code and with a corresponding JSON body.

HTTP response status codes

AzoraOne APIs use standard HTTP status codes to indicate success or failure of API requests. In general, codes in the 200 range indicate a successful request, codes in the 400 range indicate a user error in the request (for example, a required parameter was omitted or a value was invalid), and codes in the 500 range indicate an unintended error within our API, servers or databases.

Success

A successful request returns an HTTP status code in the 200 range.

200: OK — A resource has been returned.
202: Accepted — The request has been accepted for processing, but the processing has not been completed.

User error

A request with one or more user errors returns an HTTP status code in the 400 range.

400: Bad Request — The request cannot be fulfilled due to bad syntax.
401: Unauthorized — The request contains invalid authorization credentials.
403: Forbidden — The request was blocked due to security measures.
404: Not Found — The resource could not be found.
409: Conflict — One or more entities have not succeeded on a bulk request.
412: Precondition Failed — File is not ready for extraction.

Server error

A request that causes a server error returns an HTTP status code in the 500 range.

500: Internal Server Error — The request was terminated due to an internal error on our server.
501: Not Implemented — This resource has been added to the API but not yet implemented on our servers.
503: Service Unavailable — The API is currently unavailable.

JSON bodies

AzoraOne APIs return JSON in the response body. If the request is successful, you'll receive the data you asked for in the body. If the request failed, you'll receive a list of error messages instead.

Success body

As an example of a successful request, the response body below is returned when successfully adding a valid company to the companies resource.

{
  "success": true,
  "data": {
    "companyID": "1",
    "companyName": "SmallCorp",
    "companyProxy": "Account Group Inc",
    "active": true,
    "precognition": {
      "active": true
    }
  },
  "extended": "",
  "meta": "",
  "origin": "",
  "time": "2020-09-01 14:02:47"
}

All successful response bodies share the same basic structure and contain the following parameters:

success — Indicates whether the request was successful.
data — Contains the data requested.
extended — Contains extended information when extracting data from a file.
meta — Contains non-essential data connected to the requested resource.
origin — Contains information on where the extraction result was generated.
time — Indicates the date and time the request was returned.

Error body

As an example of a failed request, the response body below is returned when failing to add a valid company to the companies resource.

{
  "success": false,
  "data": [
    {
      "code": 111402,
      "message": "Company ID is not valid.",
      "details": "",
      "element": "companyID"
    }
  ],
  "extended": "",
  "meta": "",
  "origin": "",
  "time": "2020-09-01 13:57:19"
}

All unsuccessful response bodies share the same basic structure and contain the following parameters:

success — Indicates whether the request was successful.
data — Contains a list of error objects to help with debugging.
extended — Contains extended information when extracting data from a file.
meta — Contains non-essential data connected to the requested resource.
origin — Contains information on where the extraction result was generated.
time — Indicates the date and time the request was returned.

Multiple response bodies

Creating multiple entities in a single request is limited to suppliers, customers and progenitors (see Creating multiple resources). As an example, the response body below is returned when adding two suppliers in a single bulk request, where the first entry fails and the second succeeds.

{
  "objectList": [
    {
      "success": false,
      "data": [
        {
          "code": 611401,
          "message": "Supplier ID not found.",
          "details": "",
          "element": "supplierID"
        }
      ],
      "objectID": "1"
    },
    {
      "success": true,
      "data": {
        "supplierID": "2",
        "supplierName": "Telenor",
        "corporateIdentityNumber": "556421-0309",
        "bankAccountNumber": "5331-1338",
        "plusGiroNumber": "4792603-5",
        "iban": "SE2195000099603447926035",
        "vatNumber": "SE556421030901",
        "countryOfOrigin": ""
      },
      "objectID": "2"
    }
  ],
  "time": "2020-03-17 07:10:46"
}

All multiple response bodies share the same basic structure and contain the following parameters:

objectList — Contains a list of individual responses for each object.
time — Indicates the date and time the request was returned.

The objects in objectList are the same as in a single response, with one parameter added:

objectID — Indicates the order the objects were submitted in.

Each entry in a bulk request is processed independently and is not transactional: if one entry fails, entries that already succeeded are not rolled back. A bulk request can return one of three HTTP status codes:

200 — Every entry succeeded.
409 — Some entries succeeded and some failed, as in the example above.
400 — Either the request itself was malformed, for example an invalid companyID or a missing body, in which case you receive the standard error response, or every entry in the list individually failed validation, in which case you receive 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.

Error object

If a request was not successful, you'll find a list of error objects in the data parameter.

{
  "code": 111402,
  "message": "Company ID is not valid.",
  "details": "",
  "element": "companyID"
}

All error objects share the same basic structure and contain the following parameters:

code — Contains an error code indicating which error occurred.
message — Contains a brief description of the error.
details — Contains a detailed description of the error.
element — Contains the parameter name associated with the error.

Error codes

The following error codes are implemented in API version v1. We'll add error codes continuously.

101150 - Query parameter is not defined.
101151 - Missing required query parameter.
101152 - Query parameter is not valid.
101211 - Request body is missing.
111401 - Company ID not found.
111402 - Company ID is not valid.
111403 - Company ID already exists.
111502 - Company name is not valid.
113102 - Corporate identity number is not valid.
113202 - Bankgiro number is not valid.
113212 - Plusgiro number is not valid.
113222 - IBAN is not valid.
113232 - Vat number is not valid.
113242 - CountryCode is not valid.
151210 - Body is missing.
151401 - Type ID is missing.
151402 - Type ID is not valid.
151403 - Type ID already exists.
151405 - Type ID is not active.
151551 - Endpoint is missing.
151552 - Endpoint is not valid.
151553 - Endpoint already exists.
151556 - Endpoint is readonly.
151901 - Type is missing.
151902 - Type is not valid.
151903 - Type already exists.
151906 - Type is readonly.
211101 - All parameters are missing.
211202 - File format is not valid.
211211 - File is missing.
211212 - File is not valid.
211214 - File could not be processed.
211215 - File is not ready for extraction.
211302 - File length is not valid.
211401 - File ID not found.
211402 - File ID is not valid.
211403 - File ID already exists.
211501 - File name is missing.
211502 - File name is not valid.
211901 - Type does not exist.
211902 - Type is not valid.
211912 - Verification series is not valid.
211952 - Sub type is not valid.
311101 - Invoice number and OCR number are missing.
311401 - Supplier ID not found.
311402 - Supplier ID is not valid.
311601 - Date is missing.
311602 - Date is not valid.
311801 - Description is missing.
311802 - Description is not valid.
311911 - Verification series is missing.
311912 - Verification series is not valid.
311951 - Sub type is missing.
311952 - Sub type is not valid.
315211 - Total sum is missing.
315212 - Total sum is not valid.
315222 - VAT is not valid.
315301 - Invoice number is missing.
315302 - Invoice number is not valid.
315311 - OCR number is missing.
315312 - OCR number is not valid.
315321 - ReferenceNumber is missing.
315322 - ReferenceNumber number is not valid.
315331 - OrderNumber number is missing.
315332 - OrderNumber number is not valid.
315401 - Account row is missing.
315402 - Account row is not valid.
315492 - Debit and credit do not balance.
315502 - ourRef is not valid.
315512 - yourRef is not valid.
321101 - Invoice number and OCR number are missing.
321401 - Customer ID not found.
321402 - Customer ID is not valid.
321601 - Date is missing.
321602 - Date is not valid.
321801 - Description is missing.
321802 - Description is not valid.
321911 - Verification series is missing.
321912 - Verification series is not valid.
321951 - Sub type is missing.
321952 - Sub type is not valid.
325211 - Total sum is missing.
325212 - Total sum is not valid.
325222 - VAT is not valid.
325301 - Invoice number is missing.
325302 - Invoice number is not valid.
325311 - OCR number is missing.
325312 - OCR number is not valid.
325321 - ReferenceNumber is missing.
325322 - ReferenceNumber number is not valid.
325331 - OrderNumber number is missing.
325332 - OrderNumber number is not valid.
325401 - Account row is missing.
325402 - Account row is not valid.
325492 - Debit and credit do not balance.
325502 - ourRef is not valid.
325512 - yourRef is not valid.
411601 - Date is missing.
411602 - Date is not valid.
411801 - Description is missing.
411802 - Description is not valid.
411911 - Verification series is missing.
411912 - Verification series is not valid.
411951 - Sub type is missing.
411952 - Sub type is not valid.
415401 - Account row is missing.
415402 - Account row is not valid.
415492 - Debit and credit do not balance.
452102 - Label is not valid.
452202 - Value is not valid.
452302 - Method is not valid.
461101 - Identifiers are missing.
461102 - Identifiers are not valid.
461213 - Pattern already exists.
461401 - Pattern ID not found.
461402 - Pattern ID is not valid.
461403 - Pattern ID already exists.
461406 - Pattern ID is readonly.
461901 - Type does not exist.
461902 - Type is not valid.
461912 - Verification series is not valid.
461922 - Source is not valid.
461926 - Source cannot be changed after creation.
511401 - Progenitor ID not found.
511402 - Progenitor ID is not valid.
511403 - Progenitor ID already exists.
511612 - DateTime is not valid.
611001 - Cannot identify a matching supplier.
611101 - Corporate identity number, bankgiro number, plusgiro number, IBAN and suppliertags are missing.
611401 - Supplier ID not found.
611402 - Supplier ID is not valid.
611403 - Supplier ID already exists.
611502 - Supplier name is not valid.
613102 - Corporate identity number is not valid.
613202 - Bankgiro number is not valid.
613212 - Plusgiro number is not valid.
613222 - IBAN is not valid.
613232 - Vat number is not valid.
613242 - CountryCode is not valid.
617102 - Supplier tag is not valid.
621101 - Legal registration number, vat number and customertags are missing.
621401 - Customer ID not found.
621402 - Customer ID is not valid.
621403 - Customer ID already exists.
621501 - Customer name is missing.
621502 - Customer name is not valid.
621712 - Customer number is not valid.
623112 - Legal registration number is not valid.
623232 - Vat number is not valid.
623242 - CountryCode is not valid.
627102 - Customer tag is not valid.
711001 - Endpoint does not exist.
711005 - Endpoint is not active.
711211 - Request body is missing.
711512 - Endpoint is not valid.
711513 - Endpoint already exists.
711516 - Endpoint is readonly.
711522 - Type is not valid.
711523 - Type already exists.
911401 - Supplier ID is missing.
911402 - Supplier ID is not valid.
911612 - DateTime is not valid.
911901 - Type does not exist.
911902 - Type is not valid.
1000010 - API certification error.
1009100 - Something unexpected happened.
1009210 - Database connection failed.
1009220 - Database operation failed.
1009230 - Database temporarily offline.