You can choose out of multiple provisioning strategies to get documents provisioned to your application. The current options are:

• Push [Recommended]: fetchdocs pushes documents to your application via webhooks. This is the most common and recommended way to get documents provisioned.
• Webhook based pull: fetchdocs notifies your application via webhooks when a document is available. You can then pull the document from fetchdocs via the API.
• Polling: You have to poll the fetchdocs API for new documents. This is the least recommended way to get documents provisioned, as it can lead to a lot of unnecessary requests and load on both sides.

🏃🏽‍♂️ Push#

This is the recommended provisioning strategy.

fetchdocs pushes documents to your application via webhooks. This is the most common and recommended way to get documents provisioned because it reduces the load on your application and fetchdocs. You don't need to poll the API for new documents, which can lead to a lot of unnecessary requests and load on both sides. In addition, fetchdocs pushes documents to your application as soon as they're available, so you don't need to wait for the next poll cycle.

How to set up push?#

To set up push, you need to provide a provisioning URL to the fetchdocs support team. fetchdocs is calling this URL whenever a document is available. The provisioning URL should be able to handle POST requests and respond with a 200 OK status code to acknowledge that it received the document successfully. If fetchdocs doesn't receive a 200 OK status code, it logs that request as failed. In contrast to webhooks, where fetchdocs doesn't retry failed webhooks, fetchdocs is retrying failed provisioning requests. The retry interval uses an "exponential backoff" strategy, which means that the retry interval increases with each failed attempt. If the provisioning request fails finally, fetchdocs logs that request as failed and stops retrying.

Payload#

The payload for the provisioning request is a JSON object in the body of the POST request and includes the following elements:

• client_identifier: The identifier of the client. This is the identifier of the representing entity in your app. This can be the user ID, the company ID, or the account ID. You defined this identifier when you created the identity. Some systems use this for example to identify the database or instance of the user.
• identity_uuid: The UUID of the identity. This is the UUID of the representing entity in your app. You received this identifier when you created the identity.
• connection_uuid: The UUID of the connection. This is the UUID of the connection that relates to the document. You can use this identifier to link the document to the connection in your app.
• transaction_uuid: The UUID of the transaction. This is the UUID of the transaction that relates to the document. You can use this identifier to link the document to the document in your app.
• document_type: The type of the document. This is the type of the document that fetchdocs pushes to your application. This can be f.e. invoice or credit_note. The data structure of the metadata depends on the document type.
• external_id: The id of the document in the source system, f.e. the document id of the accounting tool the document was fetched from. You can use this identifier for duplicate detection, because it stays stable even if the source system re-renders the document and the file content changes. This element is always present, but it's null if the source system doesn't provide an id, f.e. for documents fetched from a mailbox or downloaded from a portal.
• document: The document data.
  • base64: The base64 encoded document. This is the document that fetchdocs pushes to your application. You need to decode this document and store it in your app.
  • filename: The filename of the document. This is the filename of the document that fetchdocs pushes to your application. If fetchdocs fetched the document from a storage provider, this is the filename of the document in the storage provider.
  • mime_type: The mime type of the document. This is the mime type of the document that fetchdocs pushes to your application.
• metadata: The metadata of the document. This is the metadata of the document that fetchdocs pushes to your application. The data structure of the metadata depends on the document type. The metadata includes information about the document, like the date, amount, and currency. See the Data Models section of the documentation for a detailed list of available attributes.

⚠️ All metadata is optional!

Pay attention: The metadata isn't always available. It depends on the integration and if the metadata is available in the source system. So make sure to handle all metadata as optional. fetchdocs always provides as much metadata as possible, but it's not guaranteed that all metadata is available. You also don't have to import all data from the metadata. You can choose which data you want to import and which data you want to ignore.

Authentication#

If your provisioning endpoint requires authentication, you need to provide the authentication information to the fetchdocs support team. fetchdocs supports token based authentication through bearer token, query parameter token and authorization header.

📦 Webhook based pull#

fetchdocs notifies your application via webhooks when a document is available. You can then pull the document from fetchdocs via the API. This is a good option if you want to have more control over when to pull documents from fetchdocs. However, it can lead to a lot of unnecessary requests and load on both sides, as you need to poll the API for new documents.

🕵️‍♂️ Polling#

You have to poll the fetchdocs API for new documents. This is the least recommended way to get documents provisioned, as it can lead to a lot of unnecessary requests and load on both sides. In addition, documents aren't available immediately, so you need to wait for the next poll cycle. This can lead to delays in getting documents provisioned to your application.

⚡ Triggering an on-demand fetch#

Independent of which provisioning strategy you use, you can ask fetchdocs to run a fetch immediately by calling POST /connections/{uuid}/fetch-now. This is what powers "Sync now" buttons in client UIs. To avoid abuse, manual fetches are limited to 5 per hour per connection and are skipped when a scheduled fetch is already due within the next minute. See Trigger a manual fetch for details.