Creating the business is the first call in onboarding a merchant. You can send everything in one request, or start with just the legal name and add each part later. Either way, Priority starts underwriting a service only once that service has everything it needs. For the full field list, jump to the Request reference.

Common use cases

Board a merchant that's ready for underwriting in a single request. See Scenario 1.
Create the business now and fill in its people, accounts and locations as they arrive. See Make your first call, then Scenario 2.
Open a Treasury deposit account or turn on payouts for a business, with no locations. See Scenario 3.

Make your first call

The smallest way to create a business is with just its legal name. This stands up the record so you have an id to build on, and it needs only your sandbox API key.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "legalName": "Example Online Goods LLC" }'

Response: 201 Created.

{
  "id": "bus_8f3a2c",
  "legalName": "Example Online Goods LLC",
  "createdAt": "2026-06-15T09:00:00Z",
  "updatedAt": "2026-06-15T09:00:00Z"
}

Store the returned id. The business now exists. See Scenario 2 to patch its remaining top-level details and add each part with its own call.

Prefer to send everything at once? Scenario 1 shows the full request, an alternative to this minimal create rather than a follow-up.

Scenarios

Priority saves what you send at every step and reports what's still outstanding, so nothing is lost between calls.

Before you begin (all scenarios)

You have a sandbox API key. See Getting started.
You know the business type and the rules it triggers for owners and tax IDs. See Business validation and KYB rules.
You have each owner's and signatory's identity details, or the id of a person already on Priority.
For card processing, you have the id of the signed merchant agreement. For a business-owned deposit account, you have the id of the account agreement. See Documents.

Scenario 1: Create a business with all its details

Make a POST request to /v1/businesses. The request below creates an LLC with one owner, one signatory, a registered address and one location with its bank account. It enables Accept Payments (card-not-present).

For the other services and features you can enable, see Supported services and features.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "example-online-goods-001",
    "legalName": "Example Online Goods LLC",
    "businessType": "llc",
    "businessDescription": "Online store selling household goods.",
    "website": "https://example.com",
    "email": "[email protected]",
    "phone": "+15555550100",
    "taxIds": [
      {
        "type": "ein",
        "value": "00-0000001",
        "country": "US",
        "isPrimary": true
      }
    ],
    "incorporations": {
      "date": "2020-01-15",
      "state": "TX",
      "country": "US"
    },
    "addresses": [
      {
        "type": "registered",
        "line1": "100 Example Street",
        "city": "Austin",
        "stateProvince": "TX",
        "postalCode": "78701",
        "countryCode": "US",
        "isPrimary": true
      }
    ],
    "owners": [
      {
        "ownershipPercentage": 100,
        "isControlPerson": true,
        "title": "Managing Member",
        "individual": {
          "firstName": "Jordan",
          "lastName": "Lee",
          "dateOfBirth": "1985-07-22",
          "email": "[email protected]",
          "phone": "+15555550101",
          "taxId": {
            "type": "ssn",
            "value": "000000001",
            "country": "US"
          },
          "governmentIds": [
            {
              "type": "drivers_license",
              "number": "D0000001",
              "country": "US",
              "state": "TX"
            }
          ],
          "addresses": [
            {
              "type": "home",
              "line1": "100 Example Street",
              "city": "Austin",
              "stateProvince": "TX",
              "postalCode": "78701",
              "countryCode": "US"
            }
          ]
        }
      }
    ],
    "signatories": [
      {
        "isPrimary": true,
        "isGuarantor": false,
        "title": "Chief Financial Officer",
        "individual": {
          "firstName": "Alex",
          "lastName": "Morgan",
          "dateOfBirth": "1990-03-14",
          "email": "[email protected]",
          "phone": "+15555550103",
          "taxId": {
            "type": "itin",
            "value": "900700001",
            "country": "US"
          },
          "governmentIds": [
            {
              "type": "drivers_license",
              "number": "D0000003",
              "country": "US",
              "state": "TX"
            }
          ],
          "addresses": [
            {
              "type": "home",
              "line1": "100 Example Street",
              "city": "Austin",
              "stateProvince": "TX",
              "postalCode": "78701",
              "countryCode": "US"
            }
          ]
        }
      }
    ],
    "locations": [
      {
        "name": "Example Online Goods",
        "isPrimary": true,
        "phone": "+15555550100",
        "address": {
          "line1": "100 Example Street",
          "city": "Austin",
          "stateProvince": "TX",
          "postalCode": "78701",
          "countryCode": "US"
        },
        "processingProfile": {
          "estimatedMonthlyVolume": 50000,
          "avgTicket": 45,
          "highTicket": 500,
          "cardMix": {
            "swipedPercent": 0,
            "motoPercent": 10,
            "ecomPercent": 90
          }
        },
        "industry": {
          "mccCode": "5999",
          "category": "Retail"
        },
        "bankAccounts": [
          {
            "purposes": ["funding", "billing"],
            "accountType": "checking",
            "accountNumber": "000123456789",
            "routingNumber": "000000000",
            "bankName": "Example Bank",
            "countryCode": "US",
            "isPrimary": true
          }
        ]
      }
    ],
    "services": {
      "payin": {
        "card": {
          "enabled": true
        }
      }
    },
    "documents": [
      {
        "id": "doc_9f2a1c"
      }
    ]
  }'

The response is 201 Created with the business and an id for every part. Store them. Tax IDs and account numbers come back with the last four digits only. The account sent on the location becomes a bank account of the business, linked to that location for funding and billing. The business record itself carries no status; the card service you asked for goes through underwriting, shown by its own status on services.payin.card.

