Skip to main content

List Associated Identities

Suggest Edits

Overview​

Retrieve a list of associated Identities (beneficial owners) for a parent merchant Identity. This endpoint returns all individuals with 25% or more ownership in the business.

Resource Access​

Production (api.ahrvo.network)

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

Staging (gateway.ahrvo.network)

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

Arguments​

AttributeMandatory / OptionalDescription
identity_idMandatoryThe ID of the parent merchant identity
limitOptionalThe number of items to return (default: 10)
after_cursorOptionalReturn every resource created after the cursor value

Example Request​

curl -X GET "https://gateway.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx/associated_identities?limit=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64_encoded_credentials>"

Example Response​

{
  "_embedded": {
    "identities": [
      {
        "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"
          },
          "parent_identity": {
            "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx"
          }
        }
      },
      {
        "id": "IDaaaaaaaaaaaaaaaaaaa",
        "created_at": "2025-12-10T20:00:00Z",
        "updated_at": "2025-12-10T20:00:00Z",
        "application": "APxxxxxxxxxxxxxxxxxx",
        "type": "PERSONAL",
        "identity_roles": ["BENEFICIAL_OWNER"],
        "entity": {
          "first_name": "Michael",
          "last_name": "Chen",
          "title": "CTO",
          "dob": {
            "year": 1988,
            "month": 4,
            "day": 25
          },
          "principal_percentage_ownership": 30,
          "personal_address": {
            "line1": "321 Tech Blvd",
            "line2": null,
            "city": "Palo Alto",
            "region": "CA",
            "postal_code": "94301",
            "country": "USA"
          },
          "phone": "6505553333",
          "email": "michael@acme.com",
          "tax_id_provided": true
        },
        "tags": {},
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/identities/IDaaaaaaaaaaaaaaaaaaa"
          },
          "parent_identity": {
            "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx/associated_identities?limit=10"
    }
  }
}

Understanding Beneficial Owners​

Key Information​

  • Identity Role: All associated identities have the BENEFICIAL_OWNER role
  • Ownership: Each owner's principal_percentage_ownership indicates their stake
  • Total Ownership: The sum of all ownership percentages may not equal 100% (only those with 25%+ are required)
  • Parent Link: Each beneficial owner links back to the parent merchant identity

Compliance Requirements​

  • Required for merchants with multiple owners
  • Part of KYC (Know Your Customer) verification
  • Needed for underwriting approval
  • Updated when ownership structure changes

Use Cases​

  • Compliance Verification: Review all beneficial owners for a merchant
  • Reporting: Generate ownership reports for compliance
  • Auditing: Verify ownership structure is current and complete
  • Onboarding: Ensure all required owners are documented before merchant approval

API Documentation​