API and webhooks

Authentication

The API authenticates with API keys, not a username and password, so your integration does not break when someone changes their password.

• You create keys yourself under Settings in your DocAccord account (verified email address required).
• Every request sends the key as a header: Authorization: Bearer da_live_.... Browser session logins are not accepted on /api/v1.
• The key is shown exactly once. Only a SHA-256 hash and a short prefix for recognition are stored. A lost key is replaced, not recovered.
• Scopes: lc:read fetches results, lc:write runs billable checks. New keys get both; you can narrow a key to one scope in Settings, for example for a system that only collects results.
• Choose the lifetime: 30, 90, 180, 365 (default) or 730 days. Every new key expires. Up to 10 active keys per account. A revoked key stops working immediately. The owner and admins of the organisation see and revoke every key of the organisation.
• Rotating without a gap: create the new key and name the one it replaces (replaces, optional overlap_hours from 1 to 72, default 24). The old key then expires after that period instead of being revoked at once.
• The Enterprise plan is checked on every call, not only at creation. If an account leaves the Enterprise plan, its keys answer with 403.

Run a check

One multipart/form-data request with your documents. The response comes back synchronously once the check is stored.

• Required: the credit and the commercial invoice. Each document either as a file (lc_file, invoice_file) or as text (lc_text, invoice_text), never both.
• Transport documents, same pattern (_file or _text): bill_of_lading, multimodal_transport_doc, air_transport_doc, road_rail_inland_waterway_doc, charter_party_bill_of_lading, sea_waybill, courier_receipt. At least one is required unless field 46A of the credit asks for none; that is checked once the credit is read, before anything is billed.
• Further transport sets (for example a second bill of lading, or an air waybill next to the bill of lading): up to three files in additional_transport_files, one set per file, with its type at the same position in additional_transport_types (such as BILL_OF_LADING, AIR_TRANSPORT_DOC). A check stays one credit.
• Optional, same pattern: packing_list, weight_list, certificate_of_origin, insurance_certificate, bill_of_exchange, beneficiary_certificate, inspection_certificate. Plus the shipment advice as text in shipment_advice_text (a file variant follows once the size limit at the entry point is adjusted).
• Files up to 20 MB: PDF, scans and photos (PNG, JPEG, GIF, WEBP, TIFF, BMP), DOCX, XLSX and text formats. The format is detected from the file content, not its name. The invoice may also be an EN 16931 e-invoice (XRechnung, ZUGFeRD, Factur-X, UBL or CII): as an XML file, or as a PDF with the XML attached. An XML file is read without AI (reading route E_INVOICE_XML in provenance); for a PDF with XML attached the pages are read and the XML then replaces the numbers, dates and ids. The bill of lading may also be an electronic bill of lading as a DCSA eBL 3.0 transport document (a JSON file, bill_of_lading_file or bill_of_lading_text): it is read from its data without AI (reading route EBL_DCSA_JSON) and counts as an electronic record where the credit is subject to eUCP. Only the data is read: the authenticity of the record, the platform and the title holder are not checked.
• strictness: STANDARD (default) or STRICT.
• amount_to_be_drawn (optional): the amount you claim under the credit, in its currency. When the invoice is above the credit, this amount decides (UCP 600 Art. 18(b)); without it and without a draft you get a warning to confirm.
• presentation_date (optional, YYYY-MM-DD): the day you will present the documents. With it the API checks the presentation period (UCP 600 Art. 14(c)) and that no document is dated later (Art. 14(i)); without it a note (presentationDateNotGiven) says neither was checked.
• instalment_number and earlier_instalments_on_time (optional): under a credit with an instalment schedule, which instalment you present (1 for the first) and whether every earlier instalment was shipped and drawn in its period (true or false). Without them the instalment is inferred from the shipment date (UCP 600 Art. 32).
• presented_counts (optional): a JSON object with the originals and copies you present per document, for example {"insurance_certificate": {"originals": 1, "copies": 0}} (the keys are the document fields of the request). With it the check tells you when the credit or UCP 600 asks for more (Art. 17, Art. 19 to 22 and 28(b)); without it you keep the notes that the count cannot be verified. earlier_drawn_amount, earlier_drawn_quantity and earlier_containers_shipped (optional): what earlier drawings under this credit took, in its currency and unit. With them the API checks the credit as a whole (total amount, total quantity, the last containers; UCP 600 Art. 18(b), 30 and 31). An invalid value is a 400 before anything is read or billed.
• presentation_medium (optional): PAPER, ELECTRONIC or MIXED, how the documents go to the bank, with MIXED plus electronic_doc_types (comma separated, for example INVOICE,PACKING_LIST). It matters only when the credit is subject to eUCP, which the API reads from fields 40E, 46A and 47A.
• amendment_file or amendment_text (optional): one amendment (an MT707 or an amendment letter from the bank) you have not answered yet, with amendment_status PENDING, ACCEPTED or REJECTED (PENDING when left out). The documents are then checked against the credit as issued and the amended credit (UCP 600 Art. 10(c)); amendment_benchmark in the result says which one the findings are measured against. A status without an amendment is a 400.
• If a required document is missing, the API answers with 400 before any document is processed or billed.
• The credit is read first, then every other document at the same time, not one after the other. The response comes as soon as the slowest document has been read.

