Manage people with the API
Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.
A person is an individual associated with a business, such as an owner, director, signer, contact, or employee. Use the people API to create and manage those records as you board a paypoint. For how people fit into the wider model, see the boarding overview.
Considerations
- The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
- A person’s
nationalitydecides which identity number applies. ForUS, sendssn. For any other nationality, sendnationalIdNumberandnationalIdIssuerinstead. Creating a person doesn’t check these, but an owner needs them to be validated. - A person’s job
titleand signer status (isSigner) belong to the person’s link with each business. Set them inbusinessRelationshipwhen you create the person, or on the link later. The same person can have a different title at each business. - Reads mask sensitive fields such as
ssn,nationalIdNumber,dateOfBirth, and identification document numbers. Use the unmasked endpoint when you need the raw values.
Create a person
Send a POST request to /v2/people with the person’s details. Only firstName and lastName are required. See the API reference for this endpoint for full documentation.
To link the person to a business as you create them, include a businessRelationship object with the businessReference and the person’s role in personType. For an owner, ownershipPercentage is required, from 0 to 100. Leave it out for every other role. Application validation holds every role except Employee to the owner requirements, so link anyone who doesn’t own part of the business, such as a contact, as an Employee. The relationship’s contact fields and addresses are separate from the person’s own top-level contact fields.
The response returns the new person with sensitive fields masked:
The personReference in the response is the reference you use to read and manage the person.
Handle a link that doesn’t complete
If linking an owner would push the business’s total ownership over 100%, Payabli still creates the person but doesn’t complete the link. The request still returns 201, but success is false, the person has no businessRelationship, and the warnings array contains a LINK_OWNERSHIP_EXCEEDED entry:
Check warnings on every create response, not only the status code. To finish linking the person, first lower an existing owner’s ownershipPercentage so the total leaves room, then link the person to the business. While the total is already at 100%, the link request fails with 400.
Get a person
Send a GET request to /v2/people/{personReference}. Sensitive fields such as ssn are masked. See the API reference for this endpoint for full documentation.
The response returns the person’s detail with sensitive fields masked:
Get unmasked person detail
To read the raw values of masked fields, send a GET request to /v2/people/{personReference}/unmasked. See the API reference for this endpoint for full documentation.
The response returns the same detail with sensitive fields unmasked:
List people
Send a GET request to /v2/people. Filter and page the results with the query parameters: name, email, verificationStatus, limit, page, sortBy, and sortOrder. See the API reference for this endpoint for full documentation.
The response returns a page of people with pagination metadata:
Update a person
Send a PATCH request to /v2/people/{personReference} with only the fields you want to change. See the API reference for this endpoint for full documentation.
You can’t change ssn, nationalIdNumber, or dateOfBirth after you create a person, so set them correctly when you create the person.
The response confirms the update and returns the new timestamp:
Search people
Send a POST request to /v2/people/search with at least one of firstName or lastName. Pass your organization’s entry name in the entry query parameter and its ID in orgId. Both are required. The entry name is OrgEntryName in the organization details. If you pass a paypoint’s entry name instead, the search covers only that paypoint’s business. See the API reference for this endpoint for full documentation.
Use search during boarding to check whether a person already exists in your organization, linked to another business, before you create them. It matches on identity details such as name, date of birth, email, and SSN. An external identity vendor can also enrich the results. To read the people already on the business, list the business’s people instead.
The response returns each match with a matchScore, plus the total count. A result with isFromVendor set to true came only from the identity vendor and has no personReference:
Search results mask each person’s dateOfBirth. To get the full value, send the same request to /v2/people/search/unmasked. See the API reference for this endpoint for full documentation.
Link a person to a business
A person can be linked to more than one business. To link someone you’ve already created, or to change or remove a link, use the people endpoints under the business. See Manage the people on a business.
Related resources
See these related resources to help you get the most out of Payabli.
References
- Required fields for boarding applications - Learn more about the Know Your Customer (KYC) and Know Your Business (KYB) fields required for merchant boarding