Getting Started

This guide walks you through setting up your environment and making your first extraction request with the DocMap API.

Prerequisites

Before you begin, make sure you have:

1. A DocMap account -- Sign up at docmap.io if you haven't already.
2. At least one extraction template -- Create a template in the Dashboard that defines the fields you want to extract from your documents.

TIP

Templates define the structure of the data you want to extract. For example, an invoice template might include fields like vendor_name, invoice_number, total_amount, and a line_items array. You can create and manage templates from the dashboard before making any API calls.

Base URL

All API requests are made to:

https://api.docmap.io

All endpoints are prefixed with /v1/. For example, the extractions endpoint is:

https://api.docmap.io/v1/extractions/run

Create an API Key

1. Go to Dashboard > Settings > API Keys.
2. Click Create API Key.
3. Give your key a descriptive name (e.g., "Production Server" or "Local Development").
4. Choose an expiration period.
5. Copy the key immediately -- it is shown only once and cannot be retrieved later.

WARNING

Store your API key securely. It will only be displayed once at creation time. If you lose it, you will need to create a new one.

Your API key will have the format dm_live_... and is used in the Authorization header of every request.

Your First Request

Verify your setup by checking the API health endpoint:

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

If everything is working, you will receive:

{ "status": "ok" }

Run Your First Extraction

With your API key and a template ready, you can extract structured data from a PDF. Encode your PDF file as a base64 string and send it to the /v1/extractions/run endpoint.

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

Example Response

A successful extraction returns the extracted data matching your template fields:

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-11-15",
    "total_amount": 1250.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": 125.00
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

Check Your Usage

Monitor your API usage to stay within your plan limits:

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(response.json())

Next Steps

Now that you have made your first extraction, explore the rest of the documentation:

• Authentication -- Learn about API keys and security best practices.
• API Reference -- Full reference for all available endpoints.