How Extractions Work
- Create or retrieve the entity you want to extract data for.
- Start the extraction with the selected datasource and options.
- Store the returned extraction ID.
- Retrieve the extraction until its
statusisfinishedorfailed. - Read the extracted data from the related resource endpoints, such as invoices or tax returns.
Scheduled Extractions
Use schedulers when the same extraction should run repeatedly, such as a daily invoice extraction or a monthly tax return extraction. A scheduler controls whether the automation is enabled, and scheduler rules define the extractor, options, and cron expression. Extractor names and options are specific to the data you are extracting. For extraction-backed resources, use the resource page to understand what data is collected and the developer examples for request bodies.Extraction Status
| Status | Description |
|---|---|
| pending | The initial extraction status. The extraction is enqueued and waiting to be processed. |
| waiting | The extraction does not meet the requirements to begin. |
| running | The extraction process started and is currently running. The running time varies depending on the extractor type and the entity’s transactional volume. Partial data may be available from related resource endpoints during this time. |
| finished | The extraction finished successfully. The extracted data is available from the related resource endpoints. |
| failed | The extraction couldn’t start or failed during the process. Our internal retry policies weren’t able to finish the extraction successfully. We may have partial data available, but new extractions should be created to ensure all the entity’s data is available. You can check the extraction error code to understand why it failed and determine whether it can be retried or not. |
| stopping | The extraction was requested to be stopped by the user. It is in the process of being stopped. |
| stopped | The extraction was stopped by the user after it started running. This extraction is included in billing. |
| cancelled | The extraction was stopped by the user before it started running. This extraction is not included in billing. |
Extraction Error Codes
| Code | Description | Retryable |
|---|---|---|
| invalid_credentials | The taxpayer Credential is no longer valid. | No |
| login_failed | We couldn’t authenticate the taxpayer with the datasource. | Yes |
| unrecoverable | The extraction process failed many times, and we reached a maximum number of retries. | Yes |
| sat_unavailable | We detected that SAT itself is down or unresponsive. | Yes |
| internal_error | We detected an internal error in our own infrastructure. | Yes |
| undefined | We couldn’t determine the error cause and our internal team will investigate it. | Yes |