Creating a business is the first step of onboarding. A single POST /v1/businesses accepts the whole entity graph — the legal entity plus its owners, signatories, bank accounts, addresses, locations, and the services it wants — and PCE creates all of it in one atomic call, returning generated IDs for every piece.

You can send as much or as little as you have. The minimum is a legal name; a complete, underwriting-ready payload for card acquiring is the goal. For the full field list, jump to the Request reference.

📘
One call, one response shape
POST, GET, and PATCH on a business all return the same object shape. A freshly created business comes back with PENDING_* statuses throughout; the same shape later shows populated values as boarding progresses. See Onboarding statuses.

Common use cases

Onboard a single-location merchant that wants to accept card payments
Onboard a business with multiple owners and authorized signers
Stand up a business record first, then add its details incrementally

Create your first business

The smallest call creates a business with only a legal name. Use it to confirm auth and see the response shape.

POST /v1/businesses

{
  "legalName": "PCETest Downtown Coffee LLC"
}

You get back a business with a generated id, status: PENDING_REQUIREMENTS, and a services/requirements structure showing there's more to provide. Store the returned id.

📘
Use idempotency-key for safe retries
Send a unique idempotency-key header on the create call. If the request times out and you retry with the same key, PCE creates the business only once. Set your own externalId in the body too, so you can look the business up later with ?externalId=.

Create a complete business

For card acquiring, underwriting needs the full picture: the legal entity, its beneficial owners (one marked as control person), a funding bank account, a registered address, and at least one location with a processing profile. This is a complete, single-call payload for an LLC.

POST /v1/businesses

{
  "externalId": "acme-merchant-001",
  "legalName": "PCETest Acme Services LLC",
  "businessType": "llc",
  "businessDescription": "General retail merchant",
  "email": "[email protected]",
  "phone": "+15122947810",
  "taxIds": [
    { "type": "ein", "value": "12-3456789", "country": "US", "isPrimary": true }
  ],
  "incorporations": [
    { "date": "2020-01-15", "state": "CA", "country": "US", "isPrimary": true }
  ],
  "addresses": [
    { "type": "registered", "line1": "100 Congress Ave", "city": "Austin",
      "stateProvince": "TX", "postalCode": "78701", "countryCode": "US", "isPrimary": true }
  ],
  "owners": [
    {
      "individual": {
        "firstName": "Casey",
        "lastName": "Control",
        "dateOfBirth": "1985-07-22",
        "nationality": "US",
        "email": "[email protected]",
        "phone": "+15128854626",
        "taxId": { "type": "ssn", "value": "123456789", "country": "US" },
        "governmentIds": [
          { "type": "drivers_license", "number": "DL77000947", "country": "US", "state": "TX" }
        ],
        "addresses": [
          { "type": "home", "line1": "100 Congress Ave", "city": "Austin",
            "stateProvince": "TX", "postalCode": "78701", "countryCode": "US" }
        ]
      },
      "ownershipPercentage": 50.00,
      "isControlPerson": true,
      "title": "Owner"
    }
  ],
  "bankAccounts": [
    { "purpose": ["funding", "billing"], "accountNumber": "1179204333",
      "routingNumber": "021000021", "accountType": "checking", "bankName": "Wells Fargo" }
  ],
  "locations": [
    {
      "name": "Store 1",
      "address": { "line1": "901 Commerce St", "city": "Austin", "stateProvince": "TX",
                   "postalCode": "78701", "countryCode": "US" },
      "phone": "+14155550521",
      "processingProfile": {
        "estimatedMonthlyVolume": 50000.00,
        "avgTicket": 150.00,
        "highTicket": 5000.00,
        "returnPolicy": "30-day refund",
        "priorProcessorUses": false,
        "priorSecurityBreach": false,
        "cardMix": { "swipedPercent": 90, "motoPercent": 5, "ecomPercent": 5 }
      },
      "operational": { "isSeasonal": false },
      "industry": { "mccCode": "5411", "description": "Retail grocery" }
    }
  ],
  "services": {
    "acquiring": { "enabled": true }
  }
}

Response — 201 Created (abbreviated; masked and status fields shown)