curl -X POST https://api.docaccord.com/api/v1/lc-checks \
  -H "Authorization: Bearer da_live_YOUR_KEY" \
  -H "Idempotency-Key: shipment-4711-presentation-1" \
  -F "lc_file=@lc.pdf" \
  -F "invoice_file=@invoice.pdf" \
  -F "bill_of_lading_file=@bill_of_lading.pdf" \
  -F "packing_list_file=@packing_list.pdf" \
  -F "strictness=STANDARD"

{
  "id": 1842,
  "report_number": "LCC-2026-001842",
  "lc_reference": "LC-2026-0457",
  "overall_status": "REJECTED_DISCREPANCIES",
  "compliance_score": 85,
  "findings": [
    {
      "rule_reference": "UCP 600 Art. 18(c) / ISBP 821 C3",
      "severity": "CRITICAL_ERROR",
      "affected_document": "Commercial Invoice #INV-2291",
      "field_name": "Goods Description",
      "found_value": "100% cotton men's shirts",
      "expected_value": "100% cotton men's shirts, style X",
      "explanation_code": "goodsDescExactMismatch",
      "explanation_params": {},
      "requires_acknowledgment": false,
      "suggested_fix_code": "goodsDescExactMismatchFix",
      "suggested_fix_params": { "lcText": "100% cotton men's shirts, style X" },
      "affected_doc_type": "INVOICE"
    }
  ],
  "created_at": "2026-09-23T09:14:02.118204"
}

• overall_status is PASSED_FOR_BANK, WARNINGS_FOUND or REJECTED_DISCREPANCIES. severity is CRITICAL_ERROR, WARNING or INFO.
• Each finding names the rule reference, the affected document and field, and the found and expected values. Instead of a rendered sentence the API returns a stable explanation_code with parameters, so you can render the text in your own system.
• requires_acknowledgment is true when a person must confirm the finding because the data alone cannot decide it. suggested_fix_code with suggested_fix_params is the suggested correction, affected_doc_type the document type. The params of a published code never change; a new meaning gets a new code, and the old one stays in the GET /api/v1/finding-codes catalogue for 90 days.
• provenance says what the check ran on: ruleset_version (the date of the rule set) and, per document, whether the DocAccord Reader read it (extraction_model, value docaccord-reader), whether an independent second reading ran (verify_model, value docaccord-reader), the reader version (prompt_sha) and the reading route (extraction_route). Both fields are empty when a document was typed rather than read. An old result stays explainable after the rules or the reader changed.
• Use the id to fetch the result again later via GET /api/v1/lc-checks/{id}.

Retries without double billing

• Optional header Idempotency-Key. If the same request is repeated with the same key, you get the stored result back: no second check, no second charge.
• The same key with a different request returns 409. So does a second request while the first one with that key is still running.
• For uploaded files, the request is recognised by the content of the file (SHA-256), not its name. Use a new key for every new document set.
• Stored results are kept for at least 24 hours.

Credit review

Review the credit itself the moment it arrives or while it is still a draft, when an amendment is still a phone call. The exporter gets the LC Workability Review, the importer the LC Pre-Issuance Review: one route, two views.

• The credit is required as lc_file (PDF, scan, photo) or lc_text (the pasted MT700 with its MT701s), never both. side is exporter (the default, the beneficiary's view, the LC Workability Review) or importer (the applicant's view, the LC Pre-Issuance Review). is_draft=true marks a draft the parties are still negotiating: the same checks run, but a finding is then a negotiating position rather than an amendment.
• Optional: a sales order as order_file, order_text or order_json (the same keys as on the ERP pre-check). order_check lists every difference from the credit as a warning, apart from the status, counts and score.
• Optional: case_id (one of your cases from GET /api/v1/lc-cases) or save_to_case=true saves the terms as a version with the source credit_review. Without a case_id the case is found or opened by the credit's reference number. The terms are saved only when every field the reading doubted was confirmed by a person. The API cannot do that, so for a reading with a doubt credit_saved.status is unconfirmed and nothing is saved. A draft is never saved (422). Without a save request the route saves nothing and credit_saved is null.
• The response gives overall_status (WORKABLE, REVIEW_ADVISED or BLOCKED), risk_band and risk_score (our own weighted count, not a probability and not a rating by any bank), the findings with explanation_code, params and the severity for the other party, and advice and commercial, the commercial reading. The wording in suggested_clause is English because it goes into a credit. When it is locked for your account after the one free reveal, wording is null and locked is true; the finding itself is never withheld.
• Billing: no check credit, as in the app. The reading goes through the same gate as POST /api/extract and the reading allowance for credits. A pasted MT700 is read too (the model reads it, a deterministic SWIFT reader reads the same text a second time and settles every difference); the review, the comparison with the order and the wording need no model. Scopes (lc:write), 60 requests an hour, the Idempotency-Key (its own scope) and the error format are those of POST /api/v1/lc-checks. The route is stateless: no id, no fetch route, no webhook. A retry with the same key returns the stored answer without reading again.

