Skip to content
Steward Developers
Back to Steward

Stage a migration item from uploaded files

POST
/api/v1/migrations/{migrationId}/items

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
migrationId
required
string

Migration ID

Request Body required

Section titled “Request Body required ”
object
files
required

Source documents for one item (one detected application group) in this migration.

Array<string>
name

Optional display name for the item. Defaults to the first file name.

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”
object
id
required

Migration item ID

string
Example
507f1f77bcf86cd799439011
migrationId
required

Owning migration ID

string
Example
507f1f77bcf86cd799439011
applicationId
required

Application created from this item once the run processes it

string
nullable
Example
507f1f77bcf86cd799439011
name
required

Display name for the item: the created application’s current name when it has one (mirrors the application page, DEV-2729), else the operator-typed item label

string
entityType
required

Applicant entity type (BUSINESS/INDIVIDUAL); null defaults to business

string
Allowed values: BUSINESS INDIVIDUAL
status
required
string
Allowed values: QUEUED IN_PROGRESS COMPLETED MISSING_DATA FAILED CANCELLED
stage
required

Pipeline checkpoint. IN_PROGRESS + APP_READY means seeded but still waiting behind the queue (shown as Queued in the UI)

string
Allowed values: PENDING APP_READY CLASSIFIED EXTRACTED
files
required

Staged source files

Array<object>
object
fileName
required

Original uploaded file name

string
mimeType
required

Uploaded file MIME type

string
size
required

Uploaded file size in bytes

number
fileCount
required

Number of staged source files

number
progress
required

Per-file pipeline progress counts

object
classified
required

Files whose content classification has finished

number
summarized
required

Files summarized during the extraction stage

number
validated
required

Per-document validations completed (can exceed fileCount — one file fans out to several document types)

number
activeFile
required

File currently being processed in the active pipeline stage

string
nullable
onboardingPercent
required

Onboarding completion percent (0-100) during the finalize stage

number
nullable
validateTotal
required

Total documents queued for the validate stage — the denominator for “validated / N documents” (null before validate)

number
nullable
outstanding
required

Post-run gap summary

object
missingFields
required

Labels of required profile fields still unfilled once document extraction settled

Array<string>
error
required

Truncated error message when the item failed

string
nullable
startedAt
required

When this item started processing

string
nullable
Example
2026-03-30T12:00:00.000Z
completedAt
required

When this item finished processing

string
nullable
Example
2026-03-30T12:01:00.000Z
createdAt
required

Date the item was created

string
Example
2026-03-30T10:00:00.000Z
updatedAt
required

Date the item was last updated

string
Example
2026-03-30T12:01:00.000Z
retryable
required

Whether an operator may re-run this item: a settled status (MISSING_DATA / FAILED / CANCELLED) whose application (if any) is still PENDING. False once the app has SUBMITTED/APPROVED — re-running would re-extract and overwrite reviewed data.

boolean
Example
{
  "id": "507f1f77bcf86cd799439011",
  "migrationId": "507f1f77bcf86cd799439011",
  "applicationId": "507f1f77bcf86cd799439011",
  "name": "string",
  "entityType": "BUSINESS",
  "status": "QUEUED",
  "stage": "PENDING",
  "files": [
    {
      "fileName": "string",
      "mimeType": "string",
      "size": 0
    }
  ],
  "fileCount": 0,
  "progress": {
    "classified": 0,
    "summarized": 0,
    "validated": 0
  },
  "activeFile": "string",
  "onboardingPercent": 0,
  "validateTotal": 0,
  "outstanding": {
    "missingFields": []
  },
  "error": "string",
  "startedAt": "2026-03-30T12:00:00.000Z",
  "completedAt": "2026-03-30T12:01:00.000Z",
  "createdAt": "2026-03-30T10:00:00.000Z",
  "updatedAt": "2026-03-30T12:01:00.000Z",
  "retryable": false
}