PUBLIC API v1

Import a pre-processed document without OCR

POST /api/v1/companies/{company_pk}/attachments/structured-import/

Stores one document and optional metadata supplied by an external document system. It never runs OCR, creates or matches a transaction, or categorizes bookkeeping data. external_source + external_id make retries idempotent within the company.

Permission: write_documents · Direct link

Company-scoped. Account permissions, plan limits and document state still apply.

Path and query parameters

Parameter	Location / type	Description
`company_pk`Required	path · `string (uuid)`	Not specified

Request body

multipart/form-data

Field	Type / accepted values	Description
`file`Required	`string (binary)`	Not specified
`externalSource`	`string`	Not specified
`externalId`	`string`	Not specified
`supplier`	`string`	Not specified
`customer`	`string`	Not specified
`invoiceNumber`	`string`	Not specified
`invoiceDate`	`string (date)`	Not specified
`serviceDate`	`string (date)`	Not specified
`netAmount`	`string (decimal)`	Not specified
`vatAmount`	`string (decimal)`	Not specified
`grossAmount`	`string (decimal)`	Not specified
`currency`	`string`	Not specified
`documentType`	`"invoice" \| "receipt" \| "credit_note" \| "contract" \| "other"`	* `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `contract` - contract * `other` - other
`direction`	`"incoming" \| "outgoing"`	* `incoming` - incoming * `outgoing` - outgoing
`tags`	`string[]`	Not specified

Responses

200 Response fields

application/json

Field Type / accepted values Description

createdRequired boolean Not specified

metadataRequired object Not specified

documentRequired

object

Not specified

Nested fields

Field	Type / accepted values	Description
`publicId`RequiredRead only	`string (uuid)`	Not specified
`created`RequiredRead only	`string (date-time)`	Not specified
`file`	`string (uri) \| null`	Not specified
`transactions`Required	`string (uuid)[]`	Not specified
`company`Required	`string (uuid)`	Not specified
`attachmentType`	`"invoice" \| "receipt" \| "contract" \| "other"`	* `invoice` - Invoice * `receipt` - Receipt * `contract` - Contract * `other` - Other
`amount`	`string (decimal) \| null`	Not specified
`amountExchanged`	`string (decimal) \| null`	Not specified
`attachmentNumber`	`string`	Not specified
`brandName`	`string`	Not specified
`currency`	`string`	Not specified
`currencyExchanged`	`string \| null`	Not specified
`description`	`string`	Not specified
`supplierCountry`	`"DE" \| "PL" \| "DOMESTIC" \| "INSIDE_EU" \| "OUTSIDE_EU" \| ""`	Not specified
`valueDate`	`string (date-time) \| null`	Not specified
`vatSumAmount`	`string (decimal) \| null`	Not specified
`vatSumAmountExchanged`	`string (decimal) \| null`	Not specified
`fileName`	`string`	Not specified
`saleType`	`"GOODS" \| "SERVICES" \| ""`	Not specified
`vatRate`	`23 \| 19 \| 8 \| 7 \| 5 \| 0 \| -1 \| -2`	* `23` - 23% * `19` - 19% * `8` - 8% * `7` - 7% * `5` - 5% * `0` - 0% * `-1` - CUSTOM % * `-2` - Reverse charge
`extractedItems`	`object \| null`	Per-item OCR extraction results: [{description, amount, vat_rate, ...}]
`fileHash`	`string`	Not specified
`retentionUntil`	`string (date) \| null`	Not specified
`externalSource`	`string`	Not specified
`externalId`	`string`	Not specified

201 Response fields

application/json

Field Type / accepted values Description

createdRequired boolean Not specified

metadataRequired object Not specified

documentRequired

object

Not specified

Nested fields

Field	Type / accepted values	Description
`publicId`RequiredRead only	`string (uuid)`	Not specified
`created`RequiredRead only	`string (date-time)`	Not specified
`file`	`string (uri) \| null`	Not specified
`transactions`Required	`string (uuid)[]`	Not specified
`company`Required	`string (uuid)`	Not specified
`attachmentType`	`"invoice" \| "receipt" \| "contract" \| "other"`	* `invoice` - Invoice * `receipt` - Receipt * `contract` - Contract * `other` - Other
`amount`	`string (decimal) \| null`	Not specified
`amountExchanged`	`string (decimal) \| null`	Not specified
`attachmentNumber`	`string`	Not specified
`brandName`	`string`	Not specified
`currency`	`string`	Not specified
`currencyExchanged`	`string \| null`	Not specified
`description`	`string`	Not specified
`supplierCountry`	`"DE" \| "PL" \| "DOMESTIC" \| "INSIDE_EU" \| "OUTSIDE_EU" \| ""`	Not specified
`valueDate`	`string (date-time) \| null`	Not specified
`vatSumAmount`	`string (decimal) \| null`	Not specified
`vatSumAmountExchanged`	`string (decimal) \| null`	Not specified
`fileName`	`string`	Not specified
`saleType`	`"GOODS" \| "SERVICES" \| ""`	Not specified
`vatRate`	`23 \| 19 \| 8 \| 7 \| 5 \| 0 \| -1 \| -2`	* `23` - 23% * `19` - 19% * `8` - 8% * `7` - 7% * `5` - 5% * `0` - 0% * `-1` - CUSTOM % * `-2` - Reverse charge
`extractedItems`	`object \| null`	Per-item OCR extraction results: [{description, amount, vat_rate, ...}]
`fileHash`	`string`	Not specified
`retentionUntil`	`string (date) \| null`	Not specified
`externalSource`	`string`	Not specified
`externalId`	`string`	Not specified

400 Response fields

application/json

Field	Type / accepted values	Description
`detail`Required	`string`	Not specified
`code`	`integer`	Not specified
`type_`	`string`	Not specified
`field`Required	`string`	Not specified

401 Response fields

application/json

Field	Type / accepted values	Description
`detail`RequiredRead only	`string`	Not specified

403 Missing scope, company mismatch, unsupported operation, or a plan/account restriction.

429 Rate limit exceeded. Wait for the Retry-After header before retrying.

Use the base URL https://api.norman.finance/api/v1. Sign up or log in to Norman to create an API key, then send it as a Bearer token. For an OpenAPI JSON file, contact support.