> 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 person POST https://api-sandbox.payabli.com/api/v2/people Content-Type: application/json Creates a person, an individual associated with a business such as an owner, director, or signer. Include a `businessRelationship` object to link the person to a business on create; the business reference, role (`personType`), and `ownershipPercentage` go inside that object. A person's job `title` and whether they're the signer (`isSigner`) also belong to the business link, so send them inside `businessRelationship`. A top-level `title` returns a `400` with the message `title moved into the businessRelationship object; send them there instead of at the top level.` Reference: https://docs.payabli.com/developers/api-reference/people/create-a-person ## 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 CreatePersonRequest. - `firstName` (string, required) — The person's first name. - `lastName` (string, required) — The person's last name. - `middleName` (string, optional) — The person's middle name. - `primaryEmail` (string, optional) — The person's primary email address. - `secondaryEmail` (string, optional) — The person's secondary email address. - `primaryPhoneNumber` (string, optional) — The person's primary phone number. - `secondaryPhoneNumber` (string, optional) — The person's secondary phone number. - `dateOfBirth` (string, optional) — The person's date of birth (`YYYY-MM-DD`). - `ssn` (string, optional) — The person's US Social Security Number, in `XXX-XX-XXXX` or `XXXXXXXXX` format. Applies when `nationality` is `US`, and needed to validate a US owner. Create doesn't enforce it. For any other nationality, send `nationalIdNumber` and `nationalIdIssuer` instead. - `nationality` (string, optional) — The person's nationality, as a two-letter ISO 3166-1 alpha-2 country code. Needed to validate an owner, but create doesn't enforce it. Nationality selects which identity number applies. `US` uses `ssn`, and any other value uses `nationalIdNumber` and `nationalIdIssuer`. - `nationalIdNumber` (string, optional) — The person's national identification number, for an individual whose `nationality` is not `US`. Send it with `nationalIdIssuer` when `nationality` is non-US. Create doesn't enforce it. - `nationalIdIssuer` (string, optional) — The authority that issued the national ID, for example the two-letter country code. Send it with `nationalIdNumber` when `nationality` is non-US. Create doesn't enforce it. - `driversLicenseNumber` (string, optional) — The person's driver's license number. - `driversLicenseState` (string, optional) — The two-letter state code for the driver's license. - `externalId` (string, optional) — Your own identifier for the person. - `customData` (map from string to any, optional) — Arbitrary key-value data you attach to the person. Payabli stores an owner's answers to a boarding template's custom questions under the `templateAnswers` key. - `addresses` (list of PersonAddressRequest, optional) — Postal addresses associated with the person. - `identificationDocuments` (list of IdentificationDocumentRequest, optional) — Government-issued identification documents for the person. - `businessRelationship` (BusinessRelationshipRequest, optional) — Links the person to a business as you create them. The link's role, ownership, primary-controller flag, contact fields, and addresses go here. These relationship contact fields are separate from the person's own top-level contact fields above. ## Response ### 201 Person 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` (PersonDetailResponse, required, nullable) — The person detail. - `warnings` (list of BoardingWarning, required, nullable) — Non-blocking warnings, such as a business link that didn't complete. ## 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. ### 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` ### IdentificationDocumentRequest A government-issued identification document included in a person request. - `type` (string, optional) — The document type, for example `drivers_license`, `passport`, or `state_id`. - `number` (string, optional) — The document number. - `issuingState` (string, optional) — The two-letter issuing state code. - `issuingCountry` (string, optional) — The two-letter ISO 3166-1 alpha-2 issuing country code. - `expirationDate` (string, optional) — The document expiration date. ### BusinessRelationshipRequest Links the person to a business as part of a person-create request. The contact fields here are scoped to the business-person relationship and are distinct from the person's own top-level `primaryEmail`, `primaryPhoneNumber`, and so on. - `businessReference` (string, required) — The reference of the business to link the person to. - `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 linking the owner would push the business over 100% total ownership, the person is still created but the link doesn't complete. The response has `success` set to `false`, omits `businessRelationship` from the person, and returns a `LINK_OWNERSHIP_EXCEEDED` entry in `warnings`. - `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. ### PersonDetailResponse The full detail of a person. Sensitive fields are masked unless read from the unmasked endpoint. - `personReference` (string, required) — The person reference. - `firstName` (string, required, nullable) — The person's first name. - `lastName` (string, required, nullable) — The person's last name. - `verificationStatus` (string, required) — The person's identity verification status, for example `not_started`. - `createdAt` (datetime, required) — When the person was created. - `lastUpdated` (datetime, required) — When the person was last updated. - `_links` (PersonLinks, required) — Hypermedia links for the person resource. - `externalId` (string, optional, nullable) — Your own identifier for the person. - `middleName` (string, optional, nullable) — The person's middle name. - `primaryEmail` (string, optional, nullable) — The person's primary email address. - `secondaryEmail` (string, optional, nullable) — The person's secondary email address. - `primaryPhoneNumber` (string, optional, nullable) — The person's primary phone number. - `secondaryPhoneNumber` (string, optional, nullable) — The person's secondary phone number. - `dateOfBirth` (string, optional, nullable) — The person's date of birth. Masked on standard reads (for example `****-**-14`); read the unmasked endpoint for the raw value. - `ssn` (string, optional, nullable) — The person's US Social Security Number. Populated when `nationality` is `US`, otherwise null. Masked on standard reads (for example `***-**-9021`); read the unmasked endpoint for the raw value. - `nationality` (string, optional, nullable) — The person's nationality, as a two-letter ISO 3166-1 alpha-2 country code. Not masked. When `US`, `ssn` is populated and the national ID fields are null; for any other value, `nationalIdNumber` and `nationalIdIssuer` are populated and `ssn` is null. - `nationalIdNumber` (string, optional, nullable) — The person's national identification number. Populated when `nationality` is not `US`, otherwise null. Masked on standard reads; read the unmasked endpoint for the raw value. - `nationalIdIssuer` (string, optional, nullable) — The authority that issued the national ID, for example the two-letter country code. Populated when `nationality` is not `US`, otherwise null. - `driversLicenseNumber` (string, optional, nullable) — The person's driver's license number. Masked on standard reads (for example `D1***567`); read the unmasked endpoint for the raw value. - `driversLicenseState` (string, optional, nullable) — The two-letter state code for the driver's license. - `customData` (map from string to any, optional, nullable) — Arbitrary key-value data attached to the person. When present, `templateAnswers` holds this owner's answers to a boarding template's person-scoped custom questions, meaning questions whose field path starts with `person.`, such as `person.backgroundCheck`. Payabli saves them on each owner. It's an object keyed by field path, and each answer is a string. A multi-select answer is one comma-separated string. Payabli saves the answers when an application is submitted through the hosted boarding application. Submitting an application with the API (`POST /v2/requests/{requestsReference}/submit`) doesn't save them. Only answers to custom questions are saved, and blank answers, standard-field answers, and document uploads aren't. A later hosted submit replaces the answer to the same question and keeps every other answer, including answers from other applications. Leaving a question blank on a later submit doesn't remove the stored answer. - `addresses` (list of PersonAddressResponse, optional, nullable) — Postal addresses associated with the person. - `identificationDocuments` (list of IdentificationDocumentResponse, optional, nullable) — Government-issued identification documents for the person. - `businessRelationship` (BusinessRelationshipResponse, optional, nullable) — The business link created with the person, present when the person was created with a `businessRelationship`. Null on a standalone person read, since the relationship is scoped to the business rather than the shared person. ### 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. ### PersonLinks Hypermedia links for a person resource. - `self` (string, optional) — Relative path to the person resource. - `business` (string, optional) — Relative path to the linked business, present when the person is linked to a business. ### PersonAddressResponse An address in a person response. - `addressLine1` (string, optional, nullable) — The first line of the street address. - `addressLine2` (string, optional, nullable) — The second line of the street address. - `cityLocality` (string, optional, nullable) — The city or locality. - `stateProvince` (string, optional, nullable) — The two-letter state or province code. - `postalCode` (string, optional, nullable) — The postal or ZIP code. - `country` (string, optional, nullable) — The two-letter ISO 3166-1 alpha-2 country code. - `type` (string, optional, nullable) — The role the address plays for the person, for example `legal` or `physical`. ### IdentificationDocumentResponse A government-issued identification document in a person response. - `type` (string, optional, nullable) — The document type, for example `passport` or `drivers_license`. - `number` (string, optional, nullable) — The document number. Masked on standard reads; read the unmasked endpoint for the raw value. - `issuingState` (string, optional, nullable) — The two-letter issuing state code. - `issuingCountry` (string, optional, nullable) — The two-letter issuing country code. - `expirationDate` (string, optional, nullable) — The document expiration date. ### BusinessRelationshipResponse The business-person relationship returned when a person is created with a `businessRelationship`. Its contact fields are scoped to the relationship and are distinct from the person's own top-level contact fields. - `businessReference` (string, required) — The reference of the linked business. - `personType` (string, required) — The person's role on the business, returned in lowercase (for example `owner`). - `ownershipPercentage` (double, required, nullable) — The person's ownership percentage (0 to 100). - `beneficialOwner` (boolean, required) — Whether the person qualifies as a beneficial owner. Derived by Payabli, not sent on create. - `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. - `billingAddressUuid` (string, required, nullable) — Reference to the stored billing address for the relationship. The address is sent as an object on create, then stored and returned by ID. - `mailingAddressUuid` (string, required, nullable) — Reference to the stored mailing address for the relationship. The address is sent as an object on create, then stored and returned by ID. ## Examples ### CreatePerson **Request** ```json { "firstName": "Marcus", "lastName": "Delgado", "middleName": "James", "primaryEmail": "marcus.delgado@example.com", "secondaryEmail": "m.delgado@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "dateOfBirth": "1985-03-14", "ssn": "412-55-9021", "nationality": "US", "driversLicenseNumber": "D1234567", "driversLicenseState": "FL", "externalId": "person-001", "customData": { "department": "finance" }, "addresses": [ { "addressLine1": "123 Main Street", "addressLine2": "Suite 400", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "legal" } ], "identificationDocuments": [ { "type": "passport", "number": "X1234567", "issuingCountry": "US", "expirationDate": "2030-06-30" } ], "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "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 created successfully", "traceId": "0HNNQ4R2OT26Q:0000001D", "data": { "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d", "firstName": "Marcus", "lastName": "Delgado", "verificationStatus": "not_started", "createdAt": "2026-08-14T17:24:31.3877241Z", "lastUpdated": "2026-08-14T17:24:31.3877242Z", "_links": { "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d", "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55" }, "externalId": "person-001", "middleName": "James", "primaryEmail": "marcus.delgado@example.com", "secondaryEmail": "m.delgado@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "dateOfBirth": "****-**-14", "ssn": "***-**-9021", "nationality": "US", "driversLicenseNumber": "D1***567", "driversLicenseState": "FL", "customData": { "department": "finance" }, "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personType": "owner", "ownershipPercentage": 100, "beneficialOwner": true, "isPrimaryController": true, "isSigner": true, "title": "CEO", "primaryEmail": "contact@example.com", "secondaryEmail": "contact.alt@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "billingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a891", "mailingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a892" } } } ``` **SDK Code** ```python CreatePerson import requests url = "https://api-sandbox.payabli.com/api/v2/people" payload = { "firstName": "Marcus", "lastName": "Delgado", "middleName": "James", "primaryEmail": "marcus.delgado@example.com", "secondaryEmail": "m.delgado@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "dateOfBirth": "1985-03-14", "ssn": "412-55-9021", "nationality": "US", "driversLicenseNumber": "D1234567", "driversLicenseState": "FL", "externalId": "person-001", "customData": { "department": "finance" }, "addresses": [ { "addressLine1": "123 Main Street", "addressLine2": "Suite 400", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "legal" } ], "identificationDocuments": [ { "type": "passport", "number": "X1234567", "issuingCountry": "US", "expirationDate": "2030-06-30" } ], "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "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 CreatePerson const url = 'https://api-sandbox.payabli.com/api/v2/people'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"firstName":"Marcus","lastName":"Delgado","middleName":"James","primaryEmail":"marcus.delgado@example.com","secondaryEmail":"m.delgado@example.net","primaryPhoneNumber":"3055551212","secondaryPhoneNumber":"3055559876","dateOfBirth":"1985-03-14","ssn":"412-55-9021","nationality":"US","driversLicenseNumber":"D1234567","driversLicenseState":"FL","externalId":"person-001","customData":{"department":"finance"},"addresses":[{"addressLine1":"123 Main Street","addressLine2":"Suite 400","cityLocality":"Miami","stateProvince":"FL","postalCode":"33101","country":"US","type":"legal"}],"identificationDocuments":[{"type":"passport","number":"X1234567","issuingCountry":"US","expirationDate":"2030-06-30"}],"businessRelationship":{"businessReference":"019fed1a-3d6e-75d3-a81e-cba3874b0a55","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 CreatePerson package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/v2/people" payload := strings.NewReader("{\n \"firstName\": \"Marcus\",\n \"lastName\": \"Delgado\",\n \"middleName\": \"James\",\n \"primaryEmail\": \"marcus.delgado@example.com\",\n \"secondaryEmail\": \"m.delgado@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"dateOfBirth\": \"1985-03-14\",\n \"ssn\": \"412-55-9021\",\n \"nationality\": \"US\",\n \"driversLicenseNumber\": \"D1234567\",\n \"driversLicenseState\": \"FL\",\n \"externalId\": \"person-001\",\n \"customData\": {\n \"department\": \"finance\"\n },\n \"addresses\": [\n {\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Suite 400\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"legal\"\n }\n ],\n \"identificationDocuments\": [\n {\n \"type\": \"passport\",\n \"number\": \"X1234567\",\n \"issuingCountry\": \"US\",\n \"expirationDate\": \"2030-06-30\"\n }\n ],\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\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 }\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 CreatePerson require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/v2/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 \"firstName\": \"Marcus\",\n \"lastName\": \"Delgado\",\n \"middleName\": \"James\",\n \"primaryEmail\": \"marcus.delgado@example.com\",\n \"secondaryEmail\": \"m.delgado@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"dateOfBirth\": \"1985-03-14\",\n \"ssn\": \"412-55-9021\",\n \"nationality\": \"US\",\n \"driversLicenseNumber\": \"D1234567\",\n \"driversLicenseState\": \"FL\",\n \"externalId\": \"person-001\",\n \"customData\": {\n \"department\": \"finance\"\n },\n \"addresses\": [\n {\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Suite 400\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"legal\"\n }\n ],\n \"identificationDocuments\": [\n {\n \"type\": \"passport\",\n \"number\": \"X1234567\",\n \"issuingCountry\": \"US\",\n \"expirationDate\": \"2030-06-30\"\n }\n ],\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\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 }\n}" response = http.request(request) puts response.read_body ``` ```java CreatePerson import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/v2/people") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"firstName\": \"Marcus\",\n \"lastName\": \"Delgado\",\n \"middleName\": \"James\",\n \"primaryEmail\": \"marcus.delgado@example.com\",\n \"secondaryEmail\": \"m.delgado@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"dateOfBirth\": \"1985-03-14\",\n \"ssn\": \"412-55-9021\",\n \"nationality\": \"US\",\n \"driversLicenseNumber\": \"D1234567\",\n \"driversLicenseState\": \"FL\",\n \"externalId\": \"person-001\",\n \"customData\": {\n \"department\": \"finance\"\n },\n \"addresses\": [\n {\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Suite 400\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"legal\"\n }\n ],\n \"identificationDocuments\": [\n {\n \"type\": \"passport\",\n \"number\": \"X1234567\",\n \"issuingCountry\": \"US\",\n \"expirationDate\": \"2030-06-30\"\n }\n ],\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\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 }\n}") .asString(); ``` ```php CreatePerson request('POST', 'https://api-sandbox.payabli.com/api/v2/people', [ 'body' => '{ "firstName": "Marcus", "lastName": "Delgado", "middleName": "James", "primaryEmail": "marcus.delgado@example.com", "secondaryEmail": "m.delgado@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "dateOfBirth": "1985-03-14", "ssn": "412-55-9021", "nationality": "US", "driversLicenseNumber": "D1234567", "driversLicenseState": "FL", "externalId": "person-001", "customData": { "department": "finance" }, "addresses": [ { "addressLine1": "123 Main Street", "addressLine2": "Suite 400", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "legal" } ], "identificationDocuments": [ { "type": "passport", "number": "X1234567", "issuingCountry": "US", "expirationDate": "2030-06-30" } ], "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "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 CreatePerson using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/v2/people"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"firstName\": \"Marcus\",\n \"lastName\": \"Delgado\",\n \"middleName\": \"James\",\n \"primaryEmail\": \"marcus.delgado@example.com\",\n \"secondaryEmail\": \"m.delgado@example.net\",\n \"primaryPhoneNumber\": \"3055551212\",\n \"secondaryPhoneNumber\": \"3055559876\",\n \"dateOfBirth\": \"1985-03-14\",\n \"ssn\": \"412-55-9021\",\n \"nationality\": \"US\",\n \"driversLicenseNumber\": \"D1234567\",\n \"driversLicenseState\": \"FL\",\n \"externalId\": \"person-001\",\n \"customData\": {\n \"department\": \"finance\"\n },\n \"addresses\": [\n {\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Suite 400\",\n \"cityLocality\": \"Miami\",\n \"stateProvince\": \"FL\",\n \"postalCode\": \"33101\",\n \"country\": \"US\",\n \"type\": \"legal\"\n }\n ],\n \"identificationDocuments\": [\n {\n \"type\": \"passport\",\n \"number\": \"X1234567\",\n \"issuingCountry\": \"US\",\n \"expirationDate\": \"2030-06-30\"\n }\n ],\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\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 }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift CreatePerson import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "firstName": "Marcus", "lastName": "Delgado", "middleName": "James", "primaryEmail": "marcus.delgado@example.com", "secondaryEmail": "m.delgado@example.net", "primaryPhoneNumber": "3055551212", "secondaryPhoneNumber": "3055559876", "dateOfBirth": "1985-03-14", "ssn": "412-55-9021", "nationality": "US", "driversLicenseNumber": "D1234567", "driversLicenseState": "FL", "externalId": "person-001", "customData": ["department": "finance"], "addresses": [ [ "addressLine1": "123 Main Street", "addressLine2": "Suite 400", "cityLocality": "Miami", "stateProvince": "FL", "postalCode": "33101", "country": "US", "type": "legal" ] ], "identificationDocuments": [ [ "type": "passport", "number": "X1234567", "issuingCountry": "US", "expirationDate": "2030-06-30" ] ], "businessRelationship": [ "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "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/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() ``` ### CreatePersonOwnershipExceeded **Request** ```json { "firstName": "Grace", "lastName": "Delgado", "nationality": "US", "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personType": "Owner", "ownershipPercentage": 50 } } ``` **Response** ```json { "success": false, "message": "Person created, but the business link did not complete. See warnings for details.", "traceId": "0HNONVRI1SQDV:0000001F", "data": { "personReference": "01a0d492-62c6-7151-9411-86ed90094a97", "firstName": "Grace", "lastName": "Delgado", "verificationStatus": "not_started", "createdAt": "2026-09-24T17:59:18.4704404Z", "lastUpdated": "2026-09-24T17:59:18.4704404Z", "_links": { "self": "/v2/people/01a0d492-62c6-7151-9411-86ed90094a97" }, "externalId": null, "middleName": null, "primaryEmail": null, "primaryPhoneNumber": null, "dateOfBirth": null, "ssn": null, "nationality": "US", "driversLicenseNumber": null, "driversLicenseState": null }, "warnings": [ { "code": "LINK_OWNERSHIP_EXCEEDED", "message": "Combined ownership would exceed 100% (existing 100.00%, attempted 50%)." } ] } ``` **SDK Code** ```python CreatePersonOwnershipExceeded import requests url = "https://api-sandbox.payabli.com/api/v2/people" payload = { "firstName": "Grace", "lastName": "Delgado", "nationality": "US", "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personType": "Owner", "ownershipPercentage": 50 } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript CreatePersonOwnershipExceeded const url = 'https://api-sandbox.payabli.com/api/v2/people'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"firstName":"Grace","lastName":"Delgado","nationality":"US","businessRelationship":{"businessReference":"019fed1a-3d6e-75d3-a81e-cba3874b0a55","personType":"Owner","ownershipPercentage":50}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go CreatePersonOwnershipExceeded package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/v2/people" payload := strings.NewReader("{\n \"firstName\": \"Grace\",\n \"lastName\": \"Delgado\",\n \"nationality\": \"US\",\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 50\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 CreatePersonOwnershipExceeded require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/v2/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 \"firstName\": \"Grace\",\n \"lastName\": \"Delgado\",\n \"nationality\": \"US\",\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 50\n }\n}" response = http.request(request) puts response.read_body ``` ```java CreatePersonOwnershipExceeded import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/v2/people") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"firstName\": \"Grace\",\n \"lastName\": \"Delgado\",\n \"nationality\": \"US\",\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 50\n }\n}") .asString(); ``` ```php CreatePersonOwnershipExceeded request('POST', 'https://api-sandbox.payabli.com/api/v2/people', [ 'body' => '{ "firstName": "Grace", "lastName": "Delgado", "nationality": "US", "businessRelationship": { "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personType": "Owner", "ownershipPercentage": 50 } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp CreatePersonOwnershipExceeded using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/v2/people"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"firstName\": \"Grace\",\n \"lastName\": \"Delgado\",\n \"nationality\": \"US\",\n \"businessRelationship\": {\n \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\n \"personType\": \"Owner\",\n \"ownershipPercentage\": 50\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift CreatePersonOwnershipExceeded import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "firstName": "Grace", "lastName": "Delgado", "nationality": "US", "businessRelationship": [ "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55", "personType": "Owner", "ownershipPercentage": 50 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/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() ```