Docupath's REST API allows external systems to programmatically submit and retrieve business documents. API ingestion is the primary method for automating document submission from ERP, EDI, RPA, and other enterprise systems. All endpoints are versioned (the current version is v1) and all paths include the version number (e.g., /v1/documents).

Prerequisites

Admin role in Docupath
Organization (and any client organizations) already configured through organization settings
API credentials generated (see steps below)

Step-by-Step: Generating API Credentials and Submitting Documents

Step 1: Navigate to API Settings

Go to Settings > Destination Format & APIs in your Docupath tenant.

Step 2: Generate API Credentials

Click Generate API Credentials.

Step 3: Enter a Key Name

Provide a descriptive Key Name that identifies the integration (e.g., "ERP Production Integration" or "RPA Invoice Submission").

Step 4: Copy Client ID and Secret

Copy the Client ID and Client Secret immediately. The Client Secret is displayed only once and cannot be retrieved after this step.

Step 5: Store Credentials Securely

Store the Client ID and Client Secret in a secure credential vault or secrets manager. Do not store them in plain text or share them via email.

Step 6: Configure the External System to Authenticate

Docupath uses OAuth 2.0 for authentication. The Client ID and Client Secret are not sent on every request; instead, your external system exchanges them for a short-lived OAuth 2.0 access token, and that token is sent with each API request.

To obtain an access token, make a POST request to the token endpoint:

Endpoint: /v1/oauth/token
Headers:
- Content-Type: application/x-www-form-urlencoded
- Authorization: Basic {base64(client_id:client_secret)}
Body: grant_type=client_credentials

A successful response (200 OK) returns an access_token, a token_type of Bearer, an expires_in value (the token lifespan in seconds, e.g., 3600), and a refresh_token. Include the access token in every subsequent request:

Authorization: Bearer {access_token}

All interactions must occur over HTTPS using the base URL https://api.docupath.app. Requests made over non-secure HTTP are rejected.

Step 7: Include Document Metadata

Each document submission to /v1/documents includes the file plus a metadata JSON object. The metadata contains:

external_id (string): a unique identifier for the document.
additional_metadata (object): optional additional metadata. Example fields include client_id (the ID of the client organization configured in organization settings) and enrich_from_org (a boolean indicating whether to enrich details from the matching client organization).

You can also include an optional batch_id to group documents that were uploaded together. The batch_id can later be used to filter documents during retrieval.

Step 8: Send a Test Document

Submit a test document via the API to verify the integration is working correctly.

Endpoint: /v1/documents
Method: POST
Headers:
- Content-Type: multipart/form-data
- Authorization: Bearer {access_token}
Body (multipart/form-data): file, metadata, and optional batch_id.

Supported file types are: txt, doc, docx, pdf, png, jpg, jpeg. Documents must be within the platform file limits: 50 MB maximum file size, 150 pages maximum, and 500 line items maximum. A successful submission returns 201 Created with the document's external_id.

Step 9: Verify in Review Screen

Confirm the test document appears in the Review Screen within your Docupath tenant and has been processed as expected. You can also verify programmatically using the search endpoint GET /v1/documents/search?external_id={external_id}, which returns the document's current_status (one of: uploaded, processing, pending_review, approved, rejected, expired).

Expected Outcome

Documents submitted via the API are ingested into the Docupath processing pipeline and appear in the Review Screen for review and validation, just as if they had been uploaded through the UI. Once processed, documents can also be retrieved through the API by external ID or by timeframe.

Common Issues

Issue	HTTP Status	Cause	Resolution
Authentication failure	401	Missing, invalid, or expired access token; or invalid Client ID / Secret	Obtain a new access token via `/v1/oauth/token`; verify credentials are correct; regenerate if compromised
Bad request	400	Malformed request body or a required field missing (e.g., `file` or `metadata`)	Verify the request includes the file and a valid `metadata` object
File rejected	400	Unsupported file type or file exceeds size/page/line limits	Ensure the file is a supported type (txt, doc, docx, pdf, png, jpg, jpeg) and within 50 MB / 150 pages / 500 line items
Document not found	404	The `external_id` does not match any document	Verify the `external_id` and confirm the document was submitted successfully
Lost Client Secret	N/A	Secret was not saved after generation	Regenerate API credentials from Settings > Destination Format & APIs

Notes

All requests must use HTTPS over the base URL https://api.docupath.app, and all endpoint paths must include the v1 version number.
Access tokens are short-lived (see expires_in in the token response). Implement the OAuth 2.0 refresh token flow, or re-authenticate using the Client Credentials Grant, to obtain a new access token before the current one expires.
Docupath does not provide automatic retry for failed API submissions; implement retry logic in your external system.
Use descriptive key names to distinguish between multiple integrations.
Implement a key rotation policy to periodically regenerate API credentials.
The Client Secret is shown only once at generation time, and there is no way to retrieve it later.

Configuring Document Ingestion via API