Skip to content

Developers

Suppliers

Received (purchase) invoices extracted by the docparser pipeline.

GET /suppliers

List received (purchase) invoices

Purchase invoices extracted by the docparser pipeline. Date filters apply to `createdAt` (ingestion date), not the extracted invoice date.

Required permission: purchases:documents.read (Purchases › Supplier invoices and expenses › Read)

Pagination: Parameters page and limit. The response includes total, page, limit, hasMore.

Parameters

NameInTypeDescription
statequerystringIngestion pipeline state, e.g. BOOKED, NEEDS_REVIEW.
needsReviewqueryboolean
dateFromquerystring (date)
dateToquerystring (date)
pagequeryinteger
Default: 1
limitqueryinteger
Default: 50 · maximum: 500

Responses

200 List of supplier invoices · application/json

NameTypeDescription
itemsobject[]
items[].idstring
items[].companyIdstring
items[].filenamestring
items[].confidencenumber
nullable
items[].statestring
items[].needsReviewboolean
items[].createdAtstring (date-time)
items[].updatedAtstring (date-time)
totalintegerTotal items matching the filter.
pageintegerPage returned (starts at 1).
limitintegerPage size applied.
hasMorebooleanThere are more pages after this one.

401 Missing or invalid Bearer token. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

403 Token lacks the required permission, or the resource is outside the token's tenant. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

429 Rate limit exceeded. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

Examples

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers?limit=50" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers?limit=50", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers?limit=50",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

GET /suppliers/items/{id}

Get one received invoice

Full extracted detail including per-line fields. 404 for items outside your tenant.

Required permission: purchases:documents.read (Purchases › Supplier invoices and expenses › Read)

Pagination: Not paginated: returns the full set.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Supplier invoice · application/json

NameTypeDescription
idstring
companyIdstring
filenamestring
confidencenumber
nullable
issuerNifstring
nullable
issuerNamestring
nullable
invoiceNumberstring
nullable
invoiceDatestring (date)
dueDatestring (date)
nullable
baseAmountnumber
nullable
vatAmountnumber
nullable
totalnumber
nullable
currencystring
statestring
linesobject[]
lines[].descriptionstring
nullable
lines[].quantitynumber
nullable
lines[].unitPricenumber
nullable
lines[].lineTotalnumber
nullable
lines[].vatRatenumber
nullable
lines[].taxCodestring
nullable
SII regime code
lines[].accountCodestring
nullable
PGC account code
fileUrlstring (uri)Exchange for a presigned download via GET /suppliers/items/{id}/file.

401 Missing or invalid Bearer token. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

403 Token lacks the required permission, or the resource is outside the token's tenant. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

404 Resource not found (or belongs to a different tenant). · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

429 Rate limit exceeded. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

Examples

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers/items/<id>" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers/items/<id>", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers/items/<id>",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

GET /suppliers/items/{id}/file

Download the original purchase document

Returns a redirect to a short-lived presigned URL for the original file.

Required permission: purchases:documents.read (Purchases › Supplier invoices and expenses › Read)

Pagination: Not paginated: returns the full set.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

302 Redirect to a presigned download URL

401 Missing or invalid Bearer token. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

403 Token lacks the required permission, or the resource is outside the token's tenant. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

404 Resource not found (or belongs to a different tenant). · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

429 Rate limit exceeded. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

Examples

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers/items/<id>/file" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers/items/<id>/file", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers/items/<id>/file",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

POST /ingest/batches

Upload a purchase document for extraction

Multipart upload of a purchase invoice (PDF/image). L1 dedup by SHA-256 returns 200 for an identical re-upload. `companyId` is forced from the token. Machine reading: with your own account-bound token, a document sent without `consent` is queued for OCR + extraction, unless your account asked for human review only; `consent=AI_AUTO` is read even then (your choice for that document wins); `consent=HUMAN_ONLY` is never read. Internal BMC tokens (BMC staff, agents, the MCP gateway) need an explicit `consent=AI_AUTO` or `origen=email`, and can never override your account's human-review-only preference. A document that is not read is stored and a person fills it in (`status: NEEDS_REVIEW`). The response never hides a non-read: `lectura: "en_cola"` when it is queued for reading, or `lectura: "no"` with `motivo` from a closed list: `sin_consentimiento` (internal token, no consent and no origen), `origen_sin_eleccion` (internal token, a channel other than email and no consent), `cuenta_solo_personas` (the account asked for human review only), `human_only` (consent=HUMAN_ONLY), `propietario_sin_resolver` (the owning account cannot be resolved: never read), `origen_no_verificado` (internal token, `origen=email` without a reference to an e-mail of the same account). `origen=email` counts only with `threadAttachmentId` or `messageId` of an e-mail of the same account. `consentimiento` carries the decision: consent, origen, llamante (cliente | interno) and origenVerificado.

Required permission: documents:ingest.create (Documents › Document capture › Create)

Pagination: Not paginated: returns the full set.

Request body multipart/form-data

NameTypeDescription
filerequiredstring (binary)The document bytes.
filenamestring
consentstringWhether the document may be read by machine. Your account-bound token: missing = read unless your account asked for human review only; AI_AUTO = read even then; HUMAN_ONLY = never read. Internal tokens: missing = not read unless origen=email.
Values: AI_AUTO, HUMAN_ONLY
origenstringChannel the document came in through. Only decides for internal tokens: email is read unless the account asked for human review only, and only with the e-mail reference (threadAttachmentId or messageId); any other channel only with consent AI_AUTO.
Values: email, subir, data_room, desconocido
threadAttachmentIdstringWith origen=email: the attachment of the source e-mail. It must exist and belong to the same account.
messageIdstringWith origen=email: the source e-mail message, if no threadAttachmentId. It must exist and belong to the same account.

Responses

200 L1 dedup hit - identical file already ingested

201 File accepted (returns batchId + itemId, `lectura`, `motivo` and `consentimiento`): `status: QUEUED` and `lectura: "en_cola"` when it is read by machine; `status: NEEDS_REVIEW` and `lectura: "no"` with its `motivo` when a person fills it in

400 Missing file, unsupported type, or too large · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

401 Missing or invalid Bearer token. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

403 Token lacks the required permission, or the resource is outside the token's tenant. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

429 Rate limit exceeded. · application/json

NameTypeDescription
errorstringHuman-readable error message
required_permissionstringPresent on 403 - the missing permission (area:resource.action)

Examples

curl
curl -X POST "https://app.bm.consulting/api/v1/ingest/batches" \
  -H "Authorization: Bearer $BMC_TOKEN" \
  -F "file=@documento.pdf"
TypeScript (fetch)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("documento.pdf")]), "documento.pdf");

const res = await fetch("https://app.bm.consulting/api/v1/ingest/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.post(
    "https://app.bm.consulting/api/v1/ingest/batches",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    files={"file": open("documento.pdf", "rb")},
    timeout=30,
)
res.raise_for_status()
data = res.json()
Book your free first meeting