POST /v1/documents

Main method of flow ① — sends a tax PDF to the Docupath processing pipeline along with its metadata. The Finn vertical AI extracts the data, validates it and exports the result in Docupath AI Format (DIF), which is then mapped to Gosocket's native XML.

Endpoint

DEVhttps://api.docupathdev.app/v1/documents

PRDhttps://api.docupath.app/v1/documents

Method: POST · Authentication: Authorization: Bearer {access_token} → see POST /v1/oauth/token

Body parameters (multipart/form-data)

Field	Type	Req.	Description
file	File	Required	The document file. Types: pdf, txt, doc, docx, png, jpg, jpeg. Max: 50 MB / 150 pages / 500 lines.
metadata	JSON (text)	Required	JSON object with external_id and additional metadata (see structure below)
batch_id	String	Optional	Batch ID generated by Gosocket to group related documents. Docupath returns it unchanged as batchId in Flow ②

warning

The metadata field must be sent as type text in the multipart/form-data, not as a file. The JSON must be valid: lowercase true/false, no trailing commas.

metadata field structure

{
  "external_id": "0012-00003835",
  "additional_metadata": {
    "client_id": "ORGANIZATION_ID_IN_DOCUPATH",
    "enrich_from_org": false
  }
}

Field	Type	Description
external_id	String (required)	Unique ID generated by Gosocket. Gosocket sends it in Flow ① and Docupath returns it unchanged as externalId in Flow ② (UploadZipDocument). End-to-end traceability key.
additional_metadata.client_id	String (required)	ID of the organization under Settings → Organizations in Docupath. ≠ the client_id of the OAuth credentials.
additional_metadata.enrich_from_org	Boolean (optional)	If true, Docupath enriches the document with data from the configured organization.

Request / Response

POST /v1/documents

POST {base_url}/v1/documents
Authorization: Bearer {access_token}
Content-Type: multipart/form-data

-- file: invoice.pdf (file-type field)
-- metadata: (text-type field)
{
"external_id": "0012-00003835",
"additional_metadata": {
  "client_id": "ORGANIZATION_ID_IN_DOCUPATH",
  "enrich_from_org": false
}
}

---

Available query APIs

Docupath exposes two additional endpoints to query the status and history of documents.

• GET /v1/documents/search?external_id={id} — Gosocket does integrate it: it's the endpoint for Flow ③ (periodic polling), used to obtain the processed XML (processed_info) and the original PDF (file_url) without depending on Docupath pushing the result via Flow ②. See the full reference.
• GET /v1/documents — lists documents processed within a date range (?start_timestamp=...&end_timestamp=... · ?batch_id=... optional). Gosocket doesn't currently integrate it; it's kept on record as a reference for batch monitoring.

Authentication for both: Authorization: Bearer {access_token} (same token as the POST).

Possible values of the current_status field:

Status	Description
uploaded	Document received, pending processing
processing	The AI is extracting and validating the data
pending_review	Processed — pending manual review in the Docupath portal. The XML and PDF are already available at this status, per tests against DEV — see Flow ③
approved	Manual review completed
rejected	Rejected — doesn't meet the configured validation rules
expired	The document expired without being processed

---

Output format — Docupath AI Format (DIF)

Once a document is approved, Docupath exports it in Docupath AI Format (DIF), its unified internal format. From the DIF it applies the mapping to Gosocket's native XML (structure <DTE><Documento><Encabezado>...), configured under Settings → Destination Format & APIs in the Docupath portal.

note

The DIF is Docupath's internal format, not the XML that Gosocket receives. If field inconsistencies appear across countries or document types, contact the Docupath team with the affected document's external_id.