Schemas

This page documents the data models returned by the DocMap API. All responses use JSON.

ExtractionRecord

An extraction record represents a single document extraction -- the result of processing a PDF against a template.

interface ExtractionRecord {
  id: string              // Unique extraction ID
  userId: string          // Owner user ID
  templateId: string      // Template used for extraction
  templateName: string    // Human-readable template name
  fileName: string        // Original uploaded file name
  status: 'processing' | 'completed' | 'failed'
  extractedData: Record<string, unknown> | null  // Structured data or null if failed
  error: string | null    // Error message if failed, null if successful
  variables: Variable[]   // Template variable definitions used
  source: 'dashboard' | 'api'  // How the extraction was initiated
  runId: string | null    // Batch run ID, null if not part of a batch
  processingTimeMs: number | null  // Processing duration in milliseconds
  createdAt: string       // ISO 8601 timestamp
}

Field Descriptions

Field	Type	Description
id	string	Unique identifier for the extraction record.
userId	string	The ID of the user who owns this extraction.
templateId	string	The ID of the template that was used to define the extraction schema.
templateName	string	The display name of the template at the time of extraction.
fileName	string	The original name of the uploaded file (e.g., "invoice-march.pdf").
status	string	"processing" while the extraction is running (async mode), "completed" if extraction succeeded, or "failed" if it did not.
extractedData	object | null	The structured data extracted from the document, matching the template's variable definitions. null if the extraction failed.
error	string | null	A description of what went wrong. null if the extraction succeeded.
variables	Variable[]	The template variable definitions that were used for this extraction. See Variable.
source	string	"dashboard" if the extraction was run from the web UI, "api" if it was run via the API.
runId	string | null	If the extraction was part of a batch run, this is the shared run ID. null for individual extractions.
processingTimeMs	number | null	How long the extraction took in milliseconds. null if not recorded.
createdAt	string	ISO 8601 timestamp of when the extraction was created.

Example

{
  "id": "ext_kp92mf7x",
  "userId": "u_abc123",
  "templateId": "tpl_inv001",
  "templateName": "Standard Invoice",
  "fileName": "acme-invoice-2024-003.pdf",
  "status": "completed",
  "extractedData": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-003",
    "invoice_date": "2024-11-15",
    "due_date": "2024-12-15",
    "total_amount": 4750.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Cloud Hosting - Pro Plan",
        "quantity": 1,
        "unit_price": 2500.00
      },
      {
        "description": "SSL Certificate (Wildcard)",
        "quantity": 3,
        "unit_price": 750.00
      }
    ]
  },
  "error": null,
  "variables": [
    { "key": "vendor_name", "type": "string", "context": "Name of the vendor or supplier", "required": true },
    { "key": "invoice_number", "type": "string", "context": "Invoice or reference number" },
    { "key": "invoice_date", "type": "date", "context": "Date the invoice was issued" },
    { "key": "due_date", "type": "date", "context": "Payment due date" },
    { "key": "total_amount", "type": "number", "context": "Total amount due" },
    { "key": "currency", "type": "string", "context": "Currency code (e.g. USD, EUR)" },
    {
      "key": "line_items",
      "type": "array",
      "context": "Individual line items on the invoice",
      "arrayType": "object",
      "fields": [
        { "key": "description", "type": "string", "context": "Item description" },
        { "key": "quantity", "type": "number", "context": "Quantity ordered" },
        { "key": "unit_price", "type": "number", "context": "Price per unit" }
      ]
    }
  ],
  "source": "api",
  "runId": null,
  "processingTimeMs": 3842,
  "createdAt": "2024-11-20T14:30:00.000Z"
}

ApiKeyPublic

The public projection of an API key. The actual key value and its hash are never returned after creation.

interface ApiKeyPublic {
  id: string              // Key ID
  userId: string          // Owner user ID
  name: string            // Label for the key
  prefix: string          // First 16 characters of the key (e.g., "dm_live_a1b2c3d4")
  expiresAt: string | null  // ISO 8601 expiration, null if never expires
  lastUsedAt: string | null // ISO 8601 last usage, null if never used
  createdAt: string       // ISO 8601 timestamp
  revoked: boolean        // Whether the key has been revoked
}

Field Descriptions

Field	Type	Description
id	string	Unique identifier for the API key.
userId	string	The ID of the user who owns this key.
name	string	A human-readable label for the key (e.g., "Production Server").
prefix	string	The first 16 characters of the key, useful for identifying which key is in use without exposing the full value.
expiresAt	string | null	ISO 8601 timestamp of when the key expires. null if the key was created with no expiration.
lastUsedAt	string | null	ISO 8601 timestamp of the last time the key was used to authenticate a request. null if never used.
createdAt	string	ISO 8601 timestamp of when the key was created.
revoked	boolean	Whether the key has been revoked. In list responses, revoked keys are filtered out, so this is typically false.

Example

{
  "id": "key_m3x9kq72",
  "userId": "u_abc123",
  "name": "Production Server",
  "prefix": "dm_live_a1b2c3d4",
  "expiresAt": "2025-03-15T00:00:00.000Z",
  "lastUsedAt": "2025-01-10T09:22:14.000Z",
  "createdAt": "2024-12-15T10:00:00.000Z",
  "revoked": false
}

WebhookPublic