{
  "id": "bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4",
  "externalId": "acme-merchant-001",
  "status": "PENDING_REQUIREMENTS",
  "legalName": "PCETest Acme Services LLC",
  "businessType": "llc",
  "taxIds": [ { "type": "ein", "lastFour": "6789", "country": "US", "isPrimary": true } ],
  "owners": [
    { "id": "own_71", "uri": "/v1/businesses/bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4/owners/own_71",
      "individualId": "ind_abc-123", "ownershipPercentage": 50.00, "isControlPerson": true,
      "title": "Owner", "status": "PENDING_VERIFICATION" }
  ],
  "bankAccounts": [
    { "id": "ba_88", "uri": "/v1/businesses/bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4/bank-accounts/ba_88",
      "purpose": ["funding", "billing"], "accountNumberLast4": "4333", "accountType": "checking",
      "bankName": "Wells Fargo" }
  ],
  "locations": [
    { "id": "loc_12", "uri": "/v1/businesses/bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4/locations/loc_12",
      "name": "Store 1", "status": "PENDING" }
  ],
  "services": {
    "acquiring": {
      "uri": "/v1/businesses/bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4/services/acquiring",
      "enabled": true, "status": "PENDING_UNDERWRITING",
      "missingFields": [], "missingDocuments": [], "errors": []
    }
  },
  "createdAt": "2026-06-15T09:00:00Z",
  "updatedAt": "2026-06-15T09:00:00Z"
}

🚧
PENDING-PUBLISH, examples
Request values are illustrative (drawn from the tested boarding collection). The response body is representative of the verified business shape and may be incomplete — confirm the exact 201 body, the masked-field set, and initial statuses against the published API Reference before publish.

Linking people

Every entry in owners[] and signatories[] links to an Individual. Supply exactly one of three ways to identify that person:

Way	When to use it	Field
Inline `individual`	The person isn't on PCE yet — create and link in one step.	`individual: { firstName, lastName, … }`
Existing `individualId`	You already created the person (or reuse one across businesses).	`individualId: "ind_…"`
Individual `externalId`	You track the person by your own reference.	resolve via `?externalId=`, then pass `individualId`

Creating a person and linking them as an owner/signer are two distinct operations. Passing an inline individual does both in one call.

📘
One control person, always
Across all owners and signatories, exactly one person must have isControlPerson: true. Zero or more than one is rejected. Ownership percentage is separate from control — set both deliberately.

Scenarios

Real businesses come in a few common shapes, and each changes the payload — mostly the businessType and the ownership rules it triggers. The complete payload above is the standard LLC with one owner. The scenarios below adapt it; only the parts that differ are called out. The exact rejection messages each rule produces are in Error handling.

Scenario 1: Sole proprietor

(owner holds 100%)

A sole proprietor (or single-member LLC). The non-guarantor owner must hold 100%, any guarantor 0%, and when the control person's tax ID and the business tax ID are both SSN/ITIN they must match.

Adapt the complete payload with businessType: "sole_proprietor" and a single owner at ownershipPercentage: 100.00, isControlPerson: true.

Scenario 2: Partnership

(owners must total ≥ 50%)

Beneficial ownership is split across partners; tax ID is an EIN. Provide each partner as an owner and mark exactly one as the control person.

Adapt with businessType: "partnership" and multiple owners[] whose ownershipPercentage values sum to 50 or more (for example two partners at 30.00 and 25.00).

Scenario 3: Non-profit or government

(beneficial ownership is 0)

A non-profit, 501(c)(3), or government entity has no equity owners, so beneficial-owner ownership must be 0. You still provide a control person so KYB has a responsible individual.

Adapt with businessType: "nonprofit" (or government / tax_exempt_501c3), owners at ownershipPercentage: 0 (or none), and a signatory marked isControlPerson: true.

🚧
PENDING-PUBLISH
Confirm whether a non-profit/government control person is supplied as an owner at 0% or strictly as a signatory, and whether owners[] may be empty in that case. Verify against the API Reference before publish.

Scenario 4: Multiple owners and signers

