Create an Associated Identity (Beneficial Owner)

Suggest Edits

---

Overview

Create an associated Identity for a beneficial owner with 25% or more ownership in the merchant business. Beneficial owner information is required for compliance and KYC (Know Your Customer) purposes when onboarding merchants.

---

Resource Access

Production (api.ahrvo.network)

POST https://api.ahrvo.network/payments/na/identities/\{identity_id}/associated_identities

Staging (gateway.ahrvo.network)

POST http://gateway.ahrvo.network/payments/na/identities/\{identity_id}/associated_identities

---

Arguments

Attribute	Mandatory / Optional	Description
identity_id	Mandatory	The ID of the primary merchant identity
entity.first_name	Mandatory	Beneficial owner's first name
entity.last_name	Mandatory	Beneficial owner's last name
entity.title	Optional	Position/title in the company
entity.dob	Mandatory	Date of birth (year, month, day)
entity.principal_percentage_ownership	Mandatory	Ownership percentage (25-100)
entity.personal_address	Mandatory	Residential address object
entity.phone	Optional	Phone number
entity.email	Optional	Email address
entity.tax_id	Mandatory	SSN or Tax ID

---

Example Request

curl -X POST https://gateway.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx/associated_identities \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -d '{
    "entity": {
      "first_name": "Sarah",
      "last_name": "Johnson",
      "title": "CFO",
      "dob": {
        "year": 1982,
        "month": 9,
        "day": 12
      },
      "principal_percentage_ownership": 40,
      "personal_address": {
        "line1": "789 Owner St",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94103",
        "country": "USA"
      },
      "phone": "4155552222",
      "email": "sarah@acme.com",
      "tax_id": "111223333"
    }
  }'

---

Example Response

{
  "id": "IDzzzzzzzzzzzzzzzzzz",
  "created_at": "2025-12-10T19:45:00Z",
  "updated_at": "2025-12-10T19:45:00Z",
  "application": "APxxxxxxxxxxxxxxxxxx",
  "type": "PERSONAL",
  "identity_roles": ["BENEFICIAL_OWNER"],
  "entity": {
    "first_name": "Sarah",
    "last_name": "Johnson",
    "title": "CFO",
    "dob": {
      "year": 1982,
      "month": 9,
      "day": 12
    },
    "principal_percentage_ownership": 40,
    "personal_address": {
      "line1": "789 Owner St",
      "line2": null,
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94103",
      "country": "USA"
    },
    "phone": "4155552222",
    "email": "sarah@acme.com",
    "tax_id_provided": true
  },
  "tags": {},
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDzzzzzzzzzzzzzzzzzz"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APxxxxxxxxxxxxxxxxxx"
    },
    "parent_identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx"
    }
  }
}

---

Beneficial Owner Requirements

According to FinCEN regulations:

• Ownership Threshold: Required for individuals owning 25% or more of the business
• Maximum Owners: Up to 4 beneficial owners can be added
• Verification: Each beneficial owner's identity must be verified for KYC compliance
• Complete Information: All required fields must be provided for compliance

---

When to Add Beneficial Owners

Add associated identities for:

• Co-founders with significant ownership
• Major investors or partners
• Family members with ownership stakes
• Anyone with 25% or more ownership

---

Important Notes

• Compliance Requirement: Required for merchant underwriting and approval
• Automatic Role: Associated identities automatically receive the BENEFICIAL_OWNER role
• Parent Relationship: Associated identities are linked to the parent merchant identity
• Verification Impact: Missing or incomplete beneficial owner information may delay merchant approval

---

API Documentation

---