# The LC Workability Review (side=exporter) of a credit that just arrived.
# Use side=importer for the LC Pre-Issuance Review of a draft you are about to
# send to your bank. lc_text takes the pasted MT700 instead of a file.
curl -X POST https://api.docaccord.com/api/v1/lc-reviews   -H "Authorization: Bearer da_live_YOUR_KEY"   -H "Idempotency-Key: credit-LC-2026-0457-review-1"   -F "lc_file=@lc.pdf"   -F "side=exporter"   -F "is_draft=false"

{
  "lc_reference": "LC-2026-0457",
  "side": "exporter",
  "is_draft": false,
  "overall_status": "BLOCKED",
  "error_count": 1,
  "warning_count": 1,
  "risk_band": "MEDIUM",
  "risk_score": 33,
  "findings": [
    {
      "id": "IR-001",
      "rule_reference": "L/C Field 31D",
      "severity": "CRITICAL_ERROR",
      "field_name": "Expiry date (31D)",
      "explanation_code": "irAlreadyExpired",
      "explanation_params": { "expiry": "2026-09-01" },
      "requires_acknowledgment": false,
      "counterparty_severity": "CRITICAL_ERROR",
      "text_variant": null,
      "suggested_clause": null
    },
    {
      "id": "IR-003",
      "rule_reference": "UCP 600 Art. 28(g)",
      "severity": "INFO",
      "field_name": "Documents required (46A)",
      "explanation_code": "irInsuranceRisksUnstated",
      "explanation_params": { "document": "Insurance Certificate" },
      "requires_acknowledgment": false,
      "counterparty_severity": "INFO",
      "text_variant": null,
      "suggested_clause": {
        "clause_id": "LC-INS-02",
        "wording": "The insurance line in field 46A is amended to state the risks to be covered, ...",
        "locked": false,
        "rule_reference": "UCP 600 Art. 28(g)",
        "guidance_code": "clause.insuranceRisks"
      }
    }
  ],
  "advice": [
    { "code": "thirdPartyDocuments", "tone": "COST", "params": { "count": 2, "list": "Certificate of Origin; Insurance Certificate" }, "cost": 300.0, "cost_currency": "EUR" }
  ],
  "commercial": null,
  "order_check": null,
  "credit_saved": null,
  "ruleset_version": "2026-09-29",
  "created_at": "2026-10-01T09:14:02.118204+00:00"
}

Limits and billing

• API access is included in the Enterprise plan. Other plans cannot create keys, and calls are refused with 403.
• A check through the API is billed exactly like a check in the browser: first from the period's included checks, then from check credits.
• When included checks and credits are used up, POST /api/v1/lc-checks answers with 402. GET /api/v1/usage shows where you stand at any time.
• Enterprise accounts can buy check credit packs of any quantity on the Billing page and switch on automatic top-up: when the credit balance falls below a level you choose, the quantity you chose is bought and charged to your subscription's payment method (Paddle sends the invoice), up to a monthly limit you set. Credits arrive once Paddle confirms the payment, usually within a minute. A 402 while a top-up is running carries Retry-After, and GET /api/v1/usage shows auto_topup_enabled and topup_pending.
• ping, usage, the list of cases, fetching past results and the credit review (POST /api/v1/lc-reviews) spend no check credit. An ERP pre-check (POST /api/v1/lc-cases/{case_id}/document-checks) spends one check credit once all its documents are read, exactly like a check; if reading fails it costs nothing.
• Rate limit: 60 requests per hour per API key on POST /api/v1/lc-checks, POST /api/v1/lc-reviews and POST /api/v1/lc-cases/{case_id}/document-checks, 200 per hour per key on every other authenticated route. Above that the API answers with 429.
• One check reads at most 15 documents, not counting the credit and its amendment. A request with more is refused with 429 before the first one is read; split the presentation into two checks. Documents of requests that fail after they were read count until a check completes, or for at most 24 hours after the first of those readings; a request whose documents no longer fit next to them gets 429 with Retry-After. Parallel requests do not count against each other.
• Every API key has a daily limit for AI document reading that starts over at midnight UTC. At 80 percent the account's email address gets one warning a day; once the limit is reached the API answers 429 with Retry-After until midnight UTC. Close to the limit, a request can also get 429 with Retry-After 60 while other requests with the key are still running; retry it after a minute. Checks already running are not interrupted. Write to us if you need a higher limit.

Error codes

Errors come back as JSON with a human-readable detail field.