# Enrichment API

Operations related to Qvalia Enrichments

## Upload an Invoice PDF

> API accepts a single invoice file (PDF or XML) and processes it\
> asynchronously. Returns a polling ID to check the status of enrichment.\
> Send the pollingId to the enrchment GET endpoint to get the status or\
> completed result.\
> \
> The Enrichment API is billed separately hence require additional permissions to be enabled. Please contact Qvalia support if you require access.

```json
{"openapi":"3.0.2","info":{"title":"Qvalia Enrichment API","version":"1.1.0"},"tags":[{"name":"Enrichment API","description":"Operations related to Qvalia Enrichments"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"}}},"paths":{"/enrichment/{accountRegNo}/invoice":{"post":{"tags":["Enrichment API"],"summary":"Upload an Invoice PDF","description":"API accepts a single invoice file (PDF or XML) and processes it\nasynchronously. Returns a polling ID to check the status of enrichment.\nSend the pollingId to the enrchment GET endpoint to get the status or\ncompleted result.\n\nThe Enrichment API is billed separately hence require additional permissions to be enabled. Please contact Qvalia support if you require access.","operationId":"enrichment-api/post-invoice","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"responses":{"202":{"description":"File accepted for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status of the request (e.g., success)."},"data":{"type":"object","description":"Confirmation message.","properties":{"pollingId":{"type":"string","description":"Polling ID for polling."}},"required":[""]}}}}},"headers":{"Location":{"schema":{"type":"string","description":"Resource URL to poll the status.","default":""},"description":"URL to poll the status."}}},"400":{"description":"Invalid file or request.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","description":"Optional name of the file being uploaded, including\nextension (e.g., invoice.pdf)."},"fileContent":{"type":"string","description":"The Base64 encoded content of the file.","format":"byte"},"enrichmentTypes":{"type":"string","description":"types of enrichment tasks to perform. Ex; \"capture\""},"parameters":{"type":"object","description":"Optional parameters for enrichment processing","properties":{}}},"required":["fileContent","enrichmentTypes"]}}}}}}}}
```

## Send a products list to categorise

> API accepts a list of products and processes it\
> asynchronously. Returns a polling ID to check the status of enrichment.\
> Send the pollingId to the enrchment GET endpoint to get the status or\
> completed result.\
> \
> The Enrichment API is billed separately hence require additional permissions to be enabled. Please contact Qvalia support if you require access.

```json
{"openapi":"3.0.2","info":{"title":"Qvalia Enrichment API","version":"1.1.0"},"tags":[{"name":"Enrichment API","description":"Operations related to Qvalia Enrichments"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"}}},"paths":{"/enrichment/{accountRegNo}/categorisation":{"post":{"tags":["Enrichment API"],"summary":"Send a products list to categorise","description":"API accepts a list of products and processes it\nasynchronously. Returns a polling ID to check the status of enrichment.\nSend the pollingId to the enrchment GET endpoint to get the status or\ncompleted result.\n\nThe Enrichment API is billed separately hence require additional permissions to be enabled. Please contact Qvalia support if you require access.","operationId":"enrichment-api/post-products","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"responses":{"202":{"description":"File accepted for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status of the request (e.g., success)."},"data":{"type":"object","description":"Confirmation message.","properties":{"pollingId":{"type":"string","description":"Polling ID for polling."}},"required":[""]}}}}},"headers":{"Location":{"schema":{"type":"string","description":"Resource URL to poll the status.","default":""},"description":"URL to poll the status."}}},"400":{"description":"Invalid file or request.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"object","description":"Products list that needs to be categorised. id and product_name are required fields.","format":"byte"},"enrichmentTypes":{"type":"string","description":"types of enrichment tasks to perform. Ex; \"unspsc\""}},"required":["products","enrichmentTypes"]}}}}}}}}
```

## Poll for and get enrichment