The public projection of a webhook. The signing secret is never returned after creation.

interface WebhookPublic {
  id: string              // Webhook ID
  userId: string          // Owner user ID
  url: string             // Registered endpoint URL
  events: WebhookEvent[]  // Subscribed events
  active: boolean         // Whether the webhook is active
  createdAt: string       // ISO 8601 timestamp
}

type WebhookEvent = 'extraction.completed' | 'extraction.failed'

Field Descriptions

Field	Type	Description
id	string	Unique identifier for the webhook.
userId	string	The ID of the user who owns this webhook.
url	string	The HTTPS endpoint that receives webhook POST requests.
events	string[]	The events this webhook is subscribed to. Values: "extraction.completed", "extraction.failed".
active	boolean	Whether the webhook is active. In list responses, only active webhooks are returned, so this is always true.
createdAt	string	ISO 8601 timestamp of when the webhook was created.

Example

{
  "id": "webhook-abc123def456",
  "userId": "uid_a1b2c3d4e5f6",
  "url": "https://your-app.com/webhooks/docmap",
  "events": ["extraction.completed", "extraction.failed"],
  "active": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

Variable

A variable defines a single field in an extraction template. Variables tell the AI what data to look for and what type to return it as.

interface Variable {
  key: string              // Field name in extracted data
  type: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array'
  context: string          // Description/hint for the AI extractor
  required?: boolean       // Whether the field is required
  fields?: Variable[]      // Nested fields (for type: 'object')
  arrayType?: 'string' | 'number' | 'object'  // Item type (for type: 'array')
}

Field Descriptions

Field	Type	Description
key	string	The field name that will appear as a key in the extracted data. Must be at least 1 character.
type	string	The expected data type. One of: string, number, date, boolean, object, array.
context	string	A natural-language description that helps the AI understand what to extract for this field. More specific context produces better results.
required	boolean	(Optional) If true, the AI will always attempt to return a value for this field.
fields	Variable[]	(Optional) For type: "object", defines the nested fields within the object. This is recursive -- nested objects can contain their own fields.
arrayType	string	(Optional) For type: "array", specifies the type of items in the array. One of: string, number, object. When arrayType is "object", use fields to define the shape of each item.

Recursive Structure

Variables support arbitrary nesting through the fields property. An object variable contains child variables, and an array variable with arrayType: "object" also uses fields to describe each array item.

This allows you to model complex document structures like invoices with line items, contracts with multiple parties, or any hierarchical data.

Example: Invoice Template with Nested Variables

[
  {
    "key": "vendor_name",
    "type": "string",
    "context": "Name of the vendor or supplier company",
    "required": true
  },
  {
    "key": "invoice_number",
    "type": "string",
    "context": "Invoice or reference number"
  },
  {
    "key": "invoice_date",
    "type": "date",
    "context": "Date the invoice was issued (YYYY-MM-DD)"
  },
  {
    "key": "total_amount",
    "type": "number",
    "context": "Total amount due including tax"
  },
  {
    "key": "billing_address",
    "type": "object",
    "context": "The billing address on the invoice",
    "fields": [
      { "key": "street", "type": "string", "context": "Street address" },
      { "key": "city", "type": "string", "context": "City name" },
      { "key": "state", "type": "string", "context": "State or province" },
      { "key": "zip", "type": "string", "context": "Postal or ZIP code" },
      { "key": "country", "type": "string", "context": "Country name or code" }
    ]
  },
  {
    "key": "line_items",
    "type": "array",
    "context": "Individual line items listed on the invoice",
    "arrayType": "object",
    "fields": [
      { "key": "description", "type": "string", "context": "Item description" },
      { "key": "quantity", "type": "number", "context": "Quantity ordered" },
      { "key": "unit_price", "type": "number", "context": "Price per unit" },
      { "key": "total", "type": "number", "context": "Line total (quantity x unit_price)" }
    ]
  },
  {
    "key": "tags",
    "type": "array",
    "context": "Keywords or categories that describe this invoice",
    "arrayType": "string"
  }
]

In this example:

• billing_address is an object with five nested string fields.
• line_items is an array of objects, each with description, quantity, unit_price, and total.
• tags is a simple array of strings with no nested fields.

UsageResponse

Returned by the GET /v1/usage endpoint. Shows the authenticated user's current plan and extraction usage for the billing period.

interface UsageResponse {
  plan: 'free' | 'starter' | 'core' | 'pro'
  usage: number            // Extractions used this period
  limit: number            // Maximum for current plan
  periodKey: string        // Current period (e.g., "2025-01")
}

Field Descriptions

Field	Type	Description
plan	string	The user's current plan. One of: free, starter, core, pro.
usage	number	The number of extractions consumed in the current billing period.
limit	number	The maximum number of extractions allowed for the user's plan.
periodKey	string	The current billing period in YYYY-MM format (e.g., "2025-01").

Example

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2025-01"
  }
}

TIP

The usage endpoint returns data wrapped in a data object, as shown above.

ErrorResponse

All API errors follow a consistent structure with a machine-readable code and a human-readable message.

interface ErrorResponse {
  error: {
    code: string           // Machine-readable error code
    message: string        // Human-readable description
  }
}

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Extraction not found"
  }
}

See the Error Codes reference for the full list of error codes, their HTTP status codes, and resolution steps.