Manage business entities with the API
Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.
A business is the legal entity behind a paypoint: the company you’re boarding, with its legal details, people, and payment methods. Use the businesses API to create and manage those records as you board a paypoint. For how businesses fit into the wider model, see the boarding overview.
Considerations
- The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
- A business belongs to an organization. Set
parentReferenceto the organization’s entrypoint to place the business there, or omit it to use the organization your credential belongs to. - Reads mask sensitive fields such as
taxReference(only the last four digits are shown). Use the unmasked endpoint when you need the raw values.
Create a business
Send a POST request to /v2/businesses with the business’s legal details. New businesses start in Draft. See the API reference for this endpoint for full documentation.
The response returns the new business’s reference and initial status:
The businessUuid in the response is the reference you use to read and manage the business.
legalStructure to a canonical value. If you send llc, reads return LimitedLiabilityCompany.Get a business
Send a GET request to /v2/businesses/{businessReference}. Sensitive fields such as taxReference are masked. See the API reference for this endpoint for full documentation.
The response returns the business’s detail with sensitive fields masked:
Get unmasked business detail
To read the raw values of masked fields, send a GET request to /v2/businesses/{businessReference}/unmasked. See the API reference for this endpoint for full documentation.
The response returns the same detail with sensitive fields unmasked:
List businesses
Send a GET request to /v2/businesses. Filter and page the results with the query parameters: status, name, merchantCatCode, legalStructure, limit, page, sortBy, and sortOrder. See the API reference for this endpoint for full documentation.
The response returns a page of businesses with pagination metadata:
Update a business
Send a PATCH request to /v2/businesses/{businessReference} with only the fields you want to change. See the API reference for this endpoint for full documentation.
The response confirms the update and returns the new timestamp:
Deactivate a business
Send a DELETE request to /v2/businesses/{businessReference}. This is a soft delete: the business moves to Deactivated and the record is kept. See the API reference for this endpoint for full documentation.
The response confirms the deactivation:
Manage the people on a business
A business’s people (owners, directors, signers, contacts, authorized users, and employees) connect to it through links. A person can have links to more than one business, and each link carries its own role, ownership, job title, and contact details. This section covers the link. To create a person or manage their own details, see Manage people with the API.
The link’s contact fields (primaryEmail, secondaryEmail, primaryPhoneNumber, secondaryPhoneNumber) and addresses belong to the relationship, not the person. Use them for how to reach the person about this business. They don’t change the person’s own contact details.
The link also sets whether the person signs the business’s boarding applications, with isSigner. Only an owner can be the signer. A business has one signer, and every application needs one before you validate or submit it. Setting isSigner to true on one person removes it from everyone else on the business.
Link people who don’t own part of the business as Employee. Application validation holds every other role to the owner requirements.
Link a person to a business
Send a POST request to /v2/businesses/{businessReference}/people with the personReference of a person you’ve already created and their role in personType. For an owner, ownershipPercentage is required, from 0 to 100. If the business’s combined ownership would go over 100%, the request fails with 400. See the API reference for this endpoint for full documentation.
The response returns the new link:
Reads return personType in lowercase, so Owner comes back as owner. Payabli sets beneficialOwner for you. The link returns its addresses as billingAddressUuid and mailingAddressUuid references rather than the full addresses.
businessRelationship object when you create the person.List a business’s people
Send a GET request to /v2/businesses/{businessReference}/people. See the API reference for this endpoint for full documentation.
The response returns every link on the business:
Get a business-person link
Send a GET request to /v2/businesses/{businessReference}/people/{personReference}. See the API reference for this endpoint for full documentation.
The response returns the link:
Update a business-person link
Send a PATCH request to /v2/businesses/{businessReference}/people/{personReference} with only the fields you want to change. Omitted fields keep their values. See the API reference for this endpoint for full documentation.
The response returns the updated link:
Unlink a person from a business
Send a DELETE request to /v2/businesses/{businessReference}/people/{personReference}. This removes the link but keeps the person record. A successful unlink returns 204 with no body. See the API reference for this endpoint for full documentation.
Related resources
See these related resources to help you get the most out of Payabli.
References
- Required fields for boarding applications - Learn more about the Know Your Customer (KYC) and Know Your Business (KYB) fields required for merchant boarding
- Funding accounts - Understand who owns a paypoint’s bank accounts and how usages decide which money each account handles