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.
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.
| grant_type | client_credentials |
| client_id | From the app page. |
| client_secret | Shown once when created or rotated. |
| scope | Optional. Space-separated; defaults to all granted scopes. |
files.documents.write (attach documents) · files.read (look up files). A pending app receives dry_run_only: true.curl -X POST "https://bloompartner.binex-softgroup.com/oauth/token" \
-d "grant_type=client_credentials" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}"{
"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.
| file * | The document. Any type except executables, up to 20 MB. |
| fileNo mblNo hblNo | Exactly one *. Bloom File No., Master B/L No. or House B/L No. |
| docType | Optional 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. |
| externalRef | Optional. Your own ID for the document (100 characters). |
| note | Optional. Shown in the File's History (200 characters). |
| ?dryRun=true | Validate everything and find the File, store nothing. Works before approval. |
| Idempotency-Key | Header, recommended. A retry with the same key within 24 hours returns the first result instead of a duplicate (response header Idempotent-Replayed: true). |
curl -X POST "https://bloompartner.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"{
"ok": true,
"documentId": 90412,
"file": { "fileNo": "OI-2611-0042", "matchedBy": "mblNo" },
"status": "received",
"externalRef": "erp-doc-48211",
"requestId": "req_c4abafdcecb9"
}{
"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" }.
| HTTP | code | Meaning · what to do |
|---|---|---|
| 400 | invalid_request | A field is missing or wrong. The message says which. |
| 400 | invalid_doc_type | Unknown docType. Omit it to let Bloom identify the document. |
| 401 | invalid_token | Missing, expired or revoked token. Request a new one. |
| 403 | not_approved | The app is pending or the scope is not granted. Use dryRun until approved. |
| 403 | app_disabled | The app was disabled. |
| 403 | ip_not_allowed | The request came from an address outside the app's allow list. |
| 403 | file_out_of_scope | The File exists but this app may not reach it. |
| 404 | file_not_found | No File matches the key. Nothing was stored. |
| 409 | ambiguous_file | Several Files match. The response lists them in files[]; resend with fileNo. |
| 409 | file_closed | The File is Closed or Void and takes no new documents. |
| 413 | file_too_large | Over 20 MB. |
| 415 | unsupported_file_type | Executable and script files are not accepted. |
| 429 | rate_limited | Wait for the seconds in the Retry-After header. |
Limits
| File size | 20 MB per document. |
| Rate | 60 requests per minute per app by default (the Bloom admin can change it). Over the limit: 429 with Retry-After. |
| Token | Valid for 60 minutes. Disabling an app or changing its access takes effect on the next request. |
| Secret rotation | The previous secret keeps working for 24 hours. |