# Migration API



<EndpointIndex
  names={[
  	'startMigration',
  	'startMigrationForAccount',
  	'resumeMigration',
  	'recoverMigration',
  	'pauseMigration',
  	'patchMigration',
  	'getMigrationSummary',
  	'getMigrationMappings',
  	'getMigrationMappingsForAccount',
  	'getAccountMigrations',
  	'listAccountMigrations',
  	'getMigrationFailures',
  ]}
  titles={{
  	startMigration: 'Start Migration',
  	startMigrationForAccount: 'Start Migrations for an Existing Account',
  	resumeMigration: 'Resume a Paused Migration',
  	recoverMigration: 'Attempt to Recover System Error Items for a Migration',
  	pauseMigration: 'Pause a Running Migration',
  	patchMigration: 'Patch an Existing Migration Request',
  	getMigrationSummary: 'Get Migration Summary',
  	getMigrationMappings: 'Get Migration Mappings',
  	getMigrationMappingsForAccount: 'Get Migration Mappings for Account',
  	getAccountMigrations: 'Get Account Migrations',
  	listAccountMigrations: 'List Account Migrations',
  	getMigrationFailures: 'Get Migration Failures',
  }}
/>

Migration Management [#migration-management]

Start Migration [#start-migration]

<ApiEndpoint name="startMigration" title="Start Migration" />

<Callout>
  See the [migration](/features/migration#idempotency-key-guide) feature guide for more information on idempotency keys.
</Callout>

<ApiSchema name="AccountMigrationRequest" />

<ApiSchema name="PolicyMigrationRequest" />

<ApiSchema name="MigrationPreferences" />

<ApiSchema name="MigrationInstallmentPreferences" />

<ApiSchema name="AuxDataMigrationRequest" />

<ApiSchema name="AuxDataEntryMigrationRequest" />

<ApiSchema name="TransactionMigrationRequest" />

<ApiSchema name="PaymentMigrationRequest" />

<ApiSchema name="AccountMigrationData" />

<ApiSchema name="AccountingMigrationRequest" />

<ApiSchema name="InvoiceMigrationRequest" />

<ApiSchema name="DisbursementMigrationRequest" />

<ApiSchema name="CreditItemMigrationRequest" />

<ApiSchema name="PaymentItemMigrationRequest" />

<ApiSchema name="SegmentMigrationRequest" />

<ApiSchema name="InstallmentMigrationRequest" />

<ApiSchema name="InstallmentItemMigrationRequest" />

<ApiSchema name="ElementMigrationRequest" />

<ApiSchema name="ChargeMigrationRequest" />

<ApiSchema name="TermMigrationRequest" />

<ApiSchema name="MigrationResponse" />

<ApiSchema name="ErrorDetailsResponse" />

Start Migrations for an Existing Account [#start-migrations-for-an-existing-account]

<ApiEndpoint name="startMigrationForAccount" title="Start Migrations for an Existing Account" />

<ApiSchema name="MigrationRequest" />

Resume a Paused Migration [#resume-a-paused-migration]

<ApiEndpoint name="resumeMigration" title="Resume a Paused Migration" />

Attempt to Recover System Error Items for a Migration [#attempt-to-recover-system-error-items-for-a-migration]

<ApiEndpoint name="recoverMigration" title="Attempt to Recover System Error Items for a Migration" />

Pause a Running Migration [#pause-a-running-migration]

<ApiEndpoint name="pauseMigration" title="Pause a Running Migration" />

<Callout>
  In-flight transactions will be completed before the migration pauses.
</Callout>

Patch an Existing Migration Request [#patch-an-existing-migration-request]

<ApiEndpoint name="patchMigration" title="Patch an Existing Migration Request" />

<ApiSchema name="PatchAccountMigrationRequest" />

<ApiSchema name="MigrationFailuresResponse" />

Migration Information [#migration-information]

Get Migration Summary [#get-migration-summary]

<ApiEndpoint name="getMigrationSummary" title="Get Migration Summary" />

Get Migration Mappings [#get-migration-mappings]

<ApiEndpoint name="getMigrationMappings" title="Get Migration Mappings" />

<ApiSchema name="AccountMigrationIdMappingsListResponse" />

<ApiSchema name="ListPageResponseAccountMigrationIdMappings" />

<ApiSchema name="AccountMigrationIdMappingsResponse" />

<ApiSchema name="MappingObject" />

Get Migration Mappings for Account [#get-migration-mappings-for-account]

<ApiEndpoint name="getMigrationMappingsForAccount" title="Get Migration Mappings for Account" />

Get Account Migrations [#get-account-migrations]

<ApiEndpoint name="getAccountMigrations" title="Get Account Migrations" />

<ApiSchema name="AccountMigrationResponse" />

List Account Migrations [#list-account-migrations]

<ApiEndpoint name="listAccountMigrations" title="List Account Migrations" />

<ApiSchema name="ListPageResponseAccountMigrationResponse" />

Get Migration Failures [#get-migration-failures]

<ApiEndpoint name="getMigrationFailures" title="Get Migration Failures" />

<ApiSchema name="ListPageResponseMigrationFailuresResponse" />


## API Reference

POST /migration/{tenantLocator}/migrations — startMigration
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  X-Idempotency-Key (string, header)
Request body (AccountMigrationRequest[]):
Responses:
  200 — OK

POST /migration/{tenantLocator}/migrations/accounts/{accountLocator} — startMigrationForAccount
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  accountLocator (ulid, path, required)
  X-Idempotency-Key (string, header)
Request body (MigrationRequest):
Responses:
  200 — OK

PATCH /migration/{tenantLocator}/migrations/{migrationLocator}/resume — resumeMigration
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
Responses:
  200 — OK

PATCH /migration/{tenantLocator}/migrations/{migrationLocator}/recover — recoverMigration
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
Responses:
  200 — OK

PATCH /migration/{tenantLocator}/migrations/{migrationLocator}/pause — pauseMigration
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
Responses:
  200 — OK

PATCH /migration/{tenantLocator}/migrations/{migrationLocator} — patchMigration
Tags: migration-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
Request body (PatchAccountMigrationRequest):
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator} — getMigrationSummary
Tags: migration-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator}/mappings/list — getMigrationMappings
Returns per-account mappings of system locators to original IDs
Tags: migration-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator}/accounts/{accountLocator}/mappings — getMigrationMappingsForAccount
Fetches mappings of original IDs to system locators for an account
Tags: migration-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
  accountLocator (ulid, path, required)
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator}/accounts/{accountLocator} — getAccountMigrations
Tags: migration-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
  accountLocator (ulid, path, required)
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator}/accounts/list — listAccountMigrations
Tags: migration-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 — OK

GET /migration/{tenantLocator}/migrations/{migrationLocator}/failures/list — getMigrationFailures
Tags: migration-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  migrationLocator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 — OK

AccountMigrationRequest
Properties:
  defaultCreatedBy (uuid, required)
  accountData (AccountMigrationData, required)
  policies (PolicyMigrationRequest[], required)
  invoices (InvoiceMigrationRequest[], required)
  payments (PaymentMigrationRequest[], required)
  disbursements (DisbursementMigrationRequest[], required)
  accounting (AccountingMigrationRequest, required)

PolicyMigrationRequest
Properties:
  createdBy (uuid, required)
  createdAt (datetime, required)
  id (string, required)
  productName (string, required)
  timezone (string)
  currency (string)
  durationBasis (Enum years | months | weeks | days | hours, required)
  staticData (map<string, object>, required)
  terms (TermMigrationRequest[], required)
  delinquencyPlanName (string)
  autoRenewalPlanName (string)
  preferences (MigrationPreferences) [deprecated]
  billingLevel (Enum account | inherit | policy)
  auxData (AuxDataMigrationRequest)

MigrationPreferences
Properties:
  installmentPreferences (MigrationInstallmentPreferences)

MigrationInstallmentPreferences
Properties:
  cadence (Enum none | fullPay | weekly | everyOtherWeek | monthly | quarterly | semiannually | annually | thirtyDays | everyNDays)
  anchorMode (Enum generateDay | termStartDay | dueDay)
  generateLeadDays (integer)
  dueLeadDays (integer)
  installmentWeights (number[], required)
  maxInstallmentsPerTerm (integer)
  installmentPlanName (string)
  anchorType (Enum none | dayOfMonth | anchorTime | dayOfWeek | weekOfMonth)
  dayOfMonth (integer)
  dayOfWeek (Enum monday | tuesday | wednesday | thursday | friday | saturday | sunday)
  weekOfMonth (Enum none | first | second | third | fourth | fifth)
  anchorTime (datetime)
  autopayLeadDays (number)

AuxDataMigrationRequest
Properties:
  entries (AuxDataEntryMigrationRequest[], required)
  settingsName (string, required)

AuxDataEntryMigrationRequest
Properties:
  key (string, required)
  value (string, required)

TransactionMigrationRequest
Properties:
  transactionType (string, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  issuedTime (datetime, required)
  segment (SegmentMigrationRequest)
  installments (InstallmentMigrationRequest[], required)
  preferences (MigrationPreferences)

PaymentMigrationRequest
Properties:
  createdBy (uuid)
  id (string, required)
  paymentTime (datetime, required)
  paymentItems (PaymentItemMigrationRequest[], required)
  paymentType (string, required)
  data (map<string, object>, required)
  currency (string)

AccountMigrationData
Properties:
  id (string, required)
  accountType (string, required)
  data (map<string, object>, required)
  createdAt (datetime, required)
  createdBy (uuid)
  delinquencyPlanName (string)
  autoRenewalPlanName (string)
  excessCreditPlanName (string)
  shortfallTolerancePlanName (string)
  preferences (MigrationPreferences)
  billingLevel (Enum account | inherit | policy)

AccountingMigrationRequest
Properties:
  originalAccountBalances (map<string, number>, required) — Key is a currency code (e.g. USD)

InvoiceMigrationRequest
Properties:
  id (string, required)
  startTime (datetime, required)
  endTime (datetime, required)
  generateTime (datetime, required)
  dueTime (datetime, required)
  currency (string)
  timezone (string)
  invoiceState (Enum open | settled | discarded)

DisbursementMigrationRequest
Properties:
  id (string, required)
  disbursementType (string, required)
  data (map<string, object>, required)
  disbursementTime (datetime, required)
  sources (CreditItemMigrationRequest[], required)
  currency (string)

CreditItemMigrationRequest
Properties:
  amount (number, required)

PaymentItemMigrationRequest
Properties:
  amount (number, required)
  invoiceId (string, required)

SegmentMigrationRequest
Properties:
  startTime (datetime, required)
  rootElement (ElementMigrationRequest, required)
  segmentType (Enum coverage | gap, required)

InstallmentMigrationRequest
Properties:
  id (string, required)
  invoiceId (string, required)
  startTime (datetime, required)
  generateTime (datetime, required)
  dueTime (datetime, required)

InstallmentItemMigrationRequest
Properties:
  id (string, required)
  amount (number, required)
  installmentNumber (integer, required)

ElementMigrationRequest
Properties:
  id (string, required)
  elementType (string, required)
  data (map<string, object>, required)
  coverageTerms (map<string, object>, required)
  elements (ElementMigrationRequest[], required)
  charges (ChargeMigrationRequest[], required)

ChargeMigrationRequest
Properties:
  rate (number, required)
  referenceRate (number, required)
  chargeType (string, required)
  tag (string, required)
  installmentItems (InstallmentItemMigrationRequest[], required)

TermMigrationRequest
Properties:
  startTime (datetime, required)
  endTime (datetime, required)
  transactions (TransactionMigrationRequest[], required)

MigrationResponse
Properties:
  locator (ulid, required)
  migrationState (Enum submitted | processing | paused | finished | failed | error, required)
  processedAccounts (integer, required)
  totalAccounts (integer, required)

ErrorDetailsResponse
Properties:
  originalId (string, required)
  errors (ValidationResult, required)

MigrationRequest
Properties:
  defaultCreatedBy (uuid, required)
  policies (PolicyMigrationRequest[], required)
  invoices (InvoiceMigrationRequest[], required)
  payments (PaymentMigrationRequest[], required)
  disbursements (DisbursementMigrationRequest[], required)

PatchAccountMigrationRequest
Properties:
  defaultCreatedBy (uuid, required)
  accountLocator (ulid, required)
  accountData (AccountMigrationData)
  policies (map<string, PolicyMigrationRequest>, required)
  invoices (map<string, InvoiceMigrationRequest>, required)
  payments (map<string, PaymentMigrationRequest>, required)
  disbursements (map<string, DisbursementMigrationRequest>, required)

MigrationFailuresResponse
Properties:
  accountLocator (ulid, required)
  accountOriginalId (string, required)
  accountError (ErrorDetailsResponse)
  policies (map<string, ErrorDetailsResponse>, required)
  invoices (map<string, ErrorDetailsResponse>, required)
  payments (map<string, ErrorDetailsResponse>, required)
  disbursements (map<string, ErrorDetailsResponse>, required)

AccountMigrationIdMappingsListResponse
Properties:
  listCompleted (boolean, required)
  items (AccountMigrationIdMappingsResponse[], required)

ListPageResponseAccountMigrationIdMappings
Properties:
  listCompleted (boolean, required)
  items (AccountMigrationIdMappingsResponse[], required)

AccountMigrationIdMappingsResponse
Properties:
  migrationLocator (ulid, required)
  accountLocator (ulid, required)
  originalAccountId (string, required)
  policies (map<string, MappingObject>, required)
  invoices (map<string, MappingObject>, required)
  payments (map<string, MappingObject>, required)
  disbursements (map<string, MappingObject>, required)

MappingObject
Properties:
  originalId (string, required)
  childrenMappings (map<string, object>, required)
  migratedAt (datetime, required)

AccountMigrationResponse
Properties:
  accountLocator (ulid)
  accountMigrationState (Enum pending | processing | error | failed | completed, required)
  processedItems (integer, required)
  errorItems (integer, required)
  totalItems (integer, required)
  lastUpdated (datetime, required)

ListPageResponseAccountMigrationResponse
Properties:
  listCompleted (boolean, required)
  items (AccountMigrationResponse[], required)

ListPageResponseMigrationFailuresResponse
Properties:
  listCompleted (boolean, required)
  items (MigrationFailuresResponse[], required)