> This documentation belongs to Invofox, an AI-powered document processing > platform. The API extracts structured data (fields) from unstructured > documents (invoices, contracts, forms, bank statements, and more). > Key concepts: Account, Environment, Document Type, Field, File, Import, > and Document. When answering, prefer the exact terminology defined in the > Glossary and cite the relevant API Reference endpoint when applicable. # Get a list of documents GET https://api.invofox.com/documents Reference: https://developers.invofox.com/api-reference/main-reference/documents/get-a-list-of-documents ## Authentication - `x-api-key` header (required) — API Key authentication via header ## Request ### Query parameters - `filter` (string, optional) — Query filter in JSON format. Supports filtering by document properties with operators. **Filter by company:** ```json {"company": {"eq": "507f1f77bcf86cd799439011"}} ``` **Filter by public state (single value):** ```json {"publicState": {"in": ["approved"]}} ``` **Filter by multiple states:** ```json {"publicState": {"in": ["approved", "exported"]}} ``` **Filter by document type:** ```json {"type": {"in": ["000000000000000000000017", "000000000000000000000018"]}} ``` **Filter by page count:** ```json {"pageCount": {"eq": 11}} ``` **Filter by date range:** ```json {"creation": {"gte": "2024-01-01T00:00:00.000Z", "lte": "2024-12-31T23:59:59.999Z"}} ``` **Filter by data fields:** ```json {"data.totalAmount": {"gte": 1000}} ``` **Combine multiple filters:** ```json { "type": {"in": ["000000000000000000000017"]}, "publicState": {"in": ["approved"]}, "pageCount": {"eq": 11} } ``` **Filter by client data:** ```json {"clientData.externalId": {"eq": "ORDER-123"}} ``` **Available operators:** * `eq` - Equals * `ne` - Not equals * `gt` - Greater than * `gte` - Greater than or equal * `lt` - Less than * `lte` - Less than or equal * `in` - Value in array - `sort` (string, optional) — Field to sort documents by. Prefix with `-` for descending order (e.g., `-creation` for newest first). - `select` (list of string, optional) — Comma-separated fields to include in the response. You can specify any field path using dot notation. **Common fields:** `_id`, `company`, `publicState`, `type`, `data`, `data.invoiceNumber`, `clientData`, `creation`, `confidence`, `pageCount` **Examples:** - To get basic info: `_id,publicState,type` - To get specific data fields: `_id,data.invoiceNumber,data.totalAmount` - To get all data: `data,type,company,confidence,publicState,creation` - `skip` (double, optional, default: 0) — **`(List pagination element)`** number of documents to skip of the list .The list is made up of documents that comply with the terms have been defined in the query.The skips start from the top of the list. - `limit` (double, optional, default: 50) — **`(List pagination element)`** total number of documents to retrieve (max. 500) of the list.The retrieval starts from the established position by the value of the param skip. ## Response ### 200 List of documents - `skip` (double, optional) - `limit` (double, optional) - `count` (double, optional) - `result` (list of Document, optional) ## Errors ### 400 Bad Request Error Missing some or all parameters - `code` (string, optional) - `additionalInfo` (ErrMissingParamsAdditionalInfo, optional) ### 429 Too Many Requests Error Too many requests were sent to the server in a short period of time. The response contains headers conforming to the [ratelimit standardization draft adopted by the IETF](https://github.com/ietf-wg-httpapi/ratelimit-headers/blob/main/draft-ietf-httpapi-ratelimit-headers.md/) * RateLimit-Limit - Limit of requests per window * RateLimit-Remaining - Remaining requests for current window * RateLimit-Reset - Seconds until window resets * Retry-After - Seconds caller should wait before retrying - `code` (string, optional) ### 500 Internal Server Error Unkown server error - `code` (string, optional) ## Types ### Document - `_id` (string, optional) - `account` (string, optional) — Account the document belongs to. - `environment` (string, optional) — Environment the document belongs to. - `company` (string, optional) — Company the document belongs to. - `creator` (string, optional) — User that uploaded the document - `clientData` (DocumentClientData, optional) — "Additional data to be added to each document. Must be an object or an array of objects. If data to be specified to each document is different, this parameter should have the following format: `[ \{ _filename: \, : }, ... \{ _filename: \, : } ]`." - `type` (enum, optional) - Allowed values: `invoice`, `deliveryNote`, `promissoryNote`, `ticket`, `supplyInvoice` - `name` (string, optional) — Original name of the uploaded file - `isGroundTruth` (boolean, optional) — Indicates the document is marked as Ground Truth (GT) - `creation` (string, optional) — Upload timestamp - `images` (list of string, optional) — Array of Azure Storage URLs (SAS) to access the document extracted images - `original` (string, optional) — Azure Storage URL (SAS) to access the original file - `mimetype` (string, optional) - `data` (map from string to any, optional) — Extracted document data. Structure varies by document type. - `publicState` (enum, optional, default: processing) - Allowed values: `processing`, `pendingCorrection`, `discarded`, `approved`, `exported`, `error` - `confidence` (enum, optional) - Allowed values: `high`, `medium`, `low` - `processInfo` (DocumentProcessInfo, optional) - `validationInfo` (DocumentValidationInfo, optional) - `approvalInfo` (DocumentApprovalInfo, optional) - `import` (DocumentImport, optional) - `exports` (list of DocumentExportsItems, optional) - `geometry` (DocumentGeometry, optional) - `deleted` (boolean, optional) — Indicates whether the document has been logically deleted - `duplicated` (boolean, optional, deprecated) ### ErrMissingParamsAdditionalInfo - `param` (string, optional) — Name of missing parameter, if there is only one - `params` (list of string, optional) — Names of missing parameters, if there are several ### DocumentClientData "Additional data to be added to each document. Must be an object or an array of objects. If data to be specified to each document is different, this parameter should have the following format: `[ \{ _filename: \, : }, ... \{ _filename: \, : } ]`." ### DocumentProcessInfo - `result` (enum, optional) - Allowed values: `verified`, `not verified`, `discarded` ### DocumentValidationInfo - `errors` (list of Error, optional) — Array of validation errors - `result` (enum, optional) - Allowed values: `valid`, `discarded` - `comments` (string, optional) — Comments added by the validator user (if any) - `validator` (string, optional) — The user that added the validation (if any) ### DocumentApprovalInfo - `beginning` (string, optional) - `result` (enum, optional) - Allowed values: `approved`, `processing` - `comments` (string, optional) - `appliedWorkflow` (DocumentApprovalInfoAppliedWorkflow, optional) - `steps` (list of DocumentApprovalInfoStepsItems, optional) ### DocumentImport - `ref` (string, optional) - `channel` (string, optional) - `info` (DocumentImportInfo, optional) ### DocumentExportsItems - `timestamp` (string, optional) - `ref` (string, optional) - `summary` (list of DocumentExportsItemsSummaryItems, optional) ### DocumentGeometry - `pages` (list of DocumentGeometryPagesItems, optional) - `boxes` (DocumentGeometryBoxes, optional) — "Keys replicate structure of field `data` whereas values are objects of the form \ \{ \ page: number, \ box: array(number) \ } \ where \ `page` is the index of the page where the box is located. \ `box` has 8 coordinates representing the vertices of the box \ \[p1x, p1y, p2x, p2y, p3x, p3y, p4x, p4y] \ " ### Error - `severity` (enum, optional) — Error severity - Allowed values: `high`, `medium`, `low` - `code` (enum, optional) — Descriptive error code * `ERR_FILE_TOO_BIG` - The uploaded file is too big (max 50 MB) * `ERR_TOO_MANY_PAGES` - Document has too many pages (max. 10) * `ERR_UNSUPPORTED_FILE_FORMAT` - Document's format not supported * `ERR_EMPTY_VALUE` - No value extracted * `ERR_INVALID_FORMAT` - Extracted value has an invalid format * `ERR_LOW_CONFIDENCE` - Extracted value has low confidence * `ERR_HANDWRITTEN_DOC` - Document is handwritten * `ERR_INVALID_DOC_TYPE` - Document type is unknown (not invoice, ticket, etc) * `ERR_CROPPED_DOC` - Document is cropped hence has missing information * `ERR_MULTI_DOC_PAGE_FOUND` - File contains multiple documents * `ERR_PAGES_MISSING` - Document has missing pages hence is incomplete * `ERR_DUPLICATED_DOCUMENT` - Document is duplicated * `ERR_MISSING_INFO` - Document is missing required information * `ERR_BAD_QUALITY` - Document has bad quality * `ERR_OTHER` - Generic error - Allowed values: `ERR_FILE_TOO_BIG`, `ERR_TOO_MANY_PAGES`, `ERR_UNSUPPORTED_FILE_FORMAT`, `ERR_EMPTY_VALUE`, `ERR_INVALID_FORMAT`, `ERR_LOW_CONFIDENCE`, `ERR_HANDWRITTEN_DOC`, `ERR_INVALID_DOC_TYPE`, `ERR_CROPPED_DOC`, `ERR_MULTI_DOC_PAGE_FOUND`, `ERR_PAGES_MISSING`, `ERR_BAD_QUALITY`, `ERR_OTHER` - `timestamp` (string, optional) — Timestamp when the error happened - `user` (string, optional) — User that reported the error (if any) - `info` (ErrorInfo, optional) — Additional information related to the error (if any) - `fields` (list of ErrorFieldsItems, optional) — document data fields related to the error (if any) ### DocumentApprovalInfoAppliedWorkflow ### DocumentApprovalInfoStepsItems - `date` (string, optional) - `type` (string, optional) - `info` (DocumentApprovalInfoStepsItemsInfo, optional) ### DocumentImportInfo ### DocumentExportsItemsSummaryItems ### DocumentGeometryPagesItems - `width` (double, optional) — Page width in units - `height` (double, optional) — Page height in units - `unit` (enum, optional) — Unit measure of width and height - Allowed values: `inch`, `pixel` - `angle` (double, optional) — Rotation of the page ### DocumentGeometryBoxes "Keys replicate structure of field `data` whereas values are objects of the form \ \{ \ page: number, \ box: array(number) \ } \ where \ `page` is the index of the page where the box is located. \ `box` has 8 coordinates representing the vertices of the box \ \[p1x, p1y, p2x, p2y, p3x, p3y, p4x, p4y] \ " ### ErrorInfo Additional information related to the error (if any) ### ErrorFieldsItems - `name` (string, optional) — field name - `prefix` (string, optional) — If the field is an array, the key of the array in data - `index` (double, optional) — If the field belongs to an array, the index in the array - `groupIndex` (double, optional) — If the field is an additional data, the first index in data.additionalData array - `splitIndex` (double, optional) — If the field is an additional data, the second index in data.additionalData array ### DocumentApprovalInfoStepsItemsInfo ## Examples **Response** ```json { "skip": 1.1, "limit": 1.1, "count": 1.1, "result": [ { "_id": "string", "account": "string", "environment": "string", "company": "string", "creator": "string", "clientData": {}, "type": "invoice", "name": "string", "isGroundTruth": true, "creation": "2024-01-15T09:30:00Z", "images": [ "string" ], "original": "string", "mimetype": "string", "data": {}, "publicState": "processing", "confidence": "high", "processInfo": { "result": "verified" }, "validationInfo": { "errors": [ { "severity": "high", "code": "ERR_FILE_TOO_BIG", "timestamp": "2024-01-15T09:30:00Z", "user": "string", "info": {}, "fields": [ { "name": "string", "prefix": "string", "index": 1.1, "groupIndex": 1.1, "splitIndex": 1.1 } ] } ], "result": "valid", "comments": "string", "validator": "string" }, "approvalInfo": { "beginning": "2024-01-15T09:30:00Z", "result": "approved", "comments": "string", "appliedWorkflow": {}, "steps": [ { "date": "2024-01-15T09:30:00Z", "type": "string", "info": {} } ] }, "import": { "ref": "string", "channel": "string", "info": {} }, "exports": [ { "timestamp": "2024-01-15T09:30:00Z", "ref": "string", "summary": [ {} ] } ], "geometry": { "pages": [ { "width": 1.1, "height": 1.1, "unit": "inch", "angle": 1.1 } ], "boxes": {} }, "deleted": true, "duplicated": true } ] } ``` **SDK Code** ```python import requests url = "https://api.invofox.com/documents" querystring = {"filter":"{\"type\":{\"in\":[\"000000000000000000000017\"]},\"publicState\":{\"in\":[\"approved\"]},\"pageCount\":{\"eq\":11}}","limit":"50","select":"data,type,company,publicState,creation"} headers = {"x-api-key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.invofox.com/documents?filter=%7B%22type%22%3A%7B%22in%22%3A%5B%22000000000000000000000017%22%5D%7D%2C%22publicState%22%3A%7B%22in%22%3A%5B%22approved%22%5D%7D%2C%22pageCount%22%3A%7B%22eq%22%3A11%7D%7D&limit=50&select=data%2Ctype%2Ccompany%2CpublicState%2Ccreation")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```