Available

Quickstart

Submit an invoice, receive its structured webhook, and retrieve the persisted job.

Updated 2026-07-28

The API accepts a public document URL and processes it asynchronously. This guide uses invoice type 0 with line items and covers both delivery choices: webhook push and job retrieval.

1. Get credentials

   Create an API key in the Docparser portal’s Developer area. Copy its client ID and secret when the secret is shown, then keep both values outside your source code.

   Local environment shell Copy

   export DOCPARSER_CLIENT_ID='org_replace_me'
   export DOCPARSER_CLIENT_SECRET='secret_replace_me'

   Every request in this guide uses x-client-id and x-client-secret. The API base URL is https://app.docparser.dev/api/v1.

2. Create a webhook receiver

   Set the API key’s registered webhook base URL to a public HTTPS origin you control, such as https://api.example.com. The request supplies only the relative path /hooks/docparser; Docparser joins that path to the registered base URL.

   Minimal Node.js webhook receiver javascript Copy

   import { createServer } from 'node:http';
   
   createServer((request, response) => {
   if (request.method !== 'POST' || request.url !== '/hooks/docparser') {
   response.writeHead(404).end();
   return;
   }
   
     const chunks = [];
     request.on('data', (chunk) => chunks.push(chunk));
     request.on('end', () => {
         const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
         console.log(result);
         response.writeHead(204).end();
     });
   
   }).listen(3000, () => console.log('Webhook receiver listening on :3000'));

   Deploy that receiver behind the registered HTTPS origin before submitting. Return a successful 2xx response promptly.

3. Submit an invoice

   Use a URL Docparser can fetch without your browser session. consumerRefId is your correlation value; it does not become a globally unique database key.

   cURL JavaScript Python

   cURL request shell Copy

   curl --request POST 'https://app.docparser.dev/api/v1/documents' \
   --header "content-type: application/json" \
   --header "x-client-id: $DOCPARSER_CLIENT_ID" \
   --header "x-client-secret: $DOCPARSER_CLIENT_SECRET" \
   --data '{
     "documentUrl": "https://files.example.com/invoices/inv-4471.pdf",
     "webhookUrl": "/hooks/docparser",
     "requireLineItems": true,
     "documentId": 4471,
     "consumerRefId": "inv-4471",
     "typeId": 0
   }'

   A valid request returns 202 Accepted immediately. Extraction continues asynchronously.

   202 Accepted json Copy

   {
   "jobId": "5ca1ab1e-314d-4b2d-b9d6-8e68870b840f",
   "consumerRefId": "inv-4471"
   }

4. Receive the result

   When processing finishes, Docparser posts the extraction result to the resolved webhook URL. A processed single-invoice webhook looks like the canonical response below.

   Processed webhook payload json Copy

   {
     "status": "processed",
     "processed_data": {
       "summary_data": {
         "invoice_number": "INV-4471",
         "expense_date": "2026-07-25",
         "currency": "INR",
         "amount": 58410,
         "taxable_amount": 49500,
         "from_gstin": "27AAECS1234F1Z5",
         "to_gstin": "27AABCF9876D1Z2",
         "irn": "a48f3e9b7c2d",
         "bank_name": "Horizon Bank",
         "ifsc": "HRZN0000142"
       },
       "lineItems": [
         {
           "description": "Warehouse handling service",
           "hsn_sac": "996729",
           "quantity": 30,
           "rate": 1650,
           "amount": 49500,
           "cgst_rate": 9,
           "cgst_amount": 4455,
           "sgst_rate": 9,
           "sgst_amount": 4455
         }
       ]
     },
     "consumer_ref_id": "inv-4471",
     "document_id": 4471
   }

   The request field is camelCase consumerRefId; the webhook identifier is snake_case consumer_ref_id.

5. Retrieve the job

   Poll with the same credentials and URL-encode the reference when you build the path. Retrieval returns the persisted job row, not only the webhook payload.

   Retrieve by consumer reference shell Copy

   curl --request GET 'https://app.docparser.dev/api/v1/documents/inv-4471' \
   --header "x-client-id: $DOCPARSER_CLIENT_ID" \
   --header "x-client-secret: $DOCPARSER_CLIENT_SECRET"

   The lookup is scoped to your organization and returns the first matching row. consumerRefId is not a globally unique key, so use a distinct value per submission in your own integration.

   Continue with the submit reference or inspect every retrieval field.