# Hypatos REST API # Introduction The Hypatos API is organized around REST. The majority of the endpoints provide CRUD functionality for resources. The API is also exposing Intent Resources which mimic user intents or actions. The Hypatos API uses [OAuth 2.0 Client Credential Grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.4) to authenticate requests. Before making any requests to any endpoint a client must authenticate with the authorization server and requests an access token from the [token endpoint](#operation/requestAccessToken). ````sh POST /auth/token HTTP/1.1 Host: api.cloud.hypatos.ai Content-Type: application/x-www-form-urlencoded Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= grant_type=client_credentials ```` `Authorization` header contains `client_id:client_secret` encoded as explained in [RFC Client Password section](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1). If the authorization server authenticated the client successfully, an access token is issued. Here is an example successful response: ````sh HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token": "mF_9.B5f-4.1JqM", "expires_in": 86400, "scope": "enrichment.write files.read", "token_type": "Bearer", } ```` This token can be used to authenticate the requests to API endpoints by sending a Bearer token in the `Authorization` HTTP header. The following example demonstrates how to use the access token to retrieve a list of documents. ````sh GET /v2/documents HTTP/1.1 Host: api.cloud.hypatos.ai Authorization: Bearer mF_9.B5f-4.1JqM ```` # Versioning Changes to this API are released regularly. We use [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) scheme for versioning so that the clients can identify any backward-incompatible changes easily. Briefly summarized one can say, if the MAJOR version of the new API version didn't change you can expect the new version to be backward-compatible. # Rate limits In order to maximise the stability of our API, we institue rate limits for all of API endpoints. Clients who send too many requests over a given period of time will see error responses that show up as status code [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429). When you see error responses with status code 429, it means you exhausted your current quota and need to withhold from sending further requests until the quota is reset. We encourage you not to wait until you get a 429 error but to monitor your quota in each request. In each response you receive from the API, you will find HTTP headers providing the details about your current quota. Here is the list of the HTTP headers: * `x-ratelimit-limit`: Indicates the quota associated to the client in the current time-window followed by the description of the quota policy. * `x-ratelimit-remaining`: Indicates the number of remaining requests in the current time-window * `x-ratelimit-reset`: Indicates the number of seconds until quota reset of the current time-window Please note that IETF is currently in the process of publishing a standard for these headers. Please explore the [draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) for more details. A basic technique to gracefully handle rate limits is watch for your quota permanently and increase the time between your request as the quota is decreasing. To recover from a 429 error you need a retry mechanism following an exponential backoff schedule. Version: 2.51.0 License: Apache 2.0 ## Servers API EU ``` https://api.cloud.hypatos.ai/v2 ``` API US ``` https://api.cloud.hypatos.com/v2 ``` ## Security ### OAuth2 Type: oauth2 ### Basic Type: http Scheme: basic ## Download OpenAPI description [Hypatos REST API](https://hypatos.redocly.app/_bundle/openapi.yaml) ## Authorization Endpoints for handling the [OAuth 2.0 Client Credentials Grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.4) flow. ### Request an access token - [POST /auth/token](https://hypatos.redocly.app/openapi/authorization/requestaccesstoken.md): Request an access token using your client credentials ## Files Endpoints for management of files ### Upload a file - [POST /files](https://hypatos.redocly.app/openapi/files/uploadfile.md): This endpoint allows a client to upload a binary file. The id returned in the response represents the file in Hypatos systems. It can be used in other endpoints, for example to initiate processing of the file to create a document holding captured data, or to include the file in a case. ### Download a file by id - [GET /files/{id}](https://hypatos.redocly.app/openapi/files/retrievefile.md): Download the content of a file with the given identifier. ## Documents Endpoints for document management ### Retrieve a list of documents - [GET /documents](https://hypatos.redocly.app/openapi/documents/documentslist.md): Retrieve a list of documents. ### Request processing of a file - [POST /documents/process-file](https://hypatos.redocly.app/openapi/documents/processfileintodocument.md): Request a processing of a file that was previously uploaded. The fileId in the request body is representing the identifier of the file that was returned by the upload endpoint. As a result of this request a document will be created and its identifier will be returned in the response. The projectId in the request body is an identifier of the project to create the document in. ### Retrieve a document by id - [GET /documents/{id}](https://hypatos.redocly.app/openapi/documents/documentsgetbyid.md): Retrieve a document by id ### Provide information about a transfer of a document to the target system - [POST /documents/{id}/transfer](https://hypatos.redocly.app/openapi/documents/documentsupdatetransfer.md): Update information about the transfer for the given document ### Provide information about the rejection of a document in the target system - [POST /documents/{id}/reject](https://hypatos.redocly.app/openapi/documents/documentsupdatereject.md): Update information about the rejection for the given document ### Provide external data for a document with given id - [POST /documents/{id}/external-data](https://hypatos.redocly.app/openapi/documents/documentupdateexternaldata.md): Update the external data for a document with given identifier. The external data are provided as a flat JSON object. The payload of this requests completley overrides the existing external data of a document. To remove the data, justsend empty JSON object {} in the payload. Please note that the maximum lenght of an key is 50 characters. Any value with a longer key will be omitted. The maximum amount of key-value pairs is limited to 20. ### Provide an external identifier for a document with given id - [POST /documents/{id}/external-id](https://hypatos.redocly.app/openapi/documents/documentsupdateexternalid.md): Provide an external identifier for a document with given id ### Provide a title for a document with given id - [POST /documents/{id}/title](https://hypatos.redocly.app/openapi/documents/documentsupdatetitle.md): Provide a title for a document with given id. ### Retrieve Document States - [GET /documents/{id}/states](https://hypatos.redocly.app/openapi/documents/retrievedocumentstates.md): Provides a list of states that the specified document has passed through. If the document is still being processed, the number of returned states should not be considered final. Subsequent calls to this endpoint may return additional states as the document continues to progress through the processing pipeline. ## Enrichment Endpoints for data enrichment ### Insert invoice including invoice lines - [POST /enrichment/invoices](https://hypatos.redocly.app/openapi/enrichment/insertinvoice.md) ### Partially update invoice - [PATCH /enrichment/invoices/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchinvoice.md) ### Delete invoice - [DELETE /enrichment/invoices/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteinvoice.md) ### Insert company - [POST /enrichment/companies](https://hypatos.redocly.app/openapi/enrichment/insertcompany.md) ### Partially update company - [PATCH /enrichment/companies/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchcompany.md) ### Delete company - [DELETE /enrichment/companies/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletecompany.md) ### Insert supplier including related subsidiaries - [POST /enrichment/suppliers](https://hypatos.redocly.app/openapi/enrichment/insertsupplier.md) ### Partially update supplier - [PATCH /enrichment/suppliers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchsupplier.md) ### Delete supplier - [DELETE /enrichment/suppliers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletesupplier.md) ### Insert purchase order including purchase order lines - [POST /enrichment/purchase-orders](https://hypatos.redocly.app/openapi/enrichment/insertpurchaseorder.md) ### Partially update purchase order - [PATCH /enrichment/purchase-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchpurchaseorder.md) ### Delete purchase Order - [DELETE /enrichment/purchase-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletepurchaseorder.md) ### Insert general ledger account - [POST /enrichment/gl-accounts](https://hypatos.redocly.app/openapi/enrichment/insertglaccount.md) ### Partially update general ledger account - [PATCH /enrichment/gl-accounts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchglaccount.md) ### Delete general ledger account - [DELETE /enrichment/gl-accounts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteglaccount.md) ### Insert cost center - [POST /enrichment/cost-centers](https://hypatos.redocly.app/openapi/enrichment/insertcostcenter.md) ### Partially update cost center - [PATCH /enrichment/cost-centers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchcostcenter.md) ### Delete cost Center - [DELETE /enrichment/cost-centers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletecostcenter.md) ### Insert approver - [POST /enrichment/approvers](https://hypatos.redocly.app/openapi/enrichment/insertapprover.md) ### Partially update approver - [PATCH /enrichment/approvers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchapprover.md) ### Delete approver - [DELETE /enrichment/approvers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteapprover.md) ### Insert customer - [POST /enrichment/customers](https://hypatos.redocly.app/openapi/enrichment/insertcustomer.md) ### Partially update customer - [PATCH /enrichment/customers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchcustomer.md) ### Delete customer - [DELETE /enrichment/customers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletecustomer.md) ### Insert data row to lookup table - [POST /enrichment/lookup-tables/{type}](https://hypatos.redocly.app/openapi/enrichment/insertlookuptablerow.md) ### Partially update data row in lookup table - [PATCH /enrichment/lookup-tables/{type}/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchlookuptablerow.md) ### Delete data row in lookup table - [DELETE /enrichment/lookup-tables/{type}/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletelookuptablerow.md) ### Insert contract - [POST /enrichment/contracts](https://hypatos.redocly.app/openapi/enrichment/insertcontract.md) ### Partially update contract - [PATCH /enrichment/contracts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchcontract.md) ### Delete contract - [DELETE /enrichment/contracts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletecontract.md) ### Insert sales order - [POST /enrichment/sales-orders](https://hypatos.redocly.app/openapi/enrichment/insertsalesorder.md) ### Partially update sales order - [PATCH /enrichment/sales-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchsalesorder.md) ### Delete sales order - [DELETE /enrichment/sales-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletesalesorder.md) ### Insert product - [POST /enrichment/products](https://hypatos.redocly.app/openapi/enrichment/insertproduct.md) ### Partially update product - [PATCH /enrichment/products/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchproduct.md) ### Delete product - [DELETE /enrichment/products/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteproduct.md) ### Insert address - [POST /enrichment/addresses](https://hypatos.redocly.app/openapi/enrichment/insertaddress.md) ### Partially update address - [PATCH /enrichment/addresses/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchaddress.md) ### Delete address - [DELETE /enrichment/addresses/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteaddress.md) ### Insert quotes - [POST /enrichment/quotes](https://hypatos.redocly.app/openapi/enrichment/insertquotes.md) ### Partially update quote - [PATCH /enrichment/quotes/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchquotes.md) ### Delete quote - [DELETE /enrichment/quotes/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletequotes.md) ### Insert Goods Receipt - [POST /enrichment/goods-receipts](https://hypatos.redocly.app/openapi/enrichment/insertgoodsreceipts.md) ### Partially update Goods Receipt - [PATCH /enrichment/goods-receipts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchgoodsreceipt.md) ### Delete Goods Receipt - [DELETE /enrichment/goods-receipts/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deletegoodsreceipt.md) ### Insert Profit Center - [POST /enrichment/profit-centers](https://hypatos.redocly.app/openapi/enrichment/insertprofitcenter.md) ### Partially update Profit Center - [PATCH /enrichment/profit-centers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchprofitcenter.md) ### Delete Profit Center - [DELETE /enrichment/profit-centers/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteprofitcenter.md) ### Insert Internal Order - [POST /enrichment/internal-orders](https://hypatos.redocly.app/openapi/enrichment/insertinternalorder.md) ### Partially update Internal Order - [PATCH /enrichment/internal-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchinternalorder.md) ### Delete Internal Order - [DELETE /enrichment/internal-orders/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteinternalorder.md) ### Insert Project - [POST /enrichment/projects](https://hypatos.redocly.app/openapi/enrichment/insertproject.md) ### Partially update Project - [PATCH /enrichment/projects/{externalId}](https://hypatos.redocly.app/openapi/enrichment/patchproject.md) ### Delete Project - [DELETE /enrichment/projects/{externalId}](https://hypatos.redocly.app/openapi/enrichment/deleteproject.md) ## Companies Endpoints for company management ### Retrieve a company by id - [GET /companies/{id}](https://hypatos.redocly.app/openapi/companies/companiesgetbyid.md) ### Retrieve a list of companies - [GET /companies](https://hypatos.redocly.app/openapi/companies/companieslist.md): Note: For now pagination is not implemented ## Projects Endpoints for project management ### Create a project - [POST /projects](https://hypatos.redocly.app/openapi/projects/projectscreate.md): Creates a project based on the request ### Retrieve a projects list for given search criteria - [GET /projects](https://hypatos.redocly.app/openapi/projects/projectslist.md) ### Retrieve a project by id - [GET /projects/{id}](https://hypatos.redocly.app/openapi/projects/projectsgetbyid.md): Retrieve a project by id ### Update a project - [PATCH /projects/{id}](https://hypatos.redocly.app/openapi/projects/projectsupdate.md): Update a project by id. This endpoint supports partial updates using PATCH semantics: - Only fields present in the request will be updated - Null values will clear optional fields (note, retentionDays) - Absent fields will remain unchanged - Required fields (name, extractionModelId, ocr, completion, duplicates, isLive, members, schema) cannot be set to null - At least one field must be provided in the request ### Retrieve a schema by project id - [GET /projects/{id}/schema](https://hypatos.redocly.app/openapi/projects/schemasgetbyprojectid.md): Retrieve a schema by project id ## E-Invoices Endpoints for e-invoices ### Retrieve a document PDF preview for e-invoices - [GET /e-invoices/{id}/preview](https://hypatos.redocly.app/openapi/e-invoices/retrieveeinvoicespreview.md): Provides a binary file of a document PDF preview for e-invoices ## Documents XML Endpoints serving project-scoped documents as XML ### List documents for a project as XML - [GET /document-xml/documents](https://hypatos.redocly.app/openapi/documents-xml/listdocumentsxml.md): Fetches the list of documents from Studio scoped to projectId, then applies the transformation rule tagged {projectId}-list to produce XML. If the rule has addBinaryFile enabled, binary attachments are inlined as base64. ### Get a single document as XML - [GET /document-xml/documents/{id}](https://hypatos.redocly.app/openapi/documents-xml/getdocumentxml.md): Fetches a document by id from Studio and applies the transformation rule tagged {projectId} to produce XML. If the rule has addBinaryFile enabled, the binary attachment is inlined as base64. ## Emails ### Retrieve an email merged content for given document ID - [GET /emails/{id}/content](https://hypatos.redocly.app/openapi/emails/emailscontentgetbydocumentid.md) ### Retrieve an email metadata for given document ID - [GET /emails/{id}](https://hypatos.redocly.app/openapi/emails/emailsmetadatagetbydocumentid.md) ### Retrieve an email eml content for given document ID - [GET /emails/{id}/eml](https://hypatos.redocly.app/openapi/emails/emailsemlgetbydocumentid.md) ## Document Routing ### Retrieve document routing with given id - [GET /routings/{id}](https://hypatos.redocly.app/openapi/document-routing/routingsgetbyid.md) ### Update document routing - [PUT /routings/{id}](https://hypatos.redocly.app/openapi/document-routing/routingsupdate.md) ### Delete document routing - [DELETE /routings/{id}](https://hypatos.redocly.app/openapi/document-routing/routingsdelete.md) ### Retrieve document routings list - [GET /routings](https://hypatos.redocly.app/openapi/document-routing/routingslist.md) ### Create document routing - [POST /routings](https://hypatos.redocly.app/openapi/document-routing/routingscreate.md) ### Change document routing order - [POST /routings/{id}/order](https://hypatos.redocly.app/openapi/document-routing/routingsorder.md) ## Users ### Retrieve user information by id - [GET /users/{id}](https://hypatos.redocly.app/openapi/users/usersgetbyid.md) ### Retrieve a users list for given search criteria - [GET /users](https://hypatos.redocly.app/openapi/users/userslist.md)