Provide each person once (inline or by individualId), split ownership to satisfy the rule for the businessType, and mark exactly one person as the control person.

POST /v1/businesses

{
  "externalId": "multi-owner-001",
  "legalName": "PCETest Acme Services LLC",
  "businessType": "llc",
  "businessDescription": "General retail merchant",
  "email": "[email protected]",
  "phone": "+15122947810",
  "taxIds": [ { "type": "ein", "value": "12-3456789", "country": "US", "isPrimary": true } ],
  "incorporations": [ { "date": "2020-01-15", "state": "CA", "country": "US", "isPrimary": true } ],
  "addresses": [
    { "type": "registered", "line1": "100 Congress Ave", "city": "Austin",
      "stateProvince": "TX", "postalCode": "78701", "countryCode": "US", "isPrimary": true }
  ],
  "owners": [
    { "individual": { "firstName": "Casey", "lastName": "Control", "dateOfBirth": "1985-07-22",
        "nationality": "US", "email": "[email protected]", "phone": "+15128854626",
        "taxId": { "type": "ssn", "value": "123456789", "country": "US" },
        "governmentIds": [ { "type": "drivers_license", "number": "DL77000947", "country": "US", "state": "TX" } ] },
      "ownershipPercentage": 60.00, "isControlPerson": true, "title": "CEO" },
    { "individual": { "firstName": "Riley", "lastName": "Partner", "dateOfBirth": "1988-03-10",
        "nationality": "US", "email": "[email protected]", "phone": "+15128854627",
        "taxId": { "type": "ssn", "value": "987654321", "country": "US" },
        "governmentIds": [ { "type": "drivers_license", "number": "DL77000948", "country": "US", "state": "TX" } ] },
      "ownershipPercentage": 40.00, "isControlPerson": false, "title": "Investor" }
  ],
  "signatories": [
    { "individualId": "ind_abc-123", "isPrimary": true, "isGuarantor": true, "title": "CEO" }
  ],
  "bankAccounts": [
    { "purpose": ["funding", "billing"], "accountNumber": "1179204333",
      "routingNumber": "021000021", "accountType": "checking", "bankName": "Wells Fargo" }
  ],
  "locations": [
    { "name": "Store 1",
      "address": { "line1": "901 Commerce St", "city": "Austin", "stateProvince": "TX",
                   "postalCode": "78701", "countryCode": "US" },
      "processingProfile": { "estimatedMonthlyVolume": 50000.00, "avgTicket": 150.00, "highTicket": 5000.00,
        "cardMix": { "swipedPercent": 90, "motoPercent": 5, "ecomPercent": 5 } },
      "industry": { "mccCode": "5411", "description": "Retail grocery" } }
  ],
  "services": { "acquiring": { "enabled": true } }
}

The signatory above links by individualId to the same person who is already an owner — create the person once, link them into as many roles as apply. The same SSN cannot be used for two separate owners on one business.

Scenario 5: Build incrementally

(minimal create, then add sub-resources)

When you don't have everything up front — or you're driving onboarding from a multi-step UI — create the business minimally and add each piece on its own endpoint.

Create the shell — POST /v1/businesses with just { "legalName": "…" }.
Create the people as standalone Individuals — POST /v1/individuals.
Add owners/signatories by individualId — POST /v1/businesses/{businessId}/owners.
Add a bank account, address, and location on their own endpoints (.../bank-accounts, .../addresses, .../locations).
Enable the service — PATCH /v1/businesses/{businessId}/services with { "acquiring": { "enabled": true } }.
Read it back with ?expand=true and check each service's missingFields / missingDocuments.

See Manage an entity for the full set of sub-resource endpoints.

Attach a document

Some businesses need a signed agreement or supporting file bound before underwriting. A document is uploaded once, then bound to the business by reference.

🚧
PENDING-PUBLISH
The Document resource (upload store and download) is planned, and the upload mechanism (multipart vs. pre-signed URL) is not finalized. A business create/GET does accept and return a documents[] binding today. Document the concrete upload → bind flow only after the resource ships. Until then, treat attachment as: obtain a doc_… id, then include documents: [{ "id": "doc_…", "acceptedAt": "…" }] on the business.

