> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta-docs.payabli.com/api-reference/organization/create-organization/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server. # Create organization POST https://api-sandbox.payabli.com/api/Organization Content-Type: application/json Creates an organization under a parent organization. This is also referred to as a suborganization. Reference: https://beta-docs.payabli.com/api-reference/organization/create-organization ## Authentication - `requestToken` header (required) — API Key authentication via header ## Servers - `https://api-sandbox.payabli.com/api` (Sandbox, default) - `https://api.payabli.com/api` (Production) ## Request ### Headers - `idempotencyKey` (string, optional) — A unique ID you can include to prevent duplicating objects or transactions if a request is sent more than once. This key is not generated in Payabli, you must generate it yourself. ### Body (application/json) This endpoint expects an object. - `orgName` (string, required) — The name of the organization. - `orgType` (integer, required) — The organization type. Currently, this must be `0`. - `replyToEmail` (string, required) — Email address for organization-level communications, such as messages about why an application was declined. This is required by commerce laws in the US. - `services` (list of ServiceCost, optional) - `billingInfo` (Instrument, optional) - `contacts` (list of Contacts, optional) — List of contacts. - `hasBilling` (boolean, optional) - `hasResidual` (boolean, optional) - `orgAddress` (string, optional) — The organization's address. - `orgCity` (string, optional) — The organization's city. - `orgCountry` (string, optional) — The organization's country. - `orgEntryName` (string, optional) — The entryname for the org, in string format. If you leave this blank, Payabli uses the DBA name. - `orgId` (string, optional) — An alternate ID for the organization, in string format. This can be your internal identifier for an org, and is typically a name, like "My Suborganization". - `orgLogo` (FileContent, optional) — Contains details about a file. See See [fileObject Object Model](/api-reference/schemas/filecontent) for a complete reference. Max upload size is 30 MB. - `orgParentId` (long, optional) — The ID of the org's parent organization. - `orgState` (string, optional) — The organization's state. - `orgTimezone` (integer, optional) — The org's timezone, in UTC offset. For example, -5 is Eastern time. - `orgWebsite` (string, optional) — The organization's website. - `orgZip` (string, optional) — The organization's ZIP code. ## Response ### 200 Success. - `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure. - `responseData` (Responsedatanonobject, optional) — Returns the organization ID. - `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'. ## Errors ### 400 Bad Request Error Bad request/ invalid data - `any` ### 401 Unauthorized Error Unauthorized request. - `any` ### 500 Internal Server Error Internal API Error - `any` ### 503 Service Unavailable Error Database connection error - `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure. - `responseData` (map from string to any, optional) — The object containing the response data. - `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'. ## Types ### ServiceCost - `description` (string, optional) - `enabled` (boolean, optional) — Toggles whether the section or element is enabled. - `monthlyCost` (double, optional) - `name` (string, optional) - `reseller` (boolean, optional) - `setupCost` (double, optional) - `txCost` (double, optional) - `txPercentCost` (double, optional) ### Instrument - `achAccount` (string, required) — Bank account number. - `achRouting` (string, required) — ABA/routing number of Bank account. - `billingAddress` (string, optional) — Billing address. - `billingCity` (string, optional) — Billing city. - `billingCountry` (string, optional) — Billing address country. - `billingState` (string, optional) — Billing state. Must be 2-letter state code for address in US. - `billingZip` (string, optional) — Billing address ZIP code. ### Contacts - `contactEmail` (string, optional) — Contact email address. - `contactName` (string, optional) — Contact name. - `contactPhone` (string, optional) — Contact phone number. - `contactTitle` (string, optional) — Contact title. ### FileContent Contains details about a file. See See [fileObject Object Model](/api-reference/schemas/filecontent) for a complete reference. Max upload size is 30 MB. - `fContent` (string, optional) — Content of file, Base64-encoded Ignored if furl is specified. Max upload size is 30 MB. - `filename` (string, optional) — The name of the attached file. - `ftype` (enum, optional) — The MIME type of the file (if content is provided) - Allowed values: `pdf`, `doc`, `docx`, `jpg`, `jpeg`, `png`, `gif`, `txt` - `furl` (string, optional) — Optional url provided to show or download the file remotely ### Responsedatanonobject The response data. ## Examples **Request** ```json { "orgName": "Pilgrim Planner", "orgType": 0, "replyToEmail": "email@example.com", "billingInfo": { "achAccount": "123123123", "achRouting": "123123123", "billingAddress": "123 Walnut Street", "billingCity": "Johnson City", "billingCountry": "US", "billingState": "TN", "billingZip": "37615" }, "contacts": [ { "contactEmail": "herman@hermanscoatings.com", "contactName": "Herman Martinez", "contactPhone": "3055550000", "contactTitle": "Owner" } ], "hasBilling": true, "hasResidual": true, "orgAddress": "123 Walnut Street", "orgCity": "Johnson City", "orgCountry": "US", "orgEntryName": "pilgrim-planner", "orgId": "123", "orgLogo": { "fContent": "TXkgdGVzdCBmaWxlHJ==...", "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" }, "orgParentId": 236, "orgState": "TN", "orgTimezone": -5, "orgWebsite": "www.pilgrimageplanner.com", "orgZip": "37615" } ``` **Response** ```json { "isSuccess": true, "responseData": 245, "responseText": "Success" } ``` **SDK Code** ```python General success response for certain organization operations import requests url = "https://api-sandbox.payabli.com/api/Organization" payload = { "orgName": "Pilgrim Planner", "orgType": 0, "replyToEmail": "email@example.com", "billingInfo": { "achAccount": "123123123", "achRouting": "123123123", "billingAddress": "123 Walnut Street", "billingCity": "Johnson City", "billingCountry": "US", "billingState": "TN", "billingZip": "37615" }, "contacts": [ { "contactEmail": "herman@hermanscoatings.com", "contactName": "Herman Martinez", "contactPhone": "3055550000", "contactTitle": "Owner" } ], "hasBilling": True, "hasResidual": True, "orgAddress": "123 Walnut Street", "orgCity": "Johnson City", "orgCountry": "US", "orgEntryName": "pilgrim-planner", "orgId": "123", "orgLogo": { "fContent": "TXkgdGVzdCBmaWxlHJ==...", "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" }, "orgParentId": 236, "orgState": "TN", "orgTimezone": -5, "orgWebsite": "www.pilgrimageplanner.com", "orgZip": "37615" } headers = { "idempotencyKey": "6B29FC40-CA47-1067-B31D-00DD010662DA", "requestToken": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript General success response for certain organization operations const url = 'https://api-sandbox.payabli.com/api/Organization'; const options = { method: 'POST', headers: { idempotencyKey: '6B29FC40-CA47-1067-B31D-00DD010662DA', requestToken: '', 'Content-Type': 'application/json' }, body: '{"orgName":"Pilgrim Planner","orgType":0,"replyToEmail":"email@example.com","billingInfo":{"achAccount":"123123123","achRouting":"123123123","billingAddress":"123 Walnut Street","billingCity":"Johnson City","billingCountry":"US","billingState":"TN","billingZip":"37615"},"contacts":[{"contactEmail":"herman@hermanscoatings.com","contactName":"Herman Martinez","contactPhone":"3055550000","contactTitle":"Owner"}],"hasBilling":true,"hasResidual":true,"orgAddress":"123 Walnut Street","orgCity":"Johnson City","orgCountry":"US","orgEntryName":"pilgrim-planner","orgId":"123","orgLogo":{"fContent":"TXkgdGVzdCBmaWxlHJ==...","filename":"my-doc.pdf","ftype":"pdf","furl":"https://mysite.com/my-doc.pdf"},"orgParentId":236,"orgState":"TN","orgTimezone":-5,"orgWebsite":"www.pilgrimageplanner.com","orgZip":"37615"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go General success response for certain organization operations package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/Organization" payload := strings.NewReader("{\n \"orgName\": \"Pilgrim Planner\",\n \"orgType\": 0,\n \"replyToEmail\": \"email@example.com\",\n \"billingInfo\": {\n \"achAccount\": \"123123123\",\n \"achRouting\": \"123123123\",\n \"billingAddress\": \"123 Walnut Street\",\n \"billingCity\": \"Johnson City\",\n \"billingCountry\": \"US\",\n \"billingState\": \"TN\",\n \"billingZip\": \"37615\"\n },\n \"contacts\": [\n {\n \"contactEmail\": \"herman@hermanscoatings.com\",\n \"contactName\": \"Herman Martinez\",\n \"contactPhone\": \"3055550000\",\n \"contactTitle\": \"Owner\"\n }\n ],\n \"hasBilling\": true,\n \"hasResidual\": true,\n \"orgAddress\": \"123 Walnut Street\",\n \"orgCity\": \"Johnson City\",\n \"orgCountry\": \"US\",\n \"orgEntryName\": \"pilgrim-planner\",\n \"orgId\": \"123\",\n \"orgLogo\": {\n \"fContent\": \"TXkgdGVzdCBmaWxlHJ==...\",\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n },\n \"orgParentId\": 236,\n \"orgState\": \"TN\",\n \"orgTimezone\": -5,\n \"orgWebsite\": \"www.pilgrimageplanner.com\",\n \"orgZip\": \"37615\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("idempotencyKey", "6B29FC40-CA47-1067-B31D-00DD010662DA") req.Header.Add("requestToken", "") 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 General success response for certain organization operations require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/Organization") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["idempotencyKey"] = '6B29FC40-CA47-1067-B31D-00DD010662DA' request["requestToken"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"orgName\": \"Pilgrim Planner\",\n \"orgType\": 0,\n \"replyToEmail\": \"email@example.com\",\n \"billingInfo\": {\n \"achAccount\": \"123123123\",\n \"achRouting\": \"123123123\",\n \"billingAddress\": \"123 Walnut Street\",\n \"billingCity\": \"Johnson City\",\n \"billingCountry\": \"US\",\n \"billingState\": \"TN\",\n \"billingZip\": \"37615\"\n },\n \"contacts\": [\n {\n \"contactEmail\": \"herman@hermanscoatings.com\",\n \"contactName\": \"Herman Martinez\",\n \"contactPhone\": \"3055550000\",\n \"contactTitle\": \"Owner\"\n }\n ],\n \"hasBilling\": true,\n \"hasResidual\": true,\n \"orgAddress\": \"123 Walnut Street\",\n \"orgCity\": \"Johnson City\",\n \"orgCountry\": \"US\",\n \"orgEntryName\": \"pilgrim-planner\",\n \"orgId\": \"123\",\n \"orgLogo\": {\n \"fContent\": \"TXkgdGVzdCBmaWxlHJ==...\",\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n },\n \"orgParentId\": 236,\n \"orgState\": \"TN\",\n \"orgTimezone\": -5,\n \"orgWebsite\": \"www.pilgrimageplanner.com\",\n \"orgZip\": \"37615\"\n}" response = http.request(request) puts response.read_body ``` ```java General success response for certain organization operations import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/Organization") .header("idempotencyKey", "6B29FC40-CA47-1067-B31D-00DD010662DA") .header("requestToken", "") .header("Content-Type", "application/json") .body("{\n \"orgName\": \"Pilgrim Planner\",\n \"orgType\": 0,\n \"replyToEmail\": \"email@example.com\",\n \"billingInfo\": {\n \"achAccount\": \"123123123\",\n \"achRouting\": \"123123123\",\n \"billingAddress\": \"123 Walnut Street\",\n \"billingCity\": \"Johnson City\",\n \"billingCountry\": \"US\",\n \"billingState\": \"TN\",\n \"billingZip\": \"37615\"\n },\n \"contacts\": [\n {\n \"contactEmail\": \"herman@hermanscoatings.com\",\n \"contactName\": \"Herman Martinez\",\n \"contactPhone\": \"3055550000\",\n \"contactTitle\": \"Owner\"\n }\n ],\n \"hasBilling\": true,\n \"hasResidual\": true,\n \"orgAddress\": \"123 Walnut Street\",\n \"orgCity\": \"Johnson City\",\n \"orgCountry\": \"US\",\n \"orgEntryName\": \"pilgrim-planner\",\n \"orgId\": \"123\",\n \"orgLogo\": {\n \"fContent\": \"TXkgdGVzdCBmaWxlHJ==...\",\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n },\n \"orgParentId\": 236,\n \"orgState\": \"TN\",\n \"orgTimezone\": -5,\n \"orgWebsite\": \"www.pilgrimageplanner.com\",\n \"orgZip\": \"37615\"\n}") .asString(); ``` ```php General success response for certain organization operations request('POST', 'https://api-sandbox.payabli.com/api/Organization', [ 'body' => '{ "orgName": "Pilgrim Planner", "orgType": 0, "replyToEmail": "email@example.com", "billingInfo": { "achAccount": "123123123", "achRouting": "123123123", "billingAddress": "123 Walnut Street", "billingCity": "Johnson City", "billingCountry": "US", "billingState": "TN", "billingZip": "37615" }, "contacts": [ { "contactEmail": "herman@hermanscoatings.com", "contactName": "Herman Martinez", "contactPhone": "3055550000", "contactTitle": "Owner" } ], "hasBilling": true, "hasResidual": true, "orgAddress": "123 Walnut Street", "orgCity": "Johnson City", "orgCountry": "US", "orgEntryName": "pilgrim-planner", "orgId": "123", "orgLogo": { "fContent": "TXkgdGVzdCBmaWxlHJ==...", "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" }, "orgParentId": 236, "orgState": "TN", "orgTimezone": -5, "orgWebsite": "www.pilgrimageplanner.com", "orgZip": "37615" }', 'headers' => [ 'Content-Type' => 'application/json', 'idempotencyKey' => '6B29FC40-CA47-1067-B31D-00DD010662DA', 'requestToken' => '', ], ]); echo $response->getBody(); ``` ```csharp General success response for certain organization operations using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/Organization"); var request = new RestRequest(Method.POST); request.AddHeader("idempotencyKey", "6B29FC40-CA47-1067-B31D-00DD010662DA"); request.AddHeader("requestToken", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"orgName\": \"Pilgrim Planner\",\n \"orgType\": 0,\n \"replyToEmail\": \"email@example.com\",\n \"billingInfo\": {\n \"achAccount\": \"123123123\",\n \"achRouting\": \"123123123\",\n \"billingAddress\": \"123 Walnut Street\",\n \"billingCity\": \"Johnson City\",\n \"billingCountry\": \"US\",\n \"billingState\": \"TN\",\n \"billingZip\": \"37615\"\n },\n \"contacts\": [\n {\n \"contactEmail\": \"herman@hermanscoatings.com\",\n \"contactName\": \"Herman Martinez\",\n \"contactPhone\": \"3055550000\",\n \"contactTitle\": \"Owner\"\n }\n ],\n \"hasBilling\": true,\n \"hasResidual\": true,\n \"orgAddress\": \"123 Walnut Street\",\n \"orgCity\": \"Johnson City\",\n \"orgCountry\": \"US\",\n \"orgEntryName\": \"pilgrim-planner\",\n \"orgId\": \"123\",\n \"orgLogo\": {\n \"fContent\": \"TXkgdGVzdCBmaWxlHJ==...\",\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n },\n \"orgParentId\": 236,\n \"orgState\": \"TN\",\n \"orgTimezone\": -5,\n \"orgWebsite\": \"www.pilgrimageplanner.com\",\n \"orgZip\": \"37615\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift General success response for certain organization operations import Foundation let headers = [ "idempotencyKey": "6B29FC40-CA47-1067-B31D-00DD010662DA", "requestToken": "", "Content-Type": "application/json" ] let parameters = [ "orgName": "Pilgrim Planner", "orgType": 0, "replyToEmail": "email@example.com", "billingInfo": [ "achAccount": "123123123", "achRouting": "123123123", "billingAddress": "123 Walnut Street", "billingCity": "Johnson City", "billingCountry": "US", "billingState": "TN", "billingZip": "37615" ], "contacts": [ [ "contactEmail": "herman@hermanscoatings.com", "contactName": "Herman Martinez", "contactPhone": "3055550000", "contactTitle": "Owner" ] ], "hasBilling": true, "hasResidual": true, "orgAddress": "123 Walnut Street", "orgCity": "Johnson City", "orgCountry": "US", "orgEntryName": "pilgrim-planner", "orgId": "123", "orgLogo": [ "fContent": "TXkgdGVzdCBmaWxlHJ==...", "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" ], "orgParentId": 236, "orgState": "TN", "orgTimezone": -5, "orgWebsite": "www.pilgrimageplanner.com", "orgZip": "37615" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Organization")! 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() ``` > If you're a software company, you're a payments company™