> 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 # Create a business POST https://api-sandbox.payabli.com/api/v2/businesses Content-Type: application/json Creates a business, the legal entity behind a paypoint. New businesses start in `Draft`. Set `parentReference` to the organization the business belongs to, or omit it to use the organization your credential belongs to. Reference: https://docs.payabli.com/developers/api-reference/businesses/create-a-business ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api-sandbox.payabli.com/api` (Sandbox, default) - `https://api.payabli.com/api` (Production) ## Request ### Body (application/json) This endpoint expects a CreateBusinessRequest. - `legalName` (string, required) — The registered legal name of the business. - `externalId` (string, optional) — Your own identifier for the business. - `description` (string, optional) — A free-text description of the business. - `legalStructure` (enum, optional) — The business's legal structure. Case-insensitive, and several inputs normalize to the same canonical value on read (for example, `llc` and `limited-liability-company` both read back as `LimitedLiabilityCompany`). - Allowed values: `limited-liability-company`, `llc`, `corporation`, `partnership`, `sole-proprietorship`, `non-profit`, `nonprofit`, `government`, `s-corp`, `s-corporation` - `stockSymbol` (string, optional) — The stock ticker symbol, if the business is publicly traded. - `incorporationState` (string, optional) — The state where the business is incorporated. - `taxIdCountry` (string, optional) — The country that issued the business's tax identifier. - `establishedDate` (datetime, optional) — The date the business was established. - `numberOfEmployees` (integer, optional) — The number of employees. - `annualRevenue` (double, optional) — The business's annual revenue. - `website` (string, optional) — The business's website URL. - `merchantCatCode` (string, optional) — The merchant category code (MCC) that classifies the business. - `timezone` (string, optional) — The business's time zone. - `phone` (list of string, optional) — Phone numbers for the business. - `emails` (list of string, optional) — Email addresses for the business. - `operatingSeasons` (list of enum, optional) — The seasons the business operates in. Values are case-insensitive on input and returned capitalized. - Allowed values: `Spring`, `Summer`, `Fall`, `Winter` - `addressDetails` (list of BusinessAddressCreate, optional) — The business's addresses. - `paymentMethods` (list of BusinessPaymentMethod, optional) — The bank accounts and cards attached to the business. - `customData` (map from string to any, optional) — Arbitrary key-value data you attach to the business. Payabli stores the applicant's answers to a boarding template's custom questions under the `templateAnswers` key. - `isForeignOwned` (boolean, optional) — Whether the business is foreign-owned. - `isTaxExempt` (boolean, optional) — Whether the business is tax-exempt. - `taxExemptClassification` (string, optional) — The business's tax-exempt classification, such as `501(c)(3)`. - `processingMetrics` (ProcessingMetrics, optional) — Expected Pay In processing profile for the business. - `payoutMetrics` (PayoutMetrics, optional) — Expected Pay Out profile for the business. - `license` (string, optional) — The business's license number. - `licenseState` (string, optional) — The state that issued the business's license. - `taxReference` (string, optional) — The business tax identifier, for example an EIN. - `parentReference` (string, optional) — The organization entrypoint the business belongs to. Omit to use the organization your credential belongs to. ## Response ### 201 Business created. - `success` (boolean, required) — Whether the request succeeded. - `message` (string, required, nullable) — A human-readable result message. - `traceId` (string, required, nullable) — The trace identifier for the request, useful for support. - `data` (BusinessCreatedResponse, required, nullable) — The created business. - `warnings` (list of BoardingWarning, required, nullable) — Non-blocking warnings. ## Errors ### 400 Bad Request Error Bad request / invalid data. - `isSuccess` (boolean, required) — Always `false` for error responses. - `responseText` (string, required) — Error text describing what went wrong. - `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). - `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context. ### 401 Unauthorized Error Unauthorized request. - `isSuccess` (boolean, required) — Always `false` for error responses. - `responseText` (string, required) — Error text describing what went wrong. - `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). - `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context. ### 409 Conflict Error The request conflicts with the current state of the resource. - `isSuccess` (boolean, required) — Always `false` for error responses. - `responseText` (string, required) — Error text describing what went wrong. - `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). - `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context. ### 500 Internal Server Error Internal server error. - `isSuccess` (boolean, required) — Always `false` for error responses. - `responseText` (string, required) — Error text describing what went wrong. - `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). - `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context. ## Types ### BusinessAddressCreate An address sent when creating a business. `country` is required. - `country` (string, required) — The two-character ISO country code. - `type` (enum, optional) — The address role. - Allowed values: `legal`, `billing`, `shipping`, `remittance`, `physical`, `mailing` - `location` (enum, optional) — The physical use of the address. Defaults to `other`. - Allowed values: `office`, `warehouse`, `retail`, `home`, `other` - `addressLine1` (string, optional) — The first line of the street address. - `addressLine2` (string, optional) — The second line of the street address. - `cityLocality` (string, optional) — The city or locality. - `stateProvince` (string, optional) — The state or province. - `postalCode` (string, optional) — The postal or ZIP code. - `floor` (string, optional) — The floor, if applicable. - `suiteApartNumber` (string, optional) — The suite or apartment number, if applicable. ### BusinessPaymentMethod A bank account or card attached to a business. - `type` (string, optional) — The payment method type, for example a bank account or card. - `accountOwner` (string, optional) — The name of the account owner. - `name` (string, optional) — An optional label for the payment method. - `financialInstitution` (string, optional) — The bank or financial institution that holds the account. - `ownerType` (string, optional) — Whether the owner is a business or an individual. - `accountType` (string, optional) — The account type, for example checking or savings. - `accountNumber` (string, optional) — The bank account number. - `routingNumber` (string, optional) — The bank routing number. - `cardNumber` (string, optional) — The card number, for card payment methods. - `expirationDate` (string, optional) — The card expiration date, for card payment methods. - `cvv` (string, optional) — The card verification value, for card payment methods. - `cardType` (string, optional) — The card type, for card payment methods. - `usage` (list of string, optional) — What the payment method is used for. - `isDefault` (boolean, optional) — Whether this is the owner's default payment method. At most one payment method per owner can set `isDefault` to `true`; sending two `true` values in one request fails validation. ### ProcessingMetrics Expected Pay In processing profile for the business. - `monthlyReceivablesVolume` (double, optional) — Expected monthly Pay In volume. - `averageReceivableSize` (double, optional) — Expected average transaction amount. - `largestReceivableSize` (double, optional) — Expected largest transaction amount. - `inboundPresentPercent` (integer, optional) — Percent of volume from card-present transactions. - `inboundOnlinePercent` (integer, optional) — Percent of volume from online transactions. - `inboundMotoPercent` (integer, optional) — Percent of volume from mail-order/telephone-order transactions. - `refundPolicy` (string, optional) — The business's refund policy. - `advancedDelivery` (boolean, optional) — Whether the business delivers goods or services before it's paid. - `percentAdvancedDelivery` (integer, optional) — Percent of sales delivered before payment. - `advancedDeliveryDays` (double, optional) — Average number of days between payment and delivery. - `numberOfTransactions` (integer, optional) — Expected number of transactions per month. ### PayoutMetrics Expected Pay Out profile for the business. - `monthlyPayablesVolume` (double, optional) — Expected monthly Pay Out volume. - `averagePayablesSize` (double, optional) — Expected average payout amount. - `largestPayablesSize` (double, optional) — Expected largest payout amount. - `numberOfTransactions` (integer, optional) — Expected number of payouts per month. ### BusinessCreatedResponse The reference and initial status of a newly created business. - `businessUuid` (string, required) — The business reference, used to read and manage the business. - `businessStatus` (string, required) — The business status. New businesses start in Draft. - `createdAt` (datetime, required) — When the business was created. - `_links` (BusinessLinks, required) — Hypermedia links for the business resource. ### BoardingWarning A non-blocking warning returned alongside a successful response. - `code` (string, optional) — A machine-readable warning code. - `message` (string, optional) — A human-readable description of the warning. ### PayabliErrorBodyResponseData Object with detailed error context. - `explanation` (string, optional) — Human-readable explanation of what happened. - `todoAction` (string, optional) — Suggested resolution. ### BusinessLinks Hypermedia links for a business resource. - `self` (string, optional) — Relative path to the business resource. ## Examples **Request** ```json { "legalName": "Rose Gardens LLC", "externalId": "rg-001", "legalStructure": "llc", "website": "https://example.com", "merchantCatCode": "5814", "phone": [ "3055551212" ], "emails": [ "ops@example.com" ], "paymentMethods": [ { "type": "bank_account", "name": "Operating account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "123456789", "routingNumber": "021000021", "usage": [ "deposits", "billing" ], "isDefault": true }, { "type": "bank_account", "name": "Payout account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "987654321", "routingNumber": "021000021", "usage": [ "payOutFunding" ], "isDefault": false } ], "taxReference": "477498993", "parentReference": "8cfec329267" } ``` **Response** ```json { "success": true, "message": "Business created successfully", "traceId": "0HNNKQIN7BJO1:00000015", "data": { "businessUuid": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "businessStatus": "Draft", "createdAt": "2026-08-10T19:15:47.6946557Z", "_links": { "self": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55" } } } ``` **SDK Code** ```python import requests url = "https://api-sandbox.payabli.com/api/v2/businesses" payload = { "legalName": "Rose Gardens LLC", "externalId": "rg-001", "legalStructure": "llc", "website": "https://example.com", "merchantCatCode": "5814", "phone": ["3055551212"], "emails": ["ops@example.com"], "paymentMethods": [ { "type": "bank_account", "name": "Operating account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "123456789", "routingNumber": "021000021", "usage": ["deposits", "billing"], "isDefault": True }, { "type": "bank_account", "name": "Payout account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "987654321", "routingNumber": "021000021", "usage": ["payOutFunding"], "isDefault": False } ], "taxReference": "477498993", "parentReference": "8cfec329267" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api-sandbox.payabli.com/api/v2/businesses'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"legalName":"Rose Gardens LLC","externalId":"rg-001","legalStructure":"llc","website":"https://example.com","merchantCatCode":"5814","phone":["3055551212"],"emails":["ops@example.com"],"paymentMethods":[{"type":"bank_account","name":"Operating account","financialInstitution":"Bank of Example","ownerType":"business","accountType":"checking","accountNumber":"123456789","routingNumber":"021000021","usage":["deposits","billing"],"isDefault":true},{"type":"bank_account","name":"Payout account","financialInstitution":"Bank of Example","ownerType":"business","accountType":"checking","accountNumber":"987654321","routingNumber":"021000021","usage":["payOutFunding"],"isDefault":false}],"taxReference":"477498993","parentReference":"8cfec329267"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/v2/businesses" payload := strings.NewReader("{\n \"legalName\": \"Rose Gardens LLC\",\n \"externalId\": \"rg-001\",\n \"legalStructure\": \"llc\",\n \"website\": \"https://example.com\",\n \"merchantCatCode\": \"5814\",\n \"phone\": [\n \"3055551212\"\n ],\n \"emails\": [\n \"ops@example.com\"\n ],\n \"paymentMethods\": [\n {\n \"type\": \"bank_account\",\n \"name\": \"Operating account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"123456789\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"deposits\",\n \"billing\"\n ],\n \"isDefault\": true\n },\n {\n \"type\": \"bank_account\",\n \"name\": \"Payout account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"987654321\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"payOutFunding\"\n ],\n \"isDefault\": false\n }\n ],\n \"taxReference\": \"477498993\",\n \"parentReference\": \"8cfec329267\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/v2/businesses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"legalName\": \"Rose Gardens LLC\",\n \"externalId\": \"rg-001\",\n \"legalStructure\": \"llc\",\n \"website\": \"https://example.com\",\n \"merchantCatCode\": \"5814\",\n \"phone\": [\n \"3055551212\"\n ],\n \"emails\": [\n \"ops@example.com\"\n ],\n \"paymentMethods\": [\n {\n \"type\": \"bank_account\",\n \"name\": \"Operating account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"123456789\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"deposits\",\n \"billing\"\n ],\n \"isDefault\": true\n },\n {\n \"type\": \"bank_account\",\n \"name\": \"Payout account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"987654321\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"payOutFunding\"\n ],\n \"isDefault\": false\n }\n ],\n \"taxReference\": \"477498993\",\n \"parentReference\": \"8cfec329267\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/v2/businesses") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"legalName\": \"Rose Gardens LLC\",\n \"externalId\": \"rg-001\",\n \"legalStructure\": \"llc\",\n \"website\": \"https://example.com\",\n \"merchantCatCode\": \"5814\",\n \"phone\": [\n \"3055551212\"\n ],\n \"emails\": [\n \"ops@example.com\"\n ],\n \"paymentMethods\": [\n {\n \"type\": \"bank_account\",\n \"name\": \"Operating account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"123456789\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"deposits\",\n \"billing\"\n ],\n \"isDefault\": true\n },\n {\n \"type\": \"bank_account\",\n \"name\": \"Payout account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"987654321\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"payOutFunding\"\n ],\n \"isDefault\": false\n }\n ],\n \"taxReference\": \"477498993\",\n \"parentReference\": \"8cfec329267\"\n}") .asString(); ``` ```php request('POST', 'https://api-sandbox.payabli.com/api/v2/businesses', [ 'body' => '{ "legalName": "Rose Gardens LLC", "externalId": "rg-001", "legalStructure": "llc", "website": "https://example.com", "merchantCatCode": "5814", "phone": [ "3055551212" ], "emails": [ "ops@example.com" ], "paymentMethods": [ { "type": "bank_account", "name": "Operating account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "123456789", "routingNumber": "021000021", "usage": [ "deposits", "billing" ], "isDefault": true }, { "type": "bank_account", "name": "Payout account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "987654321", "routingNumber": "021000021", "usage": [ "payOutFunding" ], "isDefault": false } ], "taxReference": "477498993", "parentReference": "8cfec329267" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/v2/businesses"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"legalName\": \"Rose Gardens LLC\",\n \"externalId\": \"rg-001\",\n \"legalStructure\": \"llc\",\n \"website\": \"https://example.com\",\n \"merchantCatCode\": \"5814\",\n \"phone\": [\n \"3055551212\"\n ],\n \"emails\": [\n \"ops@example.com\"\n ],\n \"paymentMethods\": [\n {\n \"type\": \"bank_account\",\n \"name\": \"Operating account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"123456789\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"deposits\",\n \"billing\"\n ],\n \"isDefault\": true\n },\n {\n \"type\": \"bank_account\",\n \"name\": \"Payout account\",\n \"financialInstitution\": \"Bank of Example\",\n \"ownerType\": \"business\",\n \"accountType\": \"checking\",\n \"accountNumber\": \"987654321\",\n \"routingNumber\": \"021000021\",\n \"usage\": [\n \"payOutFunding\"\n ],\n \"isDefault\": false\n }\n ],\n \"taxReference\": \"477498993\",\n \"parentReference\": \"8cfec329267\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "legalName": "Rose Gardens LLC", "externalId": "rg-001", "legalStructure": "llc", "website": "https://example.com", "merchantCatCode": "5814", "phone": ["3055551212"], "emails": ["ops@example.com"], "paymentMethods": [ [ "type": "bank_account", "name": "Operating account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "123456789", "routingNumber": "021000021", "usage": ["deposits", "billing"], "isDefault": true ], [ "type": "bank_account", "name": "Payout account", "financialInstitution": "Bank of Example", "ownerType": "business", "accountType": "checking", "accountNumber": "987654321", "routingNumber": "021000021", "usage": ["payOutFunding"], "isDefault": false ] ], "taxReference": "477498993", "parentReference": "8cfec329267" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/businesses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```