Document AI - API Reference

AI Field Detection

POST /api/AnalyzeDocument 5 tokens

Sends a PDF through multiple AI engines (Azure Document Intelligence, GPT-4o Vision, and PII regex) to detect all meaningful fields with bounding box coordinates. Returns labeled fields with types, confidence scores, and page positions. Use this to build templates for repeated extraction.

Uses 3 detection engines in sequence for maximum coverage. Cold start may take 15-30 seconds on first call. Subsequent calls are much faster.

Parameters

Name	Type	Required	Description
`pdf`	string	required	Base64-encoded PDF
`prebuiltModel`	string	optional	Document Intelligence model: prebuilt-invoice, prebuilt-receipt, prebuilt-layout, prebuilt-idDocument, prebuilt-businessCard (default: `prebuilt-invoice`)

Request Example

JSON

{"pdf": "<base64-pdf>", "prebuiltModel": "prebuilt-invoice"}

Response Example

JSON

{"success": true, "engines": ["DocIntelligence", "Vision", "PiiRegex"], "model": "prebuilt-invoice", "fieldCount": 12, "tableCount": 1, "fields": [{"id": 0, "label": "VendorName", "value": "Acme Corp", "type": "text", "confidence": 0.95, "page": 1, "boundingBox": {"x": 72.0, "y": 680.5, "width": 180.0, "height": 14.0}, "source": "DocIntelligence"}], "tables": [{"id": 0, "label": "LineItems", "page": 1, "boundingBox": {"x": 50, "y": 300, "width": 500, "height": 150}, "columns": ["Description", "Qty", "Amount"], "rows": [["Monthly License", "1", "$400.00"]]}], "pageSizes": [{"width": 612, "height": 792}], "timing": {"totalMs": 8500, "docIntelligenceMs": 4200, "visionMs": 3800, "piiRegexMs": 120}}

Code Examples

curl -X POST "https://docbutterfly.com/api/AnalyzeDocument" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pdf": "<base64-pdf>", "prebuiltModel": "prebuilt-invoice"}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""pdf"": ""<base64-pdf>"", ""prebuiltModel"": ""prebuilt-invoice""}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/AnalyzeDocument", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/AnalyzeDocument"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"pdf": "<base64-pdf>", "prebuiltModel": "prebuilt-invoice"}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/AnalyzeDocument
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "pdf": "\u003Cbase64-pdf\u003E",
│      "prebuiltModel": "prebuilt-invoice"
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/AnalyzeDocument"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed

AI: Process Invoice

POST /api/AiProcessInvoice 5 tokens

Extracts invoice fields — vendor, invoice number, dates, totals, tax and line items — using Azure Document Intelligence's invoice model. Same engine as AI Field Detection, but the model is pinned to prebuilt-invoice instead of being chosen by classification, so the result is repeatable for a known document type.

Billed per page, at the same rate as AI Field Detection, and capped at 30 pages per request. Sending prebuiltModel is rejected with 400 — this action always runs prebuilt-invoice; call AI Field Detection when you want to choose the model.

Parameters

Name	Type	Required	Description
`pdf`	string	required	Base64-encoded PDF or image
`fileType`	string	optional	Override magic-byte detection: pdf, jpeg, png, tiff, bmp, heif
`classifyType`	boolean	optional	Also return the AI's own label for the document type (default: `false`)

Request Example

JSON

{"pdf": "<base64-pdf>"}

Response Example

JSON

{"success": true, "model": "prebuilt-invoice", "routedModel": "prebuilt-invoice", "routedFrom": "action", "aiProvenance": {"documentIntelligence": {"configured": true, "ran": true, "modelId": "prebuilt-invoice"}, "routing": {"model": "prebuilt-invoice", "routedFrom": "action"}}, "fieldCount": 12, "fields": [{"label": "InvoiceTotal", "value": "582.62", "type": "currency", "confidence": 0.97, "page": 1}], "tables": [{"label": "Items", "columns": ["Description", "Qty", "Amount"], "rows": [["Monthly License", "1", "$400.00"]]}]}

Code Examples

curl -X POST "https://docbutterfly.com/api/AiProcessInvoice" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pdf": "<base64-pdf>"}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""pdf"": ""<base64-pdf>""}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/AiProcessInvoice", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/AiProcessInvoice"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"pdf": "<base64-pdf>"}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/AiProcessInvoice
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "pdf": "\u003Cbase64-pdf\u003E"
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/AiProcessInvoice"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed

AI: Process Receipt

POST /api/AiProcessReceipt 5 tokens

Extracts receipt fields — merchant, transaction date and time, item lines, subtotal, tax, tip and total — using Azure Document Intelligence's receipt model. Pinned to prebuilt-receipt, so expense-capture flows do not depend on the document being classified correctly first.

