Skip to main content
POST
/
reviews
Create Review
curl --request POST \
  --url https://api.flightlinehq.com/v1/reviews \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {
      "content_type": "application/zip",
      "filename": "full-case.zip",
      "url": "https://files.example.com/signed/full-case.zip?sig=abc123"
    }
  ],
  "label": "Smith refinance",
  "metadata": {
    "branch": "austin",
    "loan_officer": "jsmith"
  },
  "reference_id": "LN-2026-04-8812",
  "review_type": "mortgage_v1"
}
'
{
  "created_at": "2026-05-30T17:00:00Z",
  "document_count": 3,
  "label": "Smith refinance",
  "reference_id": "LN-2026-04-8812",
  "report_available": false,
  "review_id": "9b2c1f3a-4d5e-6789-abcd-ef0123456789",
  "review_type": "mortgage_v1",
  "sandbox": false,
  "status": "processing",
  "updated_at": "2026-05-30T17:00:05Z"
}

Headers

​
Idempotency-Key
string | null

Optional. A unique key (at most 255 characters) you choose for this create request. Resending the same request with the same key returns the ORIGINAL review (HTTP 200) instead of creating a duplicate, so the review pipeline runs exactly once. Keys are scoped to your organization. Distinct from 'reference_id', which rejects a duplicate with 409 rather than replaying.

​
authorization
string | null
​
X-Api-Key
string | null

Body

Create a review with either direct case-package uploads (multipart/form-data) or case packages referenced by signed source URL (application/json).

JSON body for POST /reviews (signed-source-URL variant).

The multipart/form-data variant carries the same logical fields as form parts plus the file uploads; see reviews.create_review.

​
documents
any[]

Case packages or documents to ingest by signed source URL.

​
label
string | null

Optional human-readable label shown in the dashboard.

Maximum string length: 500
Example:

"Smith refinance"

​
metadata
Metadata · object

Optional flat string->string metadata echoed back on reads.

Example:
{
  "branch": "austin",
  "loan_officer": "jsmith"
}
​
reference_id
string | null

Your external identifier for this loan package (idempotency key).

Maximum string length: 255
Example:

"LN-2026-04-8812"

​
review_type
string
default:mortgage_v1

Review template to run (maps to an internal schema).

Required string length: 1 - 100
Example:

"mortgage_v1"

Response

Successful Response

A review, as seen by the customer.

Returned by POST /reviews (201) and GET /reviews/{id}.

​
created_at
string<date-time>
required
​
review_id
string<uuid>
required

Flightline's identifier for this review.

​
review_type
string
required
​
status
enum<string>
required

Customer-facing review lifecycle.

A deliberately coarse projection of the internal CaseStatus. Internal states that are not meaningful to a customer (e.g. the admin-release gate pending_review, the publication-blocker state) collapse to processing so we never surface internal workflow detail or verdict-adjacent signal before the publication gate passes.

Available options:
queued,
awaiting_documents,
processing,
completed,
failed
​
updated_at
string<date-time>
required
​
document_count
integer
default:0

Number of documents ingested.

​
label
string | null
​
reference_id
string | null
​
report_available
boolean
default:false

True once the report is released and retrievable.

​
sandbox
boolean
default:false

True for sandbox (test-mode) reviews: canned results, no real analysis.