> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md # Migrate from legacy boarding to intelligent boarding > Learn how to move a boarding integration from the legacy Boarding endpoints to the intelligent boarding API > **Note** > > Intelligent boarding is in beta. To opt in, reach out to your Payabli contact. The intelligent boarding API replaces the legacy `/Boarding/*` endpoints. In legacy boarding, one application object held the business, its owners, its bank accounts, and its services. In intelligent boarding, each of those is its own record, and the application requests services for a business that already exists. Moving an integration to intelligent boarding changes the call sequence, the shape of your data, validation, and how you track an application after you submit it. Legacy boarding is deprecated and will be sunset in Q2 2027. After that, legacy boarding endpoints will no longer be available, and requests to them may fail. Until then, legacy boarding receives only critical security and stability fixes. Migrate before the sunset date to avoid disruption. ## Considerations * The intelligent boarding API uses OAuth2. Send a Bearer token on every request. See [OAuth2 authentication](/developers/oauth-authentication). * Intelligent boarding records use string references, such as `businessReference`, `personReference`, `paypointReference`, and `requestsReference`, instead of legacy numeric IDs like `appId`. ## Switch to intelligent boarding Switching to intelligent boarding doesn't change what you've already boarded with legacy boarding: * **Existing merchants stay boarded.** Merchants you boarded with legacy boarding keep processing, and you don't board them again. * **Applications in progress finish in legacy boarding.** Switching doesn't affect them. * **Stop using legacy boarding when you switch.** Boarding through both at the same time can leave your boarding data inconsistent. * **Adding services to a legacy merchant needs Payabli.** To request more services through intelligent boarding for a merchant boarded only with legacy boarding, contact Payabli first to convert the merchant's records. > **Note** > > Intelligent boarding requires configuration by the Payabli team. Contact us to get started. ## How the model changes Legacy boarding merged an application and its paypoint into a single entity. Intelligent boarding separates the business, its people, its paypoints, its payment methods, and its applications. You create the business and its paypoint first, add the people and bank accounts to the business, and then open an application that lists the services the paypoint needs. A person can be linked to more than one business, and a business can back more than one paypoint. For the full model, see [Intelligent boarding overview](/guides/pay-ops-boarding-object-model-overview). ## Map legacy calls to new endpoints A single legacy `POST /Boarding/app` call becomes several intelligent boarding calls, one for each record. The order matters, because each record needs the reference of the one before it: | Step | Legacy boarding | Intelligent boarding | | --------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create the business and its paypoint | `POST /Boarding/app` | [`POST /v2/paypoints`](/developers/api-reference/paypoints/create-a-paypoint) with an inline `business` object, or [`POST /v2/businesses`](/developers/api-reference/businesses/create-a-business) and then `POST /v2/paypoints` with the `businessReference` | | Add owners, the signer, and contacts | `ownership`, `signer`, and `contacts` on `POST /Boarding/app` | [`POST /v2/people`](/developers/api-reference/people/create-a-person) with a `businessRelationship` object, once for each person | | Add bank accounts | `bankData` on `POST /Boarding/app` | [`POST /v2/payment-methods`](/developers/api-reference/payment-methods/create-payment-methods), or `business.paymentMethods` when you create the paypoint | | Request services | `services` on `POST /Boarding/app` | [`POST /v2/requests`](/developers/api-reference/applications/create-an-application) with a `services` object | | Check the application before you submit | None | [`POST /v2/requests/{requestsReference}/validate`](/developers/api-reference/applications/validate-an-application) | | Submit the application | `onCreate` on `POST /Boarding/app`, or the hosted application | [`POST /v2/requests/{requestsReference}/submit`](/developers/api-reference/applications/submit-an-application) | | Update the application | `PUT /Boarding/app/{appId}` | `PATCH` the record that holds the data, such as the business or a person. Use [`PATCH /v2/requests/{requestsReference}`](/developers/api-reference/applications/update-an-application) only for the application's own fields, such as `services`. | | Get the application | `GET /Boarding/read/{appId}` | [`GET /v2/requests/{requestsReference}`](/developers/api-reference/applications/get-an-application) | | Remove the application | `DELETE /Boarding/app/{appId}` | [`POST /v2/requests/{requestsReference}/withdraw`](/developers/api-reference/applications/withdraw-an-application) | For a walkthrough of the intelligent boarding sequence with request and response examples, see [Board a new business with the API](/guides/pay-ops-developer-boarding-new-entity-paypoint). ## Send merchants a boarding link The legacy boarding link endpoints (`/Boarding/applink`, `/Boarding/linkbyId`, `/Boarding/linkbyTemplate`, and `/Boarding/link`) have no match in intelligent boarding. Instead, each application has its own link to the hosted boarding application, where the merchant completes it. Create the application with the API, then build the link from the application's `requestsReference`: ```txt https://app.payabli.com/boarding/app/{requestsReference} ``` ## How your data changes Most legacy fields have a match in intelligent boarding, but many move to a different record, change shape, or change format. These patterns cover most of the work. The field-by-field mapping follows in [Field mapping](#field-mapping). ### Data moves to the record it describes Legacy boarding kept everything on the application. In intelligent boarding, each value belongs to the record it describes: * **The DBA name** is `doingBusinessAs` on the paypoint. The business has no DBA field, so each paypoint carries its own. * **Owners, the signer, and contacts** are all people. You set a person's role in the business on their business link, in `businessRelationship`: `personType`, `ownershipPercentage`, `title`, `isSigner`, and `isPrimaryController`. To choose the signer, set `isSigner` to `true` on an owner's business link. Only an owner can sign. You still send a `signer` object when you submit, but it holds the signature details, not the signer's identity. * **Processing volumes** move into the business's `processingMetrics` object, such as `inboundPresentPercent`, `monthlyReceivablesVolume`, and `averageReceivableSize`. Payout volumes move into `payoutMetrics`. * **Several paypoints can share one business.** A paypoint links to its business with `businessReference`, so a business with more than one paypoint has a single business record. Paypoints that share a business are called locations. ### Flat fields become arrays Legacy boarding used numbered or prefixed flat fields for addresses and contact details. Intelligent boarding uses arrays: * **Business addresses** go in `addressDetails`, one object for each address, with a `type` such as `legal` or `mailing`. * **Personal addresses** go in the person's `addresses` array. Use the `residential` type for a home address. * **Business phone numbers** go in the `phone` array. * **Bank accounts** are separate payment methods. Legacy boarding set each account's role with the numeric `bankAccountFunction`. In intelligent boarding, each account lists what it's used for in its `usage` array, such as `deposits`, `billing`, or `payOutFunding`. ### Values change format Intelligent boarding is stricter about formats than legacy boarding: * **Dates** use ISO 8601 format, such as `2015-06-01`. Intelligent boarding rejects US-style dates like `06/01/2015` with a `400` error. * **Legal structure** takes a fixed set of values in `legalStructure`, such as `llc`, `corporation`, or `sole-proprietorship`. The legacy `btype` field accepted free text, such as `Corporation` or `Private Corp`. See [Legal structure values](#legal-structure-values) to convert them. * **Names** split into parts. The single legacy owner and contact name fields become `firstName` and `lastName`, with an optional `middleName`. ### Custom data The legacy `additionalData` object becomes `customData`. It's a free-form object on the business and on each person. ## Validate before you submit Legacy boarding had no way to check an application before you submitted it. In intelligent boarding, send a `POST` request to `/v2/requests/{requestsReference}/validate` before you submit. Validate checks the business, its people, and its payment methods against what the requested services need. It lists each missing or invalid field by its path on the record, such as `business.taxReference`. Fix the record, then validate again. Validation doesn't change the application. Validate is stricter than the create endpoints. A record can save without a field that validate still reports as missing. Request services on the application before you validate, because many requirements depend on them. For every requirement validate checks, see [What validation checks](/guides/pay-ops-developer-applications-manage#what-validation-checks). Validate also checks for data that legacy boarding didn't collect, so converted records fail validate until you add it. Expect these fields to come back missing: * **Business:** `incorporationState` and `taxIdCountry`. * **Volumes:** `processingMetrics.numberOfTransactions` when the application requests Pay In services, and `payoutMetrics.numberOfTransactions` when it requests Pay Out services. When `advancedDelivery` is `true`, the business also needs `percentAdvancedDelivery`. * **People:** `nationality` on every person except an `Employee`. People without US nationality need `nationalIdNumber` instead of `ssn`. * **Ownership:** at least one person marked `isPrimaryController`. Submit enforces some validate rules, but not all. Resolve every missing field before you submit. ## Track an application's status Intelligent boarding application statuses differ from legacy boarding statuses: * **Names and codes are new.** Legacy boarding returned `boardingStatus` codes, such as `3` for Underwriting and `99` for Activated. Intelligent boarding returns a lowercase name in `applicationStatus`, such as `pendingreview`, and a number in `applicationStatusCode`. The names and numbers don't match the legacy statuses one to one, so build your status handling on the new `applicationStatus` names instead of reusing your legacy code mapping. See [Boarding application statuses](/guides/pay-ops-boarding-application-status-reference). * **Intelligent boarding records status history.** To see every transition and what caused it, send a `GET` request to `/v2/requests/{requestsReference}/history`. * **Enablement has its own endpoint.** After approval, Payabli sets up each requested service with its processor. The application stays `approved` or `autoapproved` until every service is live, then moves to `activated`. To follow its progress, poll `GET /v2/requests/{requestsReference}/enablement`, because enablement progress has no webhook of its own. See [Check enablement after approval](/guides/pay-ops-developer-applications-manage#check-enablement-after-approval). ### Status webhooks Intelligent boarding applications send the same webhook events as legacy boarding, through the same webhook subscriptions. If you already subscribe to the legacy boarding events, you receive them for intelligent boarding applications with no change on your side. Some legacy events are narrower or no longer sent, and some statuses send no webhook: | Legacy status | Intelligent boarding status | Webhook sent | | ---------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------- | | Not Submitted (`-99`) | `draft` | `CreatedApplication`, when the application is created | | Submitted (`4`) | `submitted` | `SubmittedApplication` | | Underwriting (`3`) | `verifying` | No webhook, as in legacy boarding | | Manual Review (`6`) | `pendingreview` | `HoldingApplication` | | No equivalent | `escalatedreview`, `pendingdocuments`, `pendingresponse` | No webhook | | Approved (`7`) | `approved`, `autoapproved` | `ApprovedApplication` | | Declined (`0`) | `denied` | `DeclinedApplication` | | Withdrawn (`8`) | `withdrawn` | No webhook, as in legacy boarding | | Exception Error (`-1`) | `error` | `FailedBoardingApplication` | | Boarding (`10`) | No equivalent | No webhook. Legacy boarding sent `BoardingApplication`. | | Activated (`99`) | `activated` | `ActivatedMerchant`, one for each enabled service | | Pending Signature (`2`), Signed (`13`), Live (`100`) | No equivalent | Not applicable | Two events behave a little differently: * `FailedBoardingApplication` now fires for any application that moves to `error`. Legacy boarding sent it only for processor boarding failures. * `ActivatedMerchant` arrives once for each enabled service, as in legacy boarding. To follow a status that sends no webhook, such as `verifying` or `pendingdocuments`, poll [the application](/guides/pay-ops-developer-applications-manage#get-an-application) or [its status history](/guides/pay-ops-developer-applications-manage#track-status-changes). ## Act on an application In legacy boarding, you acted on an application by updating or deleting it. In intelligent boarding, each action is its own endpoint, and the application tells you which actions it allows: * **Check `allowedActions` first.** Application responses list the actions available in the current status. Check the list before you call a lifecycle endpoint. * **Edit only in `draft`.** You can update an application only before you submit it. * **Answer underwriting.** When underwriting requests documents or information, the application waits in `pendingdocuments` or `pendingresponse`. Upload requested documents with `POST /v2/requests/{requestsReference}/documents`, then mark the request as answered with `provide-documents` or `provide-response`. See [Upload documents](/guides/pay-ops-developer-applications-manage#upload-documents). * **Withdraw instead of delete.** Intelligent boarding has no endpoint to delete an application. Withdraw it instead, with an optional reason. You can withdraw an application in `draft`, `submitted`, `pendingdocuments`, or `pendingresponse`, and you can't reopen it afterward. See [Manage applications with the API](/guides/pay-ops-developer-applications-manage) for every action. ## Field mapping These tables map the fields you send to the legacy `POST /Boarding/app` endpoint to their intelligent boarding fields. They don't list fields that are new in intelligent boarding. See the API reference for each endpoint for every field. To automate the conversion, download the same mapping as JSON: Download JSON ### Businesses Send these fields to [`POST /v2/businesses`](/developers/api-reference/businesses/create-a-business), or in the `business` object when you create a paypoint. | Legacy field | Intelligent boarding field | Notes | | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `legalname` | `legalName` | | | `btype` | `legalStructure` | The values differ. See [Legal structure values](#legal-structure-values). | | `bsummary` | `description` | | | `ein` | `taxReference` | | | `startdate` | `establishedDate` | Use ISO 8601 format. | | `mcc` | `merchantCatCode` | | | `website` | `website` | | | `annualRevenue` | `annualRevenue` | | | `license` | `license` | | | `licstate` | `licenseState` | | | `phonenumber` | `phone` | Send it as an item in the array. | | `bEmail` | `emails` | Send it as an item in the array. | | `foreignOwned` | `isForeignOwned` | | | `seasonal` | `operatingSeasons` | | | `baddress`, `baddress1`, `bcity`, `bstate`, `bzip`, `bcountry` | `addressDetails` | One address with `type` set to `legal`. The fields are `addressLine1`, `addressLine2`, `cityLocality`, `stateProvince`, `postalCode`, and `country`. | | `maddress`, `maddress1`, `mcity`, `mstate`, `mzip`, `mcountry` | `addressDetails` | One address with `type` set to `mailing`, with the same fields. | | `binperson` | `processingMetrics.inboundPresentPercent` | | | `binweb` | `processingMetrics.inboundOnlinePercent` | | | `binphone` | `processingMetrics.inboundMotoPercent` | | | `avgmonthly` | `processingMetrics.monthlyReceivablesVolume` | | | `ticketamt` | `processingMetrics.averageReceivableSize` | | | `highticketamt` | `processingMetrics.largestReceivableSize` | | | `payoutAverageMonthlyVolume` | `payoutMetrics.monthlyPayablesVolume` | | | `payoutAverageTicketAmount` or `payoutAverageTicketLimit` | `payoutMetrics.averagePayablesSize` | Legacy boarding used either name, depending on the application type. | | `payoutHighTicketAmount` | `payoutMetrics.largestPayablesSize` | | | `whenRefunded` | `processingMetrics.refundPolicy` | `refundPolicy` takes free text. | | `whenDelivered`, `whenProvided` | `processingMetrics.advancedDelivery`, `processingMetrics.advancedDeliveryDays` | Read the two together. See [Delivery days](#delivery-days). If the result is more than 0 days, set `advancedDelivery` to `true`. | | `RepCode`, `RepName`, `RepOffice` | `customData` | Send each one as a key in the object. | | `additionalData` | `customData` | Legacy boarding accepted it on Pay In applications. | #### Legal structure values Convert each legacy `btype` value to a `legalStructure` value: | Legacy value | Intelligent boarding value | | -------------------------------------------------------------------- | -------------------------------------------------------------- | | `Sole Proprietorship`, `Sole Proprietor` | `sole-proprietorship` | | `Limited Liability Company` | `llc` | | `Corporation`, `Private Corp`, `Public Corporation`, `Public Corp` | `corporation` | | `S Corporation` | `s-corp` | | `Partnership` | `partnership` | | `Non-Profit Corporation`, `Non-Profit Association`, `Non-Profit Org` | `non-profit` | | `Government Entity`, `Government` | `government` | | `Tax Exempt` | `non-profit` or `government`, whichever describes the business | | `Trust`, `Unincorporated Association` | None | #### Delivery days Legacy boarding split delivery timing across two range fields, `whenDelivered` and `whenProvided`. Read them together, and set `advancedDeliveryDays` to a number of days in the matching range: | Legacy delivery time | Legacy time to provide | Days to set | | -------------------- | ---------------------- | ------------ | | `0-7 Days` | `30 Days or Less` | 0 to 7 | | `8-14 Days` | `30 Days or Less` | 8 to 14 | | `15-30 Days` | `30 Days or Less` | 15 to 30 | | `Over 30 Days` | `31 to 60 Days` | 31 to 60 | | `Over 30 Days` | `60+ Days` | More than 60 | ### Paypoints Send these fields to [`POST /v2/paypoints`](/developers/api-reference/paypoints/create-a-paypoint). Create one paypoint for each legacy paypoint you're migrating. When several paypoints belong to the same business, create the business once and send its `businessReference` with each paypoint. For a business that opens a new location later, see [Add a location for a business with the API](/guides/pay-ops-developer-boarding-new-location). | Legacy field | Intelligent boarding field | Notes | | -------------------- | -------------------------- | --------- | | `dbaname` | `doingBusinessAs` | Required. | | `externalPaypointId` | `externalId` | | ### People Send these fields to [`POST /v2/people`](/developers/api-reference/people/create-a-person), once for each owner, contact, and signer. Fields that start with `businessRelationship` describe the person's role in the business. For each item in the legacy `ownership` array, create a person with `businessRelationship.personType` set to `Owner`: | Legacy field | Intelligent boarding field | Notes | | ------------------------------------------------- | ------------------------------------------ | --------------------------------------------- | | `ownername` | `firstName`, `lastName` | Split the name. `middleName` is optional. | | `ownertitle` | `businessRelationship.title` | | | `ownerpercent` | `businessRelationship.ownershipPercentage` | | | `owneremail` | `primaryEmail` | | | `ownerphone1` | `primaryPhoneNumber` | | | `ownerphone2` | `secondaryPhoneNumber` | | | `ownerdob` | `dateOfBirth` | Use ISO 8601 format. | | `ownerssn` | `ssn` | | | `ownerdriver` | `driversLicenseNumber` | | | `odriverstate` | `driversLicenseState` | | | `oaddress`, `ocity`, `ostate`, `ozip`, `ocountry` | `addresses` | One address with `type` set to `residential`. | | `additionalData` | `customData` | | For each item in the legacy `contacts` array, create a person with `businessRelationship.personType` set to `Employee`: | Legacy field | Intelligent boarding field | Notes | | ---------------- | ---------------------------- | --------------- | | `contactName` | `firstName`, `lastName` | Split the name. | | `contactTitle` | `businessRelationship.title` | | | `contactEmail` | `primaryEmail` | | | `contactPhone` | `primaryPhoneNumber` | | | `additionalData` | `customData` | | The legacy `signer` object becomes an owner with `businessRelationship.isSigner` set to `true`. If the signer is already in `ownership`, set `isSigner` on that person instead of creating a new one. The signature details move to the `signer` object on [submit](/developers/api-reference/applications/submit-an-application), which also needs the signature and its `signatureType`: | Legacy field | Intelligent boarding field | Notes | | -------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------- | | `signer.name` | `firstName`, `lastName` | Split the name. | | `signer.dob` | `dateOfBirth` | Use ISO 8601 format. | | `signer.ssn` | `ssn` | | | `signer.email` | `primaryEmail` | | | `signer.phone` | `primaryPhoneNumber` | | | `signer.address`, `signer.address1`, `signer.city`, `signer.state`, `signer.zip`, `signer.country` | `addresses` | One address with `type` set to `residential`. | | `signer.acceptance` | `signer.acceptance` on submit | | | `signer.pciAttestation` | `signer.pciAttestation` on submit | | | `signer.signedDocumentReference` | `signer.signedDocumentReference` on submit | | | `signer.additionalData` | `signer.additionalData` on submit | | ### Payment methods Send one item in the `data` array for each item in the legacy `bankData` array to [`POST /v2/payment-methods`](/developers/api-reference/payment-methods/create-payment-methods). Each item also needs `type` set to `bank_account`, plus `ownerType` set to `business` and `accountOwner` set to the `businessReference`. Set `isDefault` to `true` on the account that should be the default. If you later send another account with `isDefault` set to `true`, that account becomes the default instead. | Legacy field | Intelligent boarding field | Notes | | ----------------------- | -------------------------- | ---------------------------------------------------------------------------- | | `routingAccount` | `routingNumber` | | | `accountNumber` | `accountNumber` | | | `typeAccount` | `accountType` | | | `bankName` | `financialInstitution` | | | `nickname` | `nickname` | | | `bankAccountFunction` | `usage` | See the next table. | | `bankAccountHolderType` | `ownerType` | Set `ownerType` to `business` and `accountOwner` to the `businessReference`. | | `default` | `isDefault` | | The legacy numeric `bankAccountFunction` becomes a list of `usage` values. A legacy withdrawal account, which Payabli debits for fees, becomes a `billing` account: | Legacy value | Intelligent boarding values | | ------------------------------------------- | -------------------------------------- | | `0`: Deposits | `deposits` | | `1`: Withdrawals | `billing` | | `2`: Deposits and withdrawals | `deposits`, `billing` | | `3`: Remittances | `payOutFunding` | | `4`: Remittances and deposits | `deposits`, `payOutFunding` | | `5`: Remittances and withdrawals | `billing`, `payOutFunding` | | `6`: Remittances, withdrawals, and deposits | `deposits`, `billing`, `payOutFunding` | ### Applications Send these fields to [`POST /v2/requests`](/developers/api-reference/applications/create-an-application). | Legacy field | Intelligent boarding field | Notes | | ---------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `templateId` | None | Legacy templates don't carry over. Still send a `requestTemplate` on every application, because Payabli assigns the underwriting policy from it. You choose the template for each merchant. See [Manage boarding templates with the API](/guides/pay-ops-developer-templates-manage). | | `services.card` | `services.moneyIn` | Include `Card`. The new application has no per-brand fields. | | `services.ach` | `services.moneyIn` | Include `Ach`. The new application has no SEC code fields. | | `services.odp.allowAch`, `allowChecks`, `allowVCard` | `services.moneyOut` | Include `Ach`, `Check`, or `VCard` for each payout type. | | `orgId` | None | Payabli takes the organization from your API token. | | `onCreate` | None | Submit with [`POST /v2/requests/{requestsReference}/submit`](/developers/api-reference/applications/submit-an-application). | ### Fields with no match These legacy fields have no intelligent boarding field. Leave them out of your requests: * `taxfillname`, `faxnumber`, `payoutCreditLimit`, `processingRegion`, and `creditLimit` * `whenCharged` * `bankData.bankAccountHolderName` and `bankData.country` * `signer.attestationDate` and `signer.signDate` * `recipientEmail`, `recipientEmailNotification`, and `resumable`: intelligent boarding doesn't send boarding application emails. * `services.odp.processor`, `services.odp.processing_region`, and `services.odp.issuerNetworkSettingsId`: Payabli configures these in your organization's settings. * `attachments`: upload documents separately, after you create the application. See [Upload documents](/guides/pay-ops-developer-applications-manage#upload-documents). ## Related resources See these related resources to help you get the most out of Payabli. #### References * **[Boarding application statuses](/guides/pay-ops-boarding-application-status-reference)** - Learn about the statuses a boarding application moves through and what moves it from one status to the next * **[Boarding statuses reference](/guides/pay-ops-boarding-status-reference)** - Learn about statuses and substatuses during the merchant boarding process #### Related topics * **[Intelligent boarding overview](/guides/pay-ops-boarding-object-model-overview)** - Understand the objects and application lifecycle behind intelligent boarding paypoints on Payabli * **[Board a new business with the API](/guides/pay-ops-developer-boarding-new-entity-paypoint)** - Learn how to board a new business from scratch, starting with its paypoint * **[Manage applications with the API](/guides/pay-ops-developer-applications-manage)** - Learn how to create, submit, and track boarding applications with the Payabli API