Photographed receipts are fine — send the image bytes and let magic-byte detection sort out the format. Billed per page (an image is one page), capped at 30 pages per request.

Parameters

Name	Type	Required	Description
`pdf`	string	required	Base64-encoded PDF or image
`fileType`	string	optional	Override magic-byte detection: pdf, jpeg, png, tiff, bmp, heif
`classifyType`	boolean	optional	Also return the AI's own label for the document type (default: `false`)

Request Example

JSON

{"pdf": "<base64-receipt-photo>", "fileType": "jpeg"}

Response Example

JSON

{"success": true, "model": "prebuilt-receipt", "routedModel": "prebuilt-receipt", "routedFrom": "action", "fieldCount": 8, "fields": [{"label": "MerchantName", "value": "Blue Bottle Coffee", "type": "text", "confidence": 0.94, "page": 1}, {"label": "Total", "value": "14.80", "type": "currency", "confidence": 0.96, "page": 1}]}

Code Examples

curl -X POST "https://docbutterfly.com/api/AiProcessReceipt" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pdf": "<base64-receipt-photo>", "fileType": "jpeg"}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""pdf"": ""<base64-receipt-photo>"", ""fileType"": ""jpeg""}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/AiProcessReceipt", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/AiProcessReceipt"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"pdf": "<base64-receipt-photo>", "fileType": "jpeg"}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/AiProcessReceipt
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "pdf": "\u003Cbase64-receipt-photo\u003E",
│      "fileType": "jpeg"
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/AiProcessReceipt"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed

AI: Process ID Document

POST /api/AiProcessIdDocument 5 tokens

Extracts identity-document fields — name, document number, date of birth, issuing authority and expiry — using Azure Document Intelligence's ID model. Pinned to prebuilt-idDocument. Covers passports and driver's licenses.

Identity documents are personal data: the extracted values are returned to you and not stored — your usage row records the document hash, never the contents. Billed per page, capped at 30 pages per request.

Parameters

Name	Type	Required	Description
`pdf`	string	required	Base64-encoded PDF or image
`fileType`	string	optional	Override magic-byte detection: pdf, jpeg, png, tiff, bmp, heif
`classifyType`	boolean	optional	Also return the AI's own label for the document type (default: `false`)

Request Example

JSON

{"pdf": "<base64-id-scan>", "fileType": "png"}

Response Example

JSON

{"success": true, "model": "prebuilt-idDocument", "routedModel": "prebuilt-idDocument", "routedFrom": "action", "fieldCount": 7, "fields": [{"label": "DocumentNumber", "value": "X1234567", "type": "text", "confidence": 0.93, "page": 1}, {"label": "DateOfExpiration", "value": "2031-04-18", "type": "date", "confidence": 0.91, "page": 1}]}

Code Examples

curl -X POST "https://docbutterfly.com/api/AiProcessIdDocument" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pdf": "<base64-id-scan>", "fileType": "png"}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""pdf"": ""<base64-id-scan>"", ""fileType"": ""png""}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/AiProcessIdDocument", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/AiProcessIdDocument"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"pdf": "<base64-id-scan>", "fileType": "png"}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/AiProcessIdDocument
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "pdf": "\u003Cbase64-id-scan\u003E",
│      "fileType": "png"
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/AiProcessIdDocument"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed

Extract Data with Template

POST /api/ExtractWithTemplate 5 tokens

Applies a saved template or inline template definition to a PDF document and extracts structured JSON data. Optionally redacts specified fields and returns a flattened redacted PDF. Use templateId to reference a saved template by UUID (scoped to your client account), or pass the full template object inline.

Provide either templateId (to use a saved template) or a template object with fields array. Templates are scoped per client — each API key can only access its own templates. When includeBoundingBoxes is false (default), field results contain only value, type, and confidence — ideal for Power Automate.

Parameters

Name	Type	Required	Description
`pdf`	string	required	Base64-encoded PDF
`templateId`	string	optional	UUID of a saved template (alternative to inline template). Scoped to the calling client's account via API key.
`template`	object	optional	Inline template definition (alternative to templateId). Required if templateId is not provided.
`template.prebuiltModel`	string	optional	Document Intelligence model to use (default: `prebuilt-invoice`)
`template.fields`	array	optional	Field definitions: [{fieldKey, label, type, page, x, y, width, height}]
`redactFields`	array	optional	Field keys to redact in the output PDF
`returnRedactedPdf`	boolean	optional	Include a securely redacted PDF in the response (default: `false`)
`includeBoundingBoxes`	boolean	optional	Include bounding box coordinates in field results (default: `false`)

Request Example

JSON

{"pdf": "<base64-pdf>", "templateId": "3fdf7d3a-43e6-4f9f-a98f-bd1b77b15a41"}

