> 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 # Link a person to a business POST https://api-sandbox.payabli.com/api/v2/businesses/{businessReference}/people Content-Type: application/json Links an existing person to a business, setting the relationship's role, ownership, primary-controller flag, contact fields, and addresses. Reference: https://docs.payabli.com/developers/api-reference/businesses/link-a-person-to-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 ### Path parameters - `businessReference` (string, required) — The business reference (`businessUuid`). ### Body (application/json) This endpoint expects a LinkBusinessPersonRequest. - `personReference` (string, required) — The reference of the person to link. - `personType` (enum, optional) — The person's role on the business. - Allowed values: `Owner`, `Director`, `Contact`, `Signer`, `AuthorizedUser`, `Employee` - `ownershipPercentage` (double, optional) — The person's ownership percentage (0 to 100). Required when `personType` is `Owner`, and must be omitted for every other role. If the combined ownership would exceed 100%, the link is rejected with a `400`. - `isPrimaryController` (boolean, optional) — Whether the person is the business's primary controller. - `isSigner` (boolean, optional) — Whether the person signs the business's boarding applications. Only an owner can be the signer. Setting `isSigner` to `true` on a person with another `personType` returns `400` with the message `Only an owner can be the signer.` A business has one signer. Setting `isSigner` to `true` on one person removes it from every other person linked to the business. - `title` (string, optional) — The person's job title at this business, such as `CEO` or `Managing Member`, from 1 to 100 characters. A person linked to more than one business can have a different title at each one. A blank value is treated as not sent. - `primaryEmail` (string, optional) — The relationship's primary email address. - `secondaryEmail` (string, optional) — The relationship's secondary email address. - `primaryPhoneNumber` (string, optional) — The relationship's primary phone number. - `secondaryPhoneNumber` (string, optional) — The relationship's secondary phone number. - `billingAddress` (PersonAddressRequest, optional) — The billing address for the relationship. - `mailingAddress` (PersonAddressRequest, optional) — The mailing address for the relationship. ## Response ### 201 The person was linked to the business. - `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` (BusinessPersonLink, required, nullable) — The business-person link. ## 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. ### 404 Not Found Error The requested resource wasn't found. - `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 ### PersonAddressRequest An address included in a person request. - `addressLine1` (string, optional) — The first line of the street address. - `addressLine2` (string, optional) — The second line of the street address (suite, unit, and so on). - `cityLocality` (string, optional) — The city or locality. - `stateProvince` (string, optional) — The two-letter state or province code. - `postalCode` (string, optional) — The postal or ZIP code. - `country` (string, optional) — The two-letter ISO 3166-1 alpha-2 country code. - `type` (enum, optional) — The role the address plays for the person. - Allowed values: `legal`, `billing`, `shipping`, `remittance`, `mailing`, `physical`, `residential` ### BusinessPersonLink A person's link to a business, with the relationship's role, ownership, and relationship-scoped contact details. - `businessReference` (string, required) — The reference of the linked business. - `personReference` (string, required) — The reference of the linked person. - `personType` (string, required) — The person's role on the business, returned in lowercase (for example `owner`). - `beneficialOwner` (boolean, required) — Whether the person qualifies as a beneficial owner. Derived by Payabli. - `isPrimaryController` (boolean, required) — Whether the person is the business's primary controller. - `isSigner` (boolean, required) — Whether the person signs the business's boarding applications. - `title` (string, required, nullable) — The person's job title at this business. - `primaryEmail` (string, required, nullable) — The relationship's primary email address. - `secondaryEmail` (string, required, nullable) — The relationship's secondary email address. - `primaryPhoneNumber` (string, required, nullable) — The relationship's primary phone number. - `secondaryPhoneNumber` (string, required, nullable) — The relationship's secondary phone number. - `createdAt` (datetime, required) — When the link was created. - `updatedAt` (datetime, required) — When the link was last updated. - `_links` (BusinessPersonLinks, required) — Hypermedia links for the link resource. - `ownershipPercentage` (double, optional, nullable) — The person's ownership percentage (0 to 100). Present for owners. - `billingAddressUuid` (string, optional, nullable) — Reference to the stored billing address for the relationship. Present when a billing address was set. - `mailingAddressUuid` (string, optional, nullable) — Reference to the stored mailing address for the relationship. Present when a mailing address was set. ### PayabliErrorBodyResponseData Object with detailed error context. - `explanation` (string, optional) — Human-readable explanation of what happened. - `todoAction` (string, optional) — Suggested resolution. ### BusinessPersonLinks Hypermedia links for a business-person link. - `self` (string, optional) — Relative path to the business-person link. - `business` (string, optional) — Relative path to the linked business. - `person` (string, optional) — Relative path to the linked person. ## Examples **Request** ```json { "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "personType": "Owner", "ownershipPercentage": 100, "isPrimaryController": true, "isSigner": true, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "billingAddress": { "addressLine1": "123 Main Street", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "billing" }, "mailingAddress": { "addressLine1": "456 Oak Avenue", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33102", "country": "US", "type": "mailing" } } ``` **Response** ```json { "success": true, "message": "Person linked to business successfully", "traceId": "0HNOIMDG0IS4U:00000147", "data": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "personType": "owner", "beneficialOwner": true, "isPrimaryController": true, "isSigner": true, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "createdAt": "2026-08-14T17:24:31.3877241Z", "updatedAt": "2026-08-14T17:24:31.3877241Z", "_links": { "self": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people/01a0014d-ce1a-7110-9bac-c4c59647a88d", "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55", "person": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d" }, "ownershipPercentage": 100, "billingAddressUuid": "019fed1a-6e41-7194-84c8-98ae0219799a", "mailingAddressUuid": "019fed1a-6e43-7768-b3b4-607c374f7730" } } ``` **SDK Code** ```python import requests url = "https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people" payload = { "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "personType": "Owner", "ownershipPercentage": 100, "isPrimaryController": True, "isSigner": True, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "billingAddress": { "addressLine1": "123 Main Street", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "billing" }, "mailingAddress": { "addressLine1": "456 Oak Avenue", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33102", "country": "US", "type": "mailing" } } 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/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"personReference":"01a0014d-ce1a-7110-9bac-c4c59647a88d","personType":"Owner","ownershipPercentage":100,"isPrimaryController":true,"isSigner":true,"title":"CEO","primaryEmail":"contact@example.com","secondaryEmail":"contact.alt@example.net","primaryPhoneNumber":"3055551212","secondaryPhoneNumber":"3055559876","billingAddress":{"addressLine1":"123 Main Street","cityLocality":"Miami","stateProvince":"FL","postalCode":"33101","country":"US","type":"billing"},"mailingAddress":{"addressLine1":"456 Oak Avenue","cityLocality":"Miami","stateProvince":"FL","postalCode":"33102","country":"US","type":"mailing"}}' }; 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/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people" payload := strings.NewReader("{\n \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 100,\n \"isPrimaryController\": true,\n \"isSigner\": true,\n \"title\": \"CEO\",\n \"primaryEmail\": \"contact@example.com\",\n \"secondaryEmail\": \"contact.alt@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"billingAddress\": {\n \"addressLine1\": \"123 Main Street\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"billing\"\n },\n \"mailingAddress\": {\n \"addressLine1\": \"456 Oak Avenue\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33102\",\n \"country\": \"US\",\n \"type\": \"mailing\"\n }\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/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people") 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 \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 100,\n \"isPrimaryController\": true,\n \"isSigner\": true,\n \"title\": \"CEO\",\n \"primaryEmail\": \"contact@example.com\",\n \"secondaryEmail\": \"contact.alt@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"billingAddress\": {\n \"addressLine1\": \"123 Main Street\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"billing\"\n },\n \"mailingAddress\": {\n \"addressLine1\": \"456 Oak Avenue\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33102\",\n \"country\": \"US\",\n \"type\": \"mailing\"\n }\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/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 100,\n \"isPrimaryController\": true,\n \"isSigner\": true,\n \"title\": \"CEO\",\n \"primaryEmail\": \"contact@example.com\",\n \"secondaryEmail\": \"contact.alt@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"billingAddress\": {\n \"addressLine1\": \"123 Main Street\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"billing\"\n },\n \"mailingAddress\": {\n \"addressLine1\": \"456 Oak Avenue\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33102\",\n \"country\": \"US\",\n \"type\": \"mailing\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people', [ 'body' => '{ "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "personType": "Owner", "ownershipPercentage": 100, "isPrimaryController": true, "isSigner": true, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "billingAddress": { "addressLine1": "123 Main Street", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "billing" }, "mailingAddress": { "addressLine1": "456 Oak Avenue", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33102", "country": "US", "type": "mailing" } }', '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/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 100,\n \"isPrimaryController\": true,\n \"isSigner\": true,\n \"title\": \"CEO\",\n \"primaryEmail\": \"contact@example.com\",\n \"secondaryEmail\": \"contact.alt@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"billingAddress\": {\n \"addressLine1\": \"123 Main Street\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"billing\"\n },\n \"mailingAddress\": {\n \"addressLine1\": \"456 Oak Avenue\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33102\",\n \"country\": \"US\",\n \"type\": \"mailing\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "personType": "Owner", "ownershipPercentage": 100, "isPrimaryController": true, "isSigner": true, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "billingAddress": [ "addressLine1": "123 Main Street", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "billing" ], "mailingAddress": [ "addressLine1": "456 Oak Avenue", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33102", "country": "US", "type": "mailing" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55/people")! 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() ```