Developer Documentation

Retrieve org hierarchy details

get https://{host}.api.capillarytech.com/v2/organization/hierarchy

API to retrieve hierarchy details of an org.

This API retrieves the hierarchy details of an organization based on the API credentials (till credentials/OAuth token).

👍

Note

For an overview on our APIs and for hands-on testing, refer to API overview and Make your first API call documentation.

Prerequisites

Resource information

URIv2/organization/hierarchy
HTTP methodGET
PaginationNA
Rate limitNA
Batch supportNA

Terminologies:

  1. Standard Org: An independent organization identified by a parentId of -1.
  2. Super Org: An organization with child organizations but no parent, also identified by a parentId of -1.
  3. Connected Org: An organization linked to others within a hierarchy.
  4. Base Org: The organization making the API request.

API endpoint example

curl --location 'https://eu.api.capillarytech.com/v2/organization/hierarchy'

Request query parameters

ParameterTypeDescription
fetchSiblingsbooleanSet fetchSiblings=true to retrieve details of all related organizations. This includes the details of all the orgs that share the same parent, the parent org and the requesting child org details.
If set to false and the request is made from a child org, the API will retrieve only the details of the child org and its parent org.
fetchCustomFieldsbooleanIncludes the org-level custom fields (custom fields with the scope (ORG_CUSTOM_FIELD) under the org.

Response Scenarios Based on Organization Type

  • Request from a Child Organization:

    • If fetchSiblings=true: The response includes:
      • The base (child) organization itself.
      • All other connected organizations that share the same parent.
    • If fetchSiblings=false or not set: The response includes only the child and its parent organization.

  • Request from a Parent Organization:

    • The response includes details of the base (parent) organization and all connected child organizations.

  • Request from a Standard (Independent) Organization:

    • As this organization has no parent or child associations, the response includes only the base organization.

Response parameters

ParameterTypeDescription
baseOrganizationObjectIncludes the details of the org from which the request is made.
idIntegerUnique identifier for the organization.
nameStringName of the organization.
phoneStringContact phone number for the organization.
addressStringAddress of the organization.
languageStringLanguage used by the organization.
languageCodeStringCode representing the language (e.g., "en" for English).
languageLocaleStringLocale representing the language (e.g., "en-US).
parentIdIntegerID of the parent organization. A value of -1 indicates no parent organization. Also for Standard and Super org, the id is -1.
localityStringLocality of the organization.
pinCodeStringPostal code for the organization’s address.
currencyStringCurrency used by the organization (e.g., "United States dollar").
timezoneLabelStringThe time zone in which the organization operates (e.g., "Asia/Kolkata").
timezoneOffsetStringOffset from UTC for the organization's time zone (e.g., "+05:30").
minSmsHourIntegerMinimum hour of the day during which SMS can be sent (24-hour format).
maxSmsHourIntegerMaximum hour of the day during which SMS can be sent (24-hour format).
logoStringThis parameter is not in use.
webSiteStringWebsite URL for the organization.
countryStringCountry in which the organization is located.
countryCodeStringISO country code (e.g., "US" for the United States).
activeBooleanIndicates whether the organization is active (true) or inactive (false).
orgTypeStringType of the organization (e.g., Standard org, Super org, Parent org, Child org.).
relationshipTypeStringIndicates the type of relationship with the org.
connectedOrganizationsArrayList of related organizations.
orgTypeStringIndicates whether an organization is a STANDARD_ORG (independent), SUPER_ORG (a parent with child organizations), or CHILD_ORG (a child of a parent organization).
warningsArrayList of warnings related to the organization. Empty if none.

{
  "baseOrganization": {
    "id": 3,
    "name": "Child-One-Org",
    "phone": "",
    "address": "NA",
    "language": null,
    "languageCode": null,
    "languageLocale": null,
    "parentId": 2,
    "locality": null,
    "pinCode": null,
    "currency": null,
    "timezoneLabel": "Antarctica/Vostok",
    "timezoneOffset": "+07:00",
    "minSmsHour": 11,
    "maxSmsHour": 19,
    "logo": null,
    "webSite": null,
    "country": null,
    "countryCode": null,
    "state": null,
    "city": null,
    "active": true,
    "relationshipType": "PARENT_CHILD",
    "orgType": "CHILD_ORG"
  },
  "connectedOrganizations": [
    {
      "id": 4,
      "name": "Child-Two-Org",
      "phone": "",
      "address": "NA",
      "language": null,
      "languageCode": null,
      "languageLocale": null,
      "parentId": 2,
      "locality": null,
      "pinCode": null,
      "currency": null,
      "timezoneLabel": "Antarctica/Vostok",
      "timezoneOffset": "+07:00",
      "minSmsHour": 11,
      "maxSmsHour": 19,
      "logo": null,
      "webSite": null,
      "country": null,
      "countryCode": null,
      "state": null,
      "city": null,
      "active": true,
     
      "orgType": "CHILD_ORG"
    },
    {
      "id": 2,
      "name": "Parent-One-Org",
      "phone": "",
      "address": "NA",
      "language": null,
      "languageCode": null,
      "languageLocale": null,
      "parentId": -1,
      "locality": null,
      "pinCode": null,
      "currency": null,
      "timezoneLabel": "Antarctica/Vostok",
      "timezoneOffset": "+07:00",
      "minSmsHour": 11,
      "maxSmsHour": 19,
      "logo": null,
      "webSite": null,
      "country": null,
      "countryCode": null,
      "state": null,
      "city": null,
      "active": true,
      
      "orgType": "SUPER_ORG"
    }
  ],
  "uniqueId": null,
  "warnings": [
    
  ]
}


{
    "baseOrganization": {
        "id": 50398,
        "name": "connectedOrgChild1",
        "phone": "",
        "address": "",
        "parentId": -1,
        "locality": "",
        "pinCode": "700045",
        "timezoneLabel": "Asia/Kolkata",
        "timezoneOffset": "+05:30",
        "minSmsHour": 9,
        "maxSmsHour": 21,
        "logo": "",
        "webSite": "",
        "country": "India",
        "countryCode": "IN",
        "active": true,
      "relationshipType": "PARENT_CHILD",
        "orgType": "SUPER_ORG",
        "customFields": {
            "Footer": "#1234",
            "Header": "#1234",
            "Org Secondary Color": "#1234",
            "Testing 1": "5678"
        }
    },
    "connectedOrganizations": [
        {
            "id": 50399,
            "name": "connectedOrgChildOne",
            "phone": "",
            "address": "JODHPUR GARDENS P/O LAKE GARDENS KOLKATA - 700045",
            "parentId": 50398,
            "locality": "",
            "pinCode": "700045",
            "timezoneLabel": "Asia/Kolkata",
            "timezoneOffset": "+05:30",
            "minSmsHour": 9,
            "maxSmsHour": 21,
            "logo": "",
            "webSite": "",
            "country": "India",
            "countryCode": "IN",
            "state": "West Bengal",
            "city": "KOLKATA",
            "active": true,
            
            "orgType": "CHILD_ORG",
            "customFields": {
                "Header": "#7890",
                "Org Secondary Color": "#4567"
            }
        }
    ],
    "warnings": []
}

{
  "baseOrganization": {
    "id": 3,
    "name": "Child-One-Org",
    "phone": "",
    "address": "NA",
    "language": null,
    "languageCode": null,
    "languageLocale": null,
    "parentId": 2,
    "locality": null,
    "pinCode": null,
    "currency": null,
    "timezoneLabel": "Antarctica/Vostok",
    "timezoneOffset": "+07:00",
    "minSmsHour": 11,
    "maxSmsHour": 19,
    "logo": null,
    "webSite": null,
    "country": null,
    "countryCode": null,
    "state": null,
    "city": null,
    "active": true,
    "relationshipType": "PARENT_CHILD",
    "orgType": "CHILD_ORG"
  },
  "connectedOrganizations": [
    {
      "id": 2,
      "name": "Parent-One-Org",
      "phone": "",
      "address": "NA",
      "language": null,
      "languageCode": null,
      "languageLocale": null,
      "parentId": -1,
      "locality": null,
      "pinCode": null,
      "currency": null,
      "timezoneLabel": "Antarctica/Vostok",
      "timezoneOffset": "+07:00",
      "minSmsHour": 11,
      "maxSmsHour": 19,
      "logo": null,
      "webSite": null,
      "country": null,
      "countryCode": null,
      "state": null,
      "city": null,
      "active": true,
      
      "orgType": "SUPER_ORG"
    }
  ],
  "uniqueId": null,
  "warnings": [
    
  ]
}


{
  "baseOrganization": {
    "id": 1115,
    "name": "Nightly_ApiAuto",
    "phone": "",
    "address": "asdasd",
    "language": "Dari-Persian, Pashtu",
    "languageLocale": "AF",
    "parentId": -1,
    "locality": "",
    "pinCode": "560800",
    "currency": "Indian Rupee ",
    "timezoneLabel": "Asia/Kolkata",
    "timezoneOffset": "+05:30",
    "minSmsHour": 12,
    "maxSmsHour": 21,
    "logo": "",
    "webSite": "",
    "country": "India",
    "countryCode": "IN",
    "state": "Karnataka",
    "city": "Bangalore",
    "active": true,
    "orgType": "STANDARD_ORG"
  },
  "connectedOrganizations": [],
  "warnings": []


{
  "baseOrganization": {
    "id": 51956,
    "name": "connectedOrgChildOne",
    "phone": "",
    "address": "JODHPUR GARDENS P/O LAKE GARDENS KOLKATA - 700045",
    "parentId": -1,
    "locality": "",
    "pinCode": "700045",
    "timezoneLabel": "Asia/Kolkata",
    "timezoneOffset": "+05:30",
    "minSmsHour": 9,
    "maxSmsHour": 21,
    "logo": "",
    "webSite": "",
    "country": "India",
    "countryCode": "IN",
    "state": "West Bengal",
    "city": "KOLKATA",
    "active": true,
    "relationshipType": "PARENT_CHILD",
    "orgType": "SUPER_ORG"
  },
  "connectedOrganizations": [
    {
      "id": 51957,
      "name": "connectedOrgChildTwo",
      "phone": "",
      "address": "JODHPUR GARDENS P/O LAKE GARDENS KOLKATA - 700045",
      "parentId": 51956,
      "locality": "",
      "pinCode": "700045",
      "timezoneLabel": "Asia/Kolkata",
      "timezoneOffset": "+05:30",
      "minSmsHour": 9,
      "maxSmsHour": 21,
      "logo": "",
      "webSite": "",
      "country": "India",
      "countryCode": "IN",
      "state": "West Bengal",
      "city": "KOLKATA",
      "active": true,
      
      "orgType": "CHILD_ORG"
    }
  ],
  "warnings": [
    
  ]
}
Language
Credentials
OAuth2
URL
Click Try It! to start a request and see the response here!