Initiate a file upload

Request

Request a scoped, size-capped upload slot. Returns a file id and a single-use, short-lived presigned S3 PUT URL the partner uploads the bytes to directly. No document bytes ever cross the API.

Security

PartnerApiKey and PartnerOAuth

Path

accountIdinteger, (int64)required

Account identifier

Bodyapplication/jsonrequired

contentTypestringrequired

MIME content type the file is stored as (PDF only), compared without case or parameters. The upload PUT carries the type uploadHeaders gives.

Example:"application/pdf"

fileNamestring, <= 255 charactersrequired

Original file name; its extension decides the type the file is stored as

Example:"requisition-9001.pdf"

kindstringrequired

What a partner-uploaded document is, which fixes its content-type allowlist, size cap, and retention policy. LAB_REQUISITION_PDF: the requisition the partner attaches when it accepts an order. LAB_REPORT_PDF: a result report the partner attaches when it delivers results.

Enum:"LAB_REQUISITION_PDF""LAB_REPORT_PDF"

Example:"LAB_REQUISITION_PDF"

sizeBytesinteger, (int64)required

Exact size of the upload in bytes

Example:482113

curl -i -X POST \
  'https://api-docs.lobbie.com/_mock/openapi/partner/v2/account/{accountId}/file' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "contentType": "application/pdf",
    "fileName": "requisition-9001.pdf",
    "kind": "LAB_REQUISITION_PDF",
    "sizeBytes": 482113
  }'

Responses

Upload slot created

Bodyapplication/json

expiresAtstring, (date-time)

When the upload URL expires (UTC)

Example:"2025-01-15T14:00:00Z"

idinteger, (int64)

File id

Example:5501

statusstring

Lifecycle status of an uploaded file. PENDING: the upload slot exists and the presigned URL was issued, but the bytes have not been finalized yet, so the file cannot be referenced. CLEAN: the finalized bytes passed validation (content-type allowlist, size, and magic-byte format) and the file may be referenced by an order. The name follows the file-upload framework's terminology and is forward-compatible with the malware scan that framework adds in a later phase; today it means "passed validation, safe to reference". A CLEAN file that is not referenced within 24 hours of finalizing is discarded and reads as not found. REJECTED: the finalized bytes failed validation; the file is not referenceable and its bytes are removed.

Enum:"PENDING""CLEAN""REJECTED"

Example:"PENDING"

uploadHeadersobject

Headers that must accompany the upload PUT — the signature covers all of them, so a PUT missing any one is refused by S3

Example:

{
  "Content-Length": "482113",
  "Content-Type": "application/pdf",
  "If-None-Match": "*"
}

uploadMethodstring

HTTP method to use for the upload

Example:"PUT"

uploadUrlstring

Single-use presigned S3 URL the bytes are uploaded to directly

Example:"https://s3.amazonaws.com/lobbie-partner-uploads/abc123?X-Amz-Signature=..."

Response

{
  "expiresAt": "2025-01-15T14:00:00Z",
  "id": 5501,
  "status": "PENDING",
  "uploadHeaders": {
    "Content-Length": "482113",
    "Content-Type": "application/pdf",
    "If-None-Match": "*"
  },
  "uploadMethod": "PUT",
  "uploadUrl": "https://s3.amazonaws.com/lobbie-partner-uploads/abc123?X-Amz-Signature=..."
}