{
  "id": "bus_8f3a2c",
  "externalId": "example-online-goods-001",
  "legalName": "Example Online Goods LLC",
  "businessType": "llc",
  "taxIds": [
    {
      "type": "EIN",
      "lastFour": "0001",
      "country": "US",
      "isPrimary": true
    }
  ],
  "owners": [
    {
      "id": "own_4b7d19",
      "title": "Managing Member",
      "individual": {
        "id": "ind_2c9e51"
      }
    }
  ],
  "signatories": [
    {
      "id": "sig_3c7e9a",
      "title": "Chief Financial Officer",
      "individual": {
        "id": "ind_7b2d4f"
      }
    }
  ],
  "bankAccounts": [
    {
      "id": "ba_5e9c21",
      "accountType": "checking",
      "accountNumberLast4": "6789"
    }
  ],
  "locations": [
    {
      "id": "loc_1d6b84",
      "name": "Example Online Goods",
      "bankAccounts": [
        {
          "id": "ba_5e9c21",
          "purposes": ["funding", "billing"],
          "accountNumberLast4": "6789"
        }
      ]
    }
  ],
  "services": {
    "payin": {
      "card": {
        "enabled": true,
        "status": "PENDING_UNDERWRITING"
      }
    }
  },
  "documents": [
    {
      "id": "doc_9f2a1c"
    }
  ]
}

Nothing is missing here, so that service moves to PENDING_UNDERWRITING. If a service still needs something, it's listed in its own missingFields, missingDocuments or errors; these are left out when nothing is missing. See Status lifecycle.

Change the example for other business types

Business type	What to change
Sole proprietor	`businessType: sole_proprietor`, one owner at 100%.
Partnership	`businessType: partnership`, two or more owners holding 50% or more combined.
Non-profit, 501(c)(3) or government	`businessType: nonprofit` (or `government` or `tax_exempt_501c3`), owners at 0%, and one owner or signatory with `isControlPerson: true`.

For the full rules, see Business validation and KYB rules. To add more people, or to reuse a person you already created, see Owners and signatories.

Scenario 2: Add the parts as they arrive

After your first call creates the business, complete it in place. Patch the business for its own remaining details, then add each part with its own call. Each part is its own resource, with its own request and response example on its page. Add them in this order:

Part	Call
The business's own details	Add the type, description and contact with `PATCH /v1/businesses/{businessId}`
Owners and signatories	`POST .../owners`, `POST .../signatories`
Bank account	`POST .../bank-accounts`
Address	`POST .../addresses`
Location	`POST .../locations`
Services	`PATCH .../services`
Documents	Send the document `id` in `documents` with `PATCH /v1/businesses/{businessId}`

📘 Base path shorthand

In the table, ... is shorthand for the business base path /v1/businesses/{businessId}. For example, .../owners is /v1/businesses/{businessId}/owners.

Scenario 3: Create a business for Treasury and payouts

Treasury deposit accounts and payouts are set for the whole business, so they need no locations, processing profile, or industry code. Send the Scenario 1 request with these changes:

Leave out locations.
Replace services with the Treasury or payout services you need.
For a business-owned deposit account, attach the account agreement in documents instead of the merchant agreement. An FBO deposit account needs no document.

This services block opens an FBO deposit account. FBO stands for "for the benefit of": a deposit account held for the business and managed by the program manager.

{
  "services": {
    "treasury": {
      "fbo": {
        "enabled": true
      }
    }
  }
}

Response: 201 Created. The Treasury service reports its own status:

{
  "services": {
    "treasury": {
      "fbo": {
        "enabled": true,
        "status": "PENDING_UNDERWRITING"
      }
    }
  }
}

To set up	Send in `services`	Also send
FBO deposit account	`{ "treasury": { "fbo": { "enabled": true } } }`	Nothing more.
Business-owned deposit account	`{ "treasury": { "owned": { "enabled": true } } }`	The account agreement `id` in `documents`.
Both deposit accounts	`fbo` and `owned` together under `treasury`	The account agreement `id` in `documents`.
Payouts	`{ "payout": { "ach": { "enabled": true } } }`, or `wire` or `check`	Payouts are paid from the business-owned deposit account when the business has one, otherwise from the FBO deposit account.

For each service code, see Supported services and features.

Request reference

Field	Required	Description
`legalName`	Yes	The name registered with the government.
`externalId`	Recommended	Your own external ID for the business. A repeat value doesn't create a second business; it returns `409 DUPLICATE_EXTERNAL_ID`.
`businessType`	Any service	`c_corporation`, `s_corporation`, `llc`, `single_member_llc`, `llp`, `partnership`, `sole_proprietor`, `government`, `nonprofit` or `tax_exempt_501c3`.
`businessDescription`	Card processing	What the business sells or does. Up to 512 characters.
`email`, `phone`	No	Main contact. Phone in E.164 format, for example `+15555550100`.
`taxIds`	Any service	`type` (`ein`, `ssn` or `itin`), `value`, `country`, `isPrimary`.
`incorporations`	Any service	When and where the business was formed. `date` is needed for any service; `state` and `country` for card processing.
`tradeName`	No	The name customers know the business by.
`website`	No	The business website.
`taxFilingName`	No	The name on tax filings, if different from `legalName`.

"Any service" and "Card processing" mean the field is needed before that service can go to underwriting. Of the parts, addresses and owners are needed for any service. Locations are needed only for card processing, and bank accounts are optional for Treasury and payout services. Each service lists the fields it still needs in its missingFields. For the fields of each part (owners, bank accounts, locations and so on), see that part's page from Businesses.

Next steps

Status lifecycle

Follow the business through underwriting.

Manage a business

Update a business.