Stage a boarding record

POST

/v1/loans/{ref}/boarding/stage

curl --request POST \
  --url http://localhost:8080/v1/loans/example/boarding/stage

Phase one of two-phase boarding: maps and validates the package, stages it on the core adapter, records the full preview and moves the loan from approved to boarding_staged. Send an Idempotency-Key header to make retries safe; the same key for the same loan replays the original record (201 again) instead of staging twice. Requires a signed-in admin, manager or specialist (not an API key). 404 for an unknown loan, 409 unless the loan is approved, 400 with one error per core field when validation fails, 422 when the adapter refuses the staging or no active field map exists.

Parameters

Path Parameters

ref

required

string

Header Parameters

Idempotency-Key

string

Responses

201

Created

Media typeapplication/json

The staged record with every core field and its provenance.

object

boardingId

required

string format: uuid

loanId

required

string format: uuid

loanRef

required

string

provider

required

string

fieldMapId

required

string format: uuid

fieldMapVersion

required

integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

state

required

string

preview

required

Array<object>

One core field ready to post: code, wire value and where it came from. string? CoreFieldValue.Value is null when the map found no source.

object

coreField

required

string

canonical

required

string

transform

required

string

value

required

null | string

source

required

One of:

null

null

object

Where a boarded value came from ( “every core field + source provenance”).

object

documentId

required

string format: uuid

documentName

required

string

docType

required

string

canonical

required

string

pageNo

required

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

x

required

null | number | string format: double

/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/

y

required

null | number | string format: double

/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/

w

required

null | number | string format: double

/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/

h

required

null | number | string format: double

/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/

requiredApprovalRole

required

string

stagedBy

required

string format: uuid

stagedAt

required

string format: date-time

approvedBy

required

null | string format: uuid

approvedAt

required

null | string format: date-time

committedAt

required

null | string format: date-time

coreReference

required

null | string

error

required

One of:

null

null

object

Stored as boarding_records.error_json: the provider’s answer verbatim.

object

status

required

string

detail

required

string

rawResponse

required

null | string

at

required

string format: date-time

attempt

required

integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

idempotencyKey

required

null | string

Example^generated

{
  "boardingId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "loanId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "loanRef": "example",
  "provider": "example",
  "fieldMapId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "fieldMapVersion": 1,
  "state": "example",
  "preview": [
    {
      "coreField": "example",
      "canonical": "example",
      "transform": "example",
      "value": "example",
      "source": {
        "documentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "documentName": "example",
        "docType": "example",
        "canonical": "example",
        "pageNo": 1,
        "x": 1,
        "y": 1,
        "w": 1,
        "h": 1
      }
    }
  ],
  "requiredApprovalRole": "example",
  "stagedBy": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "stagedAt": "2026-04-15T12:00:00Z",
  "approvedBy": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "approvedAt": "2026-04-15T12:00:00Z",
  "committedAt": "2026-04-15T12:00:00Z",
  "coreReference": "example",
  "error": {
    "status": "example",
    "detail": "example",
    "rawResponse": "example",
    "at": "2026-04-15T12:00:00Z",
    "attempt": 1
  },
  "idempotencyKey": "example"
}