/accounts/{accountId}/hierarchy

GET /accounts/{accountId}/hierarchy

Get complete account hierarchy as nested tree structure

Retrieve the complete hierarchy tree for an account as a nested tree structure. Returns two trees:

parentTree: The requested account as root with all parents (parents, grandparents, etc.) nested above it
childTree: The requested account as root with all children (children, grandchildren, etc.) nested below it

This endpoint loads all relationships in a single query and builds the tree in memory for optimal performance.

Example structure:

ISO (grandparent)
  └─ Agent (parent)
       └─ [Requested Account]
            ├─ Merchant 1 (child)
            └─ Merchant 2 (child)
                 └─ Location (grandchild)

Super Admins can access any account's hierarchy. Account Admins can only access hierarchies for their own accounts.

Authentication Required

Authorization: Bearer {token} header string

This header is required to access this endpoint

Required Parameters

accountId path string

Unique ID of the account to get hierarchy for

Try it out

Output:

Responses

Description

Successful response

{
  "account": {
    "uniqueId": "string",
    "name": "string",
    "accountTypeId": "string",
    "repcode": "string"
  },
  "parentTree": null,
  "childTree": null
}

References

#/components/schemas/AccountSummary #/components/schemas/HierarchyNode #/components/schemas/AccountHierarchy

type: object
properties:
  uniqueId:
    type: string
    description: Unique identifier for the account
  name:
    type: string
    description: Account name
  accountTypeId:
    type: string
    nullable: true
    description: Type of account (e.g., "iso", "agent", "merchant")
  repcode:
    type: string
    nullable: true
    description: Representative code for the account
required:
  - uniqueId
  - name

|
export interface AccountSummary {
  /** Unique identifier for the account */
  uniqueId: string;
  /** Account name */
  name: string;
  /** Type of account (e.g., "iso", "agent", "merchant") */
  accountTypeId?: string;
  /** Representative code for the account */
  repcode?: string;
}

#/components/schemas/HierarchyNode

OpenAPI
TypeScript

type: object
properties:
  uniqueId:
    type: string
    description: Unique identifier for the account
  name:
    type: string
    description: Account name
  accountTypeId:
    type: string
    nullable: true
    description: Type of account (e.g., "iso", "agent", "merchant")
  repcode:
    type: string
    nullable: true
    description: Representative code for the account
  parents:
    type: array
    description: Parent accounts (recursively nested)
  children:
    type: array
    description: Child accounts (recursively nested)
required:
  - uniqueId
  - name

|
export interface HierarchyNode {
  /** Unique identifier for the account */
  uniqueId: string;
  /** Account name */
  name: string;
  /** Type of account (e.g., "iso", "agent", "merchant") */
  accountTypeId?: string;
  /** Representative code for the account */
  repcode?: string;
  /** Parent accounts (recursively nested) */
  parents?: any[];
  /** Child accounts (recursively nested) */
  children?: any[];
}

#/components/schemas/AccountHierarchy

OpenAPI
TypeScript

type: object
properties:
  account:
    $ref: "#/components/schemas/AccountSummary"
  parentTree:
    allOf:
      - type: object
        properties:
          uniqueId:
            type: string
            description: Unique identifier for the account
          name:
            type: string
            description: Account name
          accountTypeId:
            type: string
            nullable: true
            description: Type of account (e.g., "iso", "agent", "merchant")
          repcode:
            type: string
            nullable: true
            description: Representative code for the account
          parents:
            type: array
            description: Parent accounts (recursively nested)
          children:
            type: array
            description: Child accounts (recursively nested)
        required:
          - uniqueId
          - name
        fromRef: "#/components/schemas/HierarchyNode"
      - description: Tree with this account as root, showing all parent accounts nested
          above
  childTree:
    allOf:
      - type: object
        properties:
          uniqueId:
            type: string
            description: Unique identifier for the account
          name:
            type: string
            description: Account name
          accountTypeId:
            type: string
            nullable: true
            description: Type of account (e.g., "iso", "agent", "merchant")
          repcode:
            type: string
            nullable: true
            description: Representative code for the account
          parents:
            type: array
            description: Parent accounts (recursively nested)
          children:
            type: array
            description: Child accounts (recursively nested)
        required:
          - uniqueId
          - name
        fromRef: "#/components/schemas/HierarchyNode"
      - description: Tree with this account as root, showing all child accounts nested below
required:
  - account
  - parentTree
  - childTree

|
export interface AccountHierarchy {
  account: AccountSummary;
  parentTree: {
    uniqueId: string;
    name: string;
    accountTypeId?: string;
    repcode?: string;
    parents?: any[];
    children?: any[];
  } & any;
  childTree: {
    uniqueId: string;
    name: string;
    accountTypeId?: string;
    repcode?: string;
    parents?: any[];
    children?: any[];
  } & any;
}

Route Source Code

Check out the source code for this route entrypoint here: /accounts/[accountId]/hierarchy/route.ts

Or the swagger.yaml spec this documentation was generated from: /accounts/swagger.yaml