Response Example

JSON

{"success": true, "fields": {"vendorName": {"value": "Acme Corp", "type": "text", "confidence": 0.95}, "invoiceTotal": {"value": 582.62, "type": "currency", "confidence": 0.97}, "invoiceDate": {"value": "2024-01-15", "type": "date", "confidence": 0.92}}, "tables": {"lineItems": {"columns": ["Description", "Qty", "Amount"], "rows": [["Monthly License", "1", "$400.00"]]}}, "redactedPdf": "JVBERi0xLjcK..."}

Code Examples

curl -X POST "https://docbutterfly.com/api/ExtractWithTemplate" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pdf": "<base64-pdf>", "templateId": "3fdf7d3a-43e6-4f9f-a98f-bd1b77b15a41"}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""pdf"": ""<base64-pdf>"", ""templateId"": ""3fdf7d3a-43e6-4f9f-a98f-bd1b77b15a41""}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/ExtractWithTemplate", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/ExtractWithTemplate"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"pdf": "<base64-pdf>", "templateId": "3fdf7d3a-43e6-4f9f-a98f-bd1b77b15a41"}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/ExtractWithTemplate
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "pdf": "\u003Cbase64-pdf\u003E",
│      "templateId": "3fdf7d3a-43e6-4f9f-a98f-bd1b77b15a41"
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/ExtractWithTemplate"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed

AI: Run Prompt

POST /api/AiRunPrompt 3 tokens

Runs your own instruction against text with an AI model — summarize, classify, rewrite, pull out a value, answer a question about a document. The generic escape hatch for anything the specific extraction endpoints do not cover.

"truncated" is true when the answer hit maxTokens — a cut-off answer looks complete to a flow, so branch on that field rather than on length. Returns 503 until the Azure OpenAI settings are configured, and 429 when the deployment is rate limiting.

Parameters

Name	Type	Required	Description
`prompt`	string	required	The instruction to run (max 32,000 characters)
`input`	string	optional	The text to run it against — typically the output of Convert PDF to Text or an extraction step (max 200,000 characters)
`systemPrompt`	string	optional	Overrides the default persona ("a precise document-processing assistant… answer with the result only"). Max 8,000 characters
`temperature`	number	optional	0 (deterministic) to 2 (creative) (default: `0.2`)
`maxTokens`	number	optional	Ceiling on the length of the answer, 1-8000 (default: `2000`)
`jsonMode`	boolean	optional	Force a JSON object back and parse it into the "json" field. Requires the word "JSON" to appear in the prompt or systemPrompt — say what shape you want (default: `false`)

Request Example

JSON

{"prompt": "Summarize this contract in three bullet points.", "input": "<the document text>", "maxTokens": 500}

Response Example

JSON

{"success": true, "output": "- Two-year term…", "finishReason": "stop", "truncated": false, "aiTokensUsed": {"prompt": 1840, "completion": 96, "total": 1936}, "timing": {"total": 2210, "aiProcessing": 2050}}

Code Examples

curl -X POST "https://docbutterfly.com/api/AiRunPrompt" \
  -H "X-API-Key: df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize this contract in three bullet points.", "input": "<the document text>", "maxTokens": 500}'

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "df_your_api_key_here");

var json = @"{""prompt"": ""Summarize this contract in three bullet points."", ""input"": ""<the document text>"", ""maxTokens"": 500}";
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://docbutterfly.com/api/AiRunPrompt", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import requests
import json

url = "https://docbutterfly.com/api/AiRunPrompt"
headers = {
    "X-API-Key": "df_your_api_key_here",
    "Content-Type": "application/json"
}
payload = json.loads('{"prompt": "Summarize this contract in three bullet points.", "input": "<the document text>", "maxTokens": 500}')

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

┌─────────────────────────────────────────────┐
│  Power Automate - HTTP Action               │
├─────────────────────────────────────────────┤
│                                             │
│  Method:  POST                              │
│  URI:     https://docbutterfly.com/api/AiRunPrompt
│                                             │
│  Headers:                                   │
│    X-API-Key:    df_your_api_key_here       │
│    Content-Type: application/json           │
│                                             │
│  Body:                                      │
│    {
│      "prompt": "Summarize this contract in three bullet points.",
│      "input": "\u003Cthe document text\u003E",
│      "maxTokens": 500
│    }
│                                             │
└─────────────────────────────────────────────┘

Steps:
1. Add an HTTP action to your flow
2. Set Method to "POST"
3. Set URI to "https://docbutterfly.com/api/AiRunPrompt"
4. Add the headers shown above
5. Paste the Body JSON into the Body field
6. Replace placeholder values with dynamic content as needed

Try in Testbed