Read the business back

After creating, read the full entity to get every generated child id and uri you'll need for later updates. Use ?expand=true to inline shared references (such as each owner's Individual).

GET /v1/businesses/{businessId}?expand=true

The response is the same shape as create, with each embedded child carrying its own id and uri, plus a top-level _links block. See Manage an entity for how to use those to update a single child.

Request reference

The composite create accepts the business's own fields plus nested collections. Scenarios use subsets of these.

Business fields

Field	Required	Description
`legalName`	✓	Registered legal name of the business.
`businessType`	For acquiring	One of `c_corporation`, `s_corporation`, `llc`, `single_member_llc`, `llp`, `partnership`, `sole_proprietor`, `government`, `nonprofit`, `tax_exempt_501c3`.
`businessDescription`	For acquiring	Plain-language description of what the business does (max 512 chars).
`email`, `phone`	For acquiring	Business contact details. `phone` in E.164.
`taxIds[]`	For acquiring	`{ type, value, country, isPrimary }`. Corporations/LLCs/partnerships require `type: ein`.
`incorporations[]`	For acquiring	`{ date, state, country, isPrimary }`.
`industry`	See note	Business-level industry `{ mccCode, category }`. Per-site industry lives on the location.
`externalId`	Recommended	Your own reference; immutable once set.

Nested collections

Collection	Element	Notes
`owners[]`	`{ individual \| individualId, ownershipPercentage, isControlPerson, title }`	Exactly one control person across owners + signatories.
`signatories[]`	`{ individual \| individualId, isPrimary, isGuarantor, title }`	Authorized signers.
`bankAccounts[]`	`{ purpose[], accountNumber, routingNumber, accountType, bankName, isPrimary }`	`purpose` ⊆ `funding, billing, reserves, chargeback, recovery, sweep`.
`addresses[]`	`{ type, line1, line2?, city, stateProvince, postalCode, countryCode, isPrimary }`	`type` ∈ `registered, mailing, physical, headquarters, home, work`.
`locations[]`	`{ name, address, phone?, email?, processingProfile, operational?, industry }`	`cardMix` percentages must total 100.
`services`	`{ acquiring: { enabled, features? } }`	Desired-state map. Enable `acquiring` for Accept Payments.
`documents[]`	`{ id \| documentId, acceptedAt }`	Binding to an uploaded document. See the Documents note in Key concepts.

Validation

PCE validates the whole graph atomically at create time. If any check fails, the request returns an error and no business is created. Common submit-time checks:

Required fields present and correctly typed.
businessType-specific KYB rules (tax ID type, ownership totals, control person). See Key concepts.
Each location has an MCC and a cardMix totaling 100%.
Bank routing/account numbers are well-formed.

Requirements that can only be judged during underwriting surface after creation on each service's missingFields, missingDocuments, and errors, and via status. See Onboarding statuses and Error handling.

Next steps

Manage an entity

Add or change owners, accounts, locations, and services after creation.

Track boarding status

Follow the business from requirements to underwriting to active.

Create a Business

One call, one response shape

Create your first business

Use `idempotency-key` for safe retries

Create a complete business

PENDING-PUBLISH, examples

Linking people

One control person, always

Scenarios

Scenario 1: Sole proprietor

Scenario 2: Partnership

Scenario 3: Non-profit or government

PENDING-PUBLISH

Scenario 4: Multiple owners and signers

Scenario 5: Build incrementally

Attach a document

PENDING-PUBLISH

Read the business back

Request reference

Business fields

Nested collections

Validation

Next steps

See also

One call, one response shape

Create your first business

Use idempotency-key for safe retries

Create a complete business

PENDING-PUBLISH, examples

Linking people

One control person, always

Scenarios

Scenario 1: Sole proprietor

Scenario 2: Partnership

Scenario 3: Non-profit or government

PENDING-PUBLISH

Scenario 4: Multiple owners and signers

Scenario 5: Build incrementally

Attach a document

PENDING-PUBLISH

Read the business back

Request reference

Business fields

Nested collections

Validation

Next steps

See also

Use `idempotency-key` for safe retries