Orders Workflow

Operation	Call
Create Order	`POST /a4a/3.0/api/orders/create/`
Get Order by ID	`GET /a4a/3.0/api/orders/id/{id}`
Get Order by Code	`GET /a4a/3.0/api/orders/code/{code}`
Cancel Order	`POST /a4a/3.0/api/orders/cancel/`

The three identifiers

Identifier	Example	What it is	Use it with
Order `id`	`299`	The order's numeric ID	`GET /orders/id/{id}`, Cancel Order
Order `code`	`HFUEBSFQJGSRELUH`	The order's unique alphanumeric code	`GET /orders/code/{code}`
`icgid`	`CY00001234406861`	The company's ICG ID, returned by Search	`GET /report/{type}/code/{code}`, and `code` on order items

Each item inside an order also has its own id and code (for example 1327 and HOXYBHRLCUWXYGYY) the item-level identifiers, distinct from the order-level ones.

Create an order

POST https://sandbox-v3.api4all.io/a4a/3.0/api/orders/create/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reference": "123456",
  "items": [
    {
      "code": "CY00001234406861",
      "reference": "123456",
      "language": "EN",
      "product": "2200",
      "format": "JSON",
      "speed": "Normal",
      "freshinvestigation": 0,
      "comments": ""
    }
  ]
}

reference is yours: Any value you want for internal tracking. It appears on both the order and the item, and you'll need it again if you cancel.

An order can carry multiple items, so you can request several reports on different companies, or different products for the same company in a single call.

See Product Codes for every field and its allowed values.

The order object

Both Create Order and the two Get Order calls return the same shape:

{
  "messages": [],
  "searchdate": "2025-12-01 17:36:57.057",
  "searchtype": "id",
  "searchterm": "299",
  "records": 1,
  "orders": [
    {
      "id": "299",
      "code": "HFUEBSFQJGSRELUH",
      "reference": "123456",
      "dateplaced": "2025-12-01 17:36:46",
      "datestarted": "",
      "information": "",
      "comments": "",
      "items": "1",
      "status": "Received",
      "details": [
        {
          "id": "1327",
          "code": "HOXYBHRLCUWXYGYY",
          "reference": "123456",
          "icgid": "CY00001234406861",
          "name": "INFOCREDIT GROUP LIMITED",
          "reg_no": "C4404",
          "country": "CY",
          "product": "API4ALL - Structure Report",
          "format": "JSON",
          "speed": "Normal",
          "investigation": "0",
          "report": null,
          "dateplaced": "2025-12-01 17:36:56",
          "status": "Received"
        }
      ]
    }
  ]
}

Field	Notes
`messages`	Array of messages relating to the request
`searchtype`	How the order was looked up
`searchterm`	The value that was looked up
`records`	Number of orders returned
`items`	Number of items on the order, as a string
`status`	Order status
`details`	The order's items, each with its own status
`report`	The report file, once ready. `null` while the order is still in progress

Note that the order carries a status and each item carries its own status.

Retrieve an order

By order ID:

GET https://sandbox-v3.api4all.io/a4a/3.0/api/orders/id/299
Authorization: Bearer {access_token}

By order code:

GET https://sandbox-v3.api4all.io/a4a/3.0/api/orders/code/HFUEBSFQJGSRELUH
Authorization: Bearer {access_token}

Both return the same order. The report is delivered as a binary file in the report field of the order detail once the order completes.

📘
Two ways to get the report. You can read it from the order's report field, or fetch it directly by company code from the matching report endpoint. For example GET /a4a/3.0/api/report/structure/code/CY00001234406861.

Order statuses

Status	Meaning
`Received`	The order has been accepted and is queued
`In progress`	The order is in progress
`Ready`	The order is ready
`Cancelled`	The order was cancelled
`Failed`	The order has failed

Cancel an order

POST https://sandbox-v3.api4all.io/a4a/3.0/api/orders/cancel/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "orders": [
    {
      "id": 123,
      "reference": "123456",
      "comments": ""
    }
  ]
}

Field	Type	Required	Description
`id`	integer	Yes	The unique Order ID generated at the time of order creation
`reference`	string	Yes	Your reference number for the order
`comments`	string	No	Any notes regarding the cancellation

When cancellation is possible

Cancellation only works when both conditions hold:

The order was placed with fresh investigation enabled (freshinvestigation: 1), and
The order status is still Received.

Once an investigation for data already on file (freshinvestigation: 1) is underway, the window for cancellation has closed.

The response is the order object with status updated to Cancelled, on both the order and its items.

Putting it together

Search ──► company_code (ICG ID)
             │
             ▼
      POST /orders/create/  ──►  order id + order code
             │
             ├──► GET /orders/id/{id}      ──► poll status
             ├──► GET /orders/code/{code}  ──► poll status
             │
             ├──► POST /orders/cancel/     ──► only if freshinvestigation = 1
             │                                  and status = Received
             ▼
      report ready ──► read `report` field
                   └─► or GET /report/{type}/code/{icgid}

The three identifiers

Create an order

The order object

Retrieve an order

Two ways to get the report. You can read it from the order's report field, or fetch it directly by company code from the matching report endpoint. For example GET /a4a/3.0/api/report/structure/code/CY00001234406861.

Order statuses

Cancel an order

When cancellation is possible

Putting it together

Two ways to get the report. You can read it from the order's `report` field, or fetch it directly by company code from the matching report endpoint. For example `GET /a4a/3.0/api/report/structure/code/CY00001234406861`.