Create Business UBO

Create an Ultimate Beneficial Owner (UBO) with identity documents for a business customer.

Endpoint

POST https://prod.rynopay.io/partner/v1/business-profiles/{customerId}/associate-ubo

Path parameters

Parameter	Type	Description
customerId	UUID	The business customer ID returned from Create Business Profile

Request body

Field	Type	Required	Description
customerId	string (UUID)	Yes	Business customer ID
firstName	string	Yes	UBO first name (max 100 chars)
lastName	string	Yes	UBO last name (max 100 chars)
birthDate	string	No	Date of birth (YYYY-MM-DD, must be in the past)
taxResidenceCountry	string	No	Tax residence country (ISO 3166-1 alpha-3)
email	string	Yes	UBO email address (max 255 chars)
phone	string	No	International phone number (E.164 format)
ownershipType	string[]	Yes	One or more ownership types. See allowed values
percentageShare	integer	No	Ownership percentage (1–100)
address	object	Yes	Address object
identities	array	Yes	List of Identity objects (at least one required)

Identity object

Field	Type	Required	Description
identityTypeCode	string	Yes	Identity document type. See allowed values
issuingCountry	string	Yes	Issuing country (ISO 3166-1 alpha-3)
identityValue	string	Yes	Document number or value (max 255 chars)
documentUploadId	string (UUID)	No	Reference to an uploaded document file
issueDate	string	No	Document issue date (YYYY-MM-DD, must not be in the future)
expiryDate	string	No	Document expiry date (YYYY-MM-DD, must be in the future)

info

When both issueDate and expiryDate are provided, the expiry date must be after the issue date. Whether these dates are required depends on the country onboarding configuration for the business customer.

Example request

curl -X POST https://prod.rynopay.io/partner/v1/business-profiles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/associate-ubo \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1985-03-15",
    "taxResidenceCountry": "NGA",
    "email": "john.doe@acmecorp.com",
    "phone": "+2348012345678",
    "ownershipType": ["SHAREHOLDER", "DIRECTOR"],
    "percentageShare": 45,
    "address": {
      "streetLine1": "12 Marina Road",
      "city": "Lagos",
      "state": "Lagos",
      "postalCode": "100001",
      "countryCode": "NGA"
    },
    "identities": [
      {
        "identityTypeCode": "PASSPORT",
        "issuingCountry": "NGA",
        "identityValue": "A12345678",
        "issueDate": "2020-01-10",
        "expiryDate": "2030-01-10"
      }
    ]
  }'

Response

200 OK

{
  "isSuccess": true,
  "value": {
    "uboId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Field	Type	Description
uboId	string (UUID)	Unique identifier for the newly created UBO

400 Bad Request

{
  "isSuccess": false,
  "error": {
    "code": "Validation",
    "message": "One or more validation errors occurred"
  }
}

Enum reference

Ownership types

Value
SHAREHOLDER
DIRECTOR
UBO

Identity types

Value	Description
NATIOANL_ID	National identity card
PASSPORT	International passport
DRIVING_LICENCE	Driving licence
IDENTITY_CARD	General identity card
RESIDENCE_CARD	Residence permit card
VOTER_CARD	Voter registration card
BVN	Bank Verification Number
OTHERS	Other identity document