/accounts/relationship

POST /accounts/relationship

Create one or more parent-child relationships

Create parent-child relationships between accounts in bulk.

Validates all accounts exist
Prevents circular relationships (e.g., child becoming parent of its ancestor)
Prevents duplicate relationships (handled by unique constraint)
Supports creating multiple relationships in one request

Requires Super Admin permissions.

Authentication Required

Authorization: Bearer {token} header string

This header is required to access this endpoint

Request Body

{
  "relationships": [
    {
      "parentAccountId": "string",
      "childAccountId": "string"
    }
  ]
}

{
  "relationships": [
    {
      "parentAccountId": "iso-123",
      "childAccountId": "agent-456"
    }
  ]
}

{
  "relationships": [
    {
      "parentAccountId": "iso-123",
      "childAccountId": "agent-456"
    },
    {
      "parentAccountId": "iso-123",
      "childAccountId": "agent-789"
    },
    {
      "parentAccountId": "agent-456",
      "childAccountId": "merchant-001"
    }
  ]
}

{
  "relationships": [
    {
      "parentAccountId": "string",
      "childAccountId": "string"
    }
  ]
}

Try it out

Output:

Responses

Description

Relationships created successfully

[
  {
    "parentAccountId": "string",
    "childAccountId": "string",
    "createdBy": "string",
    "createdAt": "string",
    "parentAccount": {
      "uniqueId": "string",
      "name": "string",
      "accountTypeId": "string",
      "repcode": "string"
    },
    "childAccount": {
      "uniqueId": "string",
      "name": "string",
      "accountTypeId": "string",
      "repcode": "string"
    }
  }
]

Description

Bad Request

{
  "error": "string",
  "status": 0,
  "message": "string"
}

References

#/components/schemas/AccountSummary #/components/schemas/AccountRelationship #/components/schemas/Error

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/AccountRelationship

OpenAPI
TypeScript

type: object
properties:
  parentAccountId:
    type: string
    description: Unique ID of the parent account
  childAccountId:
    type: string
    description: Unique ID of the child account
  createdBy:
    type: string
    description: Email of the user who created the relationship
  createdAt:
    type: string
    format: date-time
    description: Timestamp when the relationship was created
  parentAccount:
    $ref: "#/components/schemas/AccountSummary"
  childAccount:
    $ref: "#/components/schemas/AccountSummary"
required:
  - parentAccountId
  - childAccountId
  - createdBy
  - createdAt

|
export interface AccountRelationship {
  /** Unique ID of the parent account */
  parentAccountId: string;
  /** Unique ID of the child account */
  childAccountId: string;
  /** Email of the user who created the relationship */
  createdBy: string;
  /** Timestamp when the relationship was created */
  createdAt: Date;
  parentAccount?: AccountSummary;
  childAccount?: AccountSummary;
}

#/components/schemas/Error

OpenAPI
TypeScript

type: object
properties:
  error:
    type: string
    description: Error message
  status:
    type: integer
    description: HTTP status code
  message:
    type: string
    description: Detailed error message
description: Error response object
required:
  - error

|
export interface Error {
  /** Error message */
  error: string;
  /** HTTP status code */
  status?: number;
  /** Detailed error message */
  message?: string;
}

Route Source Code

Check out the source code for this route entrypoint here: /accounts/relationship/route.ts

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