Bloom DevelopersSign in

Bloom Open API

Attach documents to Bloom Files from a trusted backend service. Keep the client secret on the server only — never in browser or mobile code, and never in source control.

Base URLhttps://bloompartner-test.binex-softgroup.com

Authentication

OAuth 2.0 client credentials. Request a token, cache it until expires_in runs out, and send it as a Bearer token. There is no refresh token — request a new one when it expires. The Client ID and secret may also be sent as HTTP Basic credentials.

POST/oauth/token
grant_typeclient_credentials
client_idFrom the app page.
client_secretShown once when created or rotated.
scopeOptional. Space-separated; defaults to all granted scopes.
Scopes: files.documents.write (attach documents) · files.read (look up files). A pending app receives dry_run_only: true.
Token request
curl -X POST "https://bloompartner-test.binex-softgroup.com/oauth/token" \
  -d "grant_type=client_credentials" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}"
Response · 200
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "files.documents.write",
  "requestId": "req_0c3b10308550"
}

Attach a document

One file per request, as multipart/form-data. Name the File with exactly one of the three keys; matching ignores case, spaces and hyphens. The document appears in the File's Documents tab once Bloom has identified its type, a few seconds after the response.

POST/v1/documentsfiles.documents.write
file *The document. Any type except executables, up to 20 MB.
fileNo mblNo hblNoExactly one *. Bloom File No., Master B/L No. or House B/L No.
docTypeOptional type code: MBL, HBL, SMBL, AWB, AN, PO, CI, AR, AP, DC, PL, CO, SI, ISF, AES, ENTRY, ACI, SA, OTHER. Omit to let Bloom identify it.
externalRefOptional. Your own ID for the document (100 characters).
noteOptional. Shown in the File's History (200 characters).
?dryRun=trueValidate everything and find the File, store nothing. Works before approval.
Idempotency-KeyHeader, recommended. A retry with the same key within 24 hours returns the first result instead of a duplicate (response header Idempotent-Replayed: true).
Request
curl -X POST "https://bloompartner-test.binex-softgroup.com/v1/documents" \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: erp-doc-48211" \
  -F "mblNo=MAEU240118765" \
  -F "docType=AN" \
  -F "externalRef=erp-doc-48211" \
  -F "file=@arrival-notice.pdf"
Response · 201
{
  "ok": true,
  "documentId": 90412,
  "file": { "fileNo": "OI-2611-0042", "matchedBy": "mblNo" },
  "status": "received",
  "externalRef": "erp-doc-48211",
  "requestId": "req_c4abafdcecb9"
}
Dry-run response · 200
{
  "ok": true,
  "dryRun": true,
  "file": { "fileNo": "OI-2611-0042", "matchedBy": "mblNo" },
  "document": { "name": "arrival-notice.pdf", "size": 48211, "docType": "AN" },
  "requestId": "req_28b1c3389fb0"
}

Errors

Every error has the same shape: { "ok": false, "code": "…", "message": "…", "requestId": "…" }. Branch on code; quote requestId when you ask for help. The token endpoint uses the OAuth shape { "error", "error_description" }.

HTTPcodeMeaning · what to do
400invalid_requestA field is missing or wrong. The message says which.
400invalid_doc_typeUnknown docType. Omit it to let Bloom identify the document.
401invalid_tokenMissing, expired or revoked token. Request a new one.
403not_approvedThe app is pending or the scope is not granted. Use dryRun until approved.
403app_disabledThe app was disabled.
403ip_not_allowedThe request came from an address outside the app's allow list.
403file_out_of_scopeThe File exists but this app may not reach it.
404file_not_foundNo File matches the key. Nothing was stored.
409ambiguous_fileSeveral Files match. The response lists them in files[]; resend with fileNo.
409file_closedThe File is Closed or Void and takes no new documents.
413file_too_largeOver 20 MB.
415unsupported_file_typeExecutable and script files are not accepted.
429rate_limitedWait for the seconds in the Retry-After header.

Limits

File size20 MB per document.
Rate60 requests per minute per app by default (the Bloom admin can change it). Over the limit: 429 with Retry-After.
TokenValid for 60 minutes. Disabling an app or changing its access takes effect on the next request.
Secret rotationThe previous secret keeps working for 24 hours.