documents.jp API

You send physical documents to documents.jp. We scan them. The API delivers the PDF, page images, and extracted content to your app or your team. There is no file upload. Paper is the input; the API is the output.

Authentication

Every request carries a secret key in the Authorization header. Sandbox keys start with sk_test_. Live keys start with sk_live_.

Authorization: Bearer sk_test_…

Send paper

Each account gets a receiving address in Japan. Forward mail there, or ship receipts, invoices, 名刺, and books. A scan object is created when the item arrives — you do not POST a file.

合同会社グリーン
c/o documents.jp
〒106-0032 東京都港区…

Types we scan: mail, receipt, invoice, business_card, book, or auto.

Set a destination

Tell us where to POST each completed scan. Your app, a teammate’s service, or another scanning product.

curl https://api.documents.jp/v1/destinations \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://app.yours.com/inbox"}'

{
  "id": "dest_12ab",
  "url": "https://app.yours.com/inbox",
  "status": "active"
}

Retrieve a scan

Pull the scan after it is complete, or wait for the webhook. files.pdf and files.images are signed URLs.

{
  "id": "scan_9f3a2c",
  "status": "complete",
  "type": "invoice",
  "pages": 2,
  "language": "ja",
  "files": {
    "pdf": "https://files.documents.jp/v1/scans/scan_9f3a2c.pdf",
    "images": [
      "https://files.documents.jp/v1/scans/scan_9f3a2c/1.jpg",
      "https://files.documents.jp/v1/scans/scan_9f3a2c/2.jpg"
    ]
  },
  "document": { },
  "received": 1787664000,
  "completed": 1787664300
}

List scans

Cursor-paginated. Query starting_after, limit (1–100), and optional type.

Webhooks

When a physical document has been scanned, we POST the full scan object — PDF, images, and content — to your destination. That POST is the product.

Verify with the X-Documents-Signature HMAC-SHA256 of the raw body, using your webhook secret.

Mail schema

Returned in document when type is mail.

{
  "sender": { "name": "福岡市", "address": "…" },
  "recipient": { "name": "合同会社グリーン", "address": "…" },
  "posted_on": "2026-08-12",
  "subject": "固定資産税納税通知書",
  "body_text": "…",
  "attachments": [
    { "kind": "notice", "pages": [1, 2] }
  ]
}

Receipt schema

{
  "merchant": "セブン-イレブン 渋谷2丁目",
  "paid_on": "2026-08-25",
  "currency": "JPY",
  "subtotal": 1080,
  "tax": 108,
  "total": 1188,
  "payment_method": "ic",
  "line_items": [
    { "description": "Onigiri", "qty": 2, "amount": 280 }
  ]
}

Invoice schema

{
  "vendor": "東京電力エナジーパートナー",
  "vendor_registration": "T1234567890123",
  "invoice_number": "2026-08-88421",
  "issued_on": "2026-08-12",
  "due_on": "2026-09-15",
  "currency": "JPY",
  "subtotal": 12982,
  "tax": 1298,
  "total": 14280,
  "qualified_invoice": true,
  "line_items": [
    { "description": "電気料金 8月分", "amount": 12982, "tax_rate": 0.10 }
  ]
}

Business card schema

{
  "name": "佐藤 美咲",
  "title": "Director of Operations",
  "company": "合同会社グリーン",
  "email": "misaki@example.jp",
  "phone": "+81-3-0000-0000",
  "address": "東京都港区…",
  "url": "https://example.jp",
  "side": "front"
}

Book schema

{
  "title": "会社法講義",
  "authors": ["山田 太郎"],
  "publisher": "…",
  "isbn": "978-4-00-000000-0",
  "language": "ja",
  "page_count": 412,
  "pages": [
    { "number": 1, "text": "…" }
  ]
}

Errors

Errors are JSON. Codes are stable.