> This endpoint allows clients to check the status of an\
> enrichment process using a polling ID. Since enrichment is an\
> asynchronous operation, this endpoint should be used to monitor progress\
> and retrieve results once processing is complete.\
> \
> \*\*Response Content\*\*: The response data will contain results for the specific \
> enrichment types that were requested in the original POST request. For example:\
> \- If "capture" was requested, the response will include a \`capture\` object\
> \- If "categorisation" was requested, the response will include a \`categorisation\` object  \
> \- If both were requested, both objects will be present in the response\
> \
> \*\*Polling Behavior\*\*\
> \
> \*   If the enrichment process is still ongoing, the API will return HTTP\
> 202 (Accepted), indicating that the request was received and is still\
> being processed.\
> \
> \*   Once the enrichment is complete, the API will return HTTP 200 (OK)\
> along with the final result.\
> \
> \*   Clients must limit polling requests to once every 30 seconds.\
> Requests made at a higher frequency may be rate-limited or rejected

```json
{"openapi":"3.0.2","info":{"title":"Qvalia Enrichment API","version":"1.1.0"},"tags":[{"name":"Enrichment API","description":"Operations related to Qvalia Enrichments"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"},"pollingId":{"name":"pollingId","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"The unique polling ID for the file"}}},"paths":{"/enrichment/{accountRegNo}/{pollingId}":{"get":{"tags":["Enrichment API"],"summary":"Poll for and get enrichment","description":"This endpoint allows clients to check the status of an\nenrichment process using a polling ID. Since enrichment is an\nasynchronous operation, this endpoint should be used to monitor progress\nand retrieve results once processing is complete.\n\n**Response Content**: The response data will contain results for the specific \nenrichment types that were requested in the original POST request. For example:\n- If \"capture\" was requested, the response will include a `capture` object\n- If \"categorisation\" was requested, the response will include a `categorisation` object  \n- If both were requested, both objects will be present in the response\n\n**Polling Behavior**\n\n*   If the enrichment process is still ongoing, the API will return HTTP\n202 (Accepted), indicating that the request was received and is still\nbeing processed.\n\n*   Once the enrichment is complete, the API will return HTTP 200 (OK)\nalong with the final result.\n\n*   Clients must limit polling requests to once every 30 seconds.\nRequests made at a higher frequency may be rate-limited or rejected","operationId":"enrichment-api/get-enrichment-pollingid","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/pollingId"}],"responses":{"200":{"description":"Enrichment complete, result available.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status of the request (e.g., success)."},"data":{"type":"object","description":"Contains enrichment results based on the requested enrichmentTypes. May include one or more of: capture, categorisation.","properties":{"capture":{"type":"object","description":"Result of PDF capture (present when \"capture\" is requested in enrichmentTypes)","properties":{"result":{"type":"object","description":"Captured invoice data","properties":{"Invoice":{"type":"object","description":"Extracted invoice information","properties":{}}},"required":["Invoice"]},"errors":{"type":"array","description":"Errors will include extraction errors. If the\nprocess failed to correctly extract certain main\nattribute, an array of error messages indicating\nreason for the error is returned. Client is\nencouraged to look at error messages based on\ntheir usecases.","items":{"type":"string"}},"warnings":{"type":"array","description":"Warning will include non critical errors during\nthe extraction.","items":{"type":"string"}}},"required":["result"]},"categorisation":{"type":"object","description":"Result of product categorisation (present when \"categorisation\" is requested in enrichmentTypes)","properties":{"result":{"type":"object","description":"Categorised products data","properties":{},"required":[""]},"errors":{"type":"array","description":"Errors if available that occured during enrichment\nprocess.","items":{"type":"string"}}},"required":["result"]}}}}}}}},"202":{"description":"The enrichment process is still in progress. The client should retry after 30 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status of the processing (e.g., processing, error)."}}}}}},"400":{"description":"Invalid or expired polling ID.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","default":"error","description":"Status of the processing (e.g., processing, error)."}}}}}},"404":{"description":"Invalid or expired polling ID.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","default":"error","description":"Status of the processing (e.g., processing, error)."}}}}}},"429":{"description":"The client has exceeded the polling frequency limit. The request is\nrejected, and the client should wait before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":""},"message":{"type":"string","description":""}}}}}}}}}}}
```

## Get individual enrichment result

> Get the enrichment result using the polling ID. Returns the result in\
> the format requested.

```json
{"openapi":"3.0.2","info":{"title":"Qvalia Enrichment API","version":"1.1.0"},"tags":[{"name":"Enrichment API","description":"Operations related to Qvalia Enrichments"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"},"pollingId":{"name":"pollingId","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"The unique polling ID for the file"}}},"paths":{"/enrichment/{accountRegNo}/{pollingId}/{enrichmentType}":{"get":{"tags":["Enrichment API"],"summary":"Get individual enrichment result","description":"Get the enrichment result using the polling ID. Returns the result in\nthe format requested.","operationId":"enrichment-api/get-enrichment-type-pollingid","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/pollingId"},{"name":"enrichmentType","in":"path","required":true,"schema":{"type":"string","description":"The enrichment type sent on posting of the document","default":"capture","enum":["capture","posting","classification","co2"]},"description":"The enrichment type sent on posting of the document"}],"responses":{"200":{"description":"Enrichment complete, result available.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status of the request (e.g., success)."},"data":{"type":"object","description":"","properties":{"result":{"type":"object","description":"Container for the enrichment result","properties":{},"required":[""]},"errors":{"type":"array","description":"Errors if available that occured during enrichment\nprocess.","items":{}},"warnings":{"type":"array","description":"Warnings if available that occured during enrichment\nprocess.","items":{}}},"required":[""]}}}}}},"202":{"description":"The enrichment process is still in progress. The client should retry after 30 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":""}}}}}},"400":{"description":"Invalid or expired polling ID.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","default":"error","description":"Status of the processing (e.g., processing, error)."}}}}}},"404":{"description":"Invalid or expired polling ID.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","default":"error","description":"Status of the processing (e.g., processing, error)."}}}}}},"429":{"description":"The client has exceeded the polling frequency limit. The request is\nrejected, and the client should wait before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":""},"message":{"type":"string","description":""}}}}}}}}}}}
```