Time	Status	User Agent
Retrieving recent requests…

Use this API to retrieve store location details from your organisation. You can fetch all stores, search by code, name, or external ID, or retrieve a specific store with its hierarchy information. The API supports pagination, sorting, and filtering.

You can use this API to:

Fetch all stores in the organisation.
Search stores by code, name, or external ID prefix.
Retrieve specific stores using store codes.
Filter stores by active status or admin type.
Retrieve hierarchy information including parent zones, concepts, and child locations.

The response includes store details, contact information, location coordinates, optional hierarchy data, and pagination details.

🚧
Filter precedence
When using multiple filters, entityCodes takes precedence over q filters. Multiple q filters are combined with OR logic.

Example request

curl --location 'https://crm-nightly-new.cc.capillarytech.com/v2/locations?q=name%3Akrishna%2C%20external_id%3Ashivam' \
--header 'Authorization: Basic a3Jpc2huYSYjk2NGIwNzE1MmQyMzRiNzA='

curl --location 'https://eu.api.capillarytech.com/v2/locations?type=STORE&entityCodes=store001,store002' \
--header 'Authorization: Basic YOUR_AUTH_TOKEN'

curl --location 'https://eu.api.capillarytech.com/v2/locations?type=STORE&q=name:MUM,code:STR' \
--header 'Authorization: Basic YOUR_AUTH_TOKEN'

curl --location 'https://eu.api.capillarytech.com/v2/locations?type=STORE&entityCodes=store001&includeChildren=true' \
--header 'Authorization: Basic YOUR_AUTH_TOKEN'

Prerequisites

Authentication: Basic or OAuth authentication
Access group resource: Read access to the Organization resource

Resource information


HTTP method	GET
Pagination	Yes

Query parameters

Field	Type	Required	Description
type	string	Optional	Location type. Currently supported: `STORE`. Other types (`ZONE`, `TILL`, `CONCEPT`) are planned for future releases. Defaults to `STORE`.
entityCodes	string	Optional	Comma-separated store codes to retrieve specific stores. Maximum 30 codes. Takes precedence over `q` filters when provided. Example: store001, store002
q	string	Optional	Comma-separated `field:value` pairs for prefix search. Supported fields: `name`, `code`, `external_id`. Returns stores whose field value starts with the specified string. This parameter is ignored if `entityCodes` is provided. Example: `q=name:MUM,code:STR` returns stores where name starts with "MUM" OR code starts with "STR".
isActive	boolean	Optional	Filter by active status. `true` for active stores, `false` for inactive stores.
isAdmin	boolean	Optional	Filter by admin type. `true` for admin stores, `false` for non-admin stores.
isOrgUnit	boolean	Optional	Filter by organization unit status. Only valid when `type=CONCEPT`.
limit	integer	Optional	Maximum number of records to retrieve per page. Values: 1–100. Defaults to `20`.
offset	integer	Optional	Number of records to skip from the beginning of the response. Defaults to `0`.
sortBy	string	Optional	Allows you to sort the response based on specific fields. Supported values: `entityCode`, `name`, `lastUpdated`. Defaults to `lastUpdated`.
sortOrder	string	Optional	Sort direction. Supported values: `ASC`, `DESC`. Defaults to `DESC`.
includeCFs	boolean	Optional	Include custom fields in the response. When `true`, the `attributes` object is populated in each store record.
includeChildren	boolean	Optional	Include child locations in the hierarchy. Requires exactly one code in `entityCodes`.
childrenLimit	integer	Optional	Maximum number of child records to retrieve per page. Values: 1–100. Defaults to `10`.
childrenOffset	integer	Optional	Number of child records to skip from the beginning of the response. Defaults to `0`.

Example response

{
    "limit": 20,
    "offset": 0,
    "total": 1,
    "data": [
        {
            "id": 50019407,
            "type": "STORE",
            "code": "krishna.store01",
            "externalId": "shivam01",
            "name": "krishna store01",
            "description": "",
            "isActive": true,
            "isAdmin": false,
            "isOuEnabled": false,
            "lastUpdatedOn": "2025-11-07T18:11:41+05:30",
            "hierarchy": {
                "areaParent": {
                    "id": 50019405,
                    "type": "ZONE",
                    "name": "South",
                    "code": "south",
                    "externalId": "south"
                },
                "groupParent": {
                    "id": 50019397,
                    "type": "CONCEPT",
                    "name": "ROOT",
                    "code": "root",
                    "externalId": "root",
                    "isOrgUnit": false
                }
            },
            "email": "",
            "mobile": "",
            "landline": "",
            "latitude": "",
            "longitude": "",
            "externalId1": "",
            "externalId2": ""
        }
    ]
}

{
  "limit": 20,
  "offset": 0,
  "total": 1,
  "data": [
    {
      "id": 50770954,
      "type": "STORE",
      "code": "store001",
      "external_id": "EXT-001",
      "name": "Main Street Store",
      "description": "Downtown flagship store",
      "is_active": true,
      "is_admin": false,
      "is_ou_enabled": false,
      "last_updated_on": "2024-01-15T10:30:00Z",
      "email": "[email protected]",
      "mobile": "919686000000",
      "landline": "",
      "latitude": "12.9716",
      "longitude": "77.5946",
      "external_id_1": "ALT-EXT-001",
      "external_id_2": "",
      "parentZoneId": 75152646,
      "parentConceptId": 75216471,
      "hierarchy": {
        "area_parent": {
          "id": 75152647,
          "type": "ZONE",
          "display_type": "Area",
          "name": "South Zone",
          "code": "ZONE_SOUTH",
          "external_id": "EXT-ZONE-001"
        },
        "group_parent": {
          "id": 75216471,
          "type": "CONCEPT",
          "display_type": "Concept",
          "name": "Retail Concept",
          "code": "CONCEPT_RETAIL",
          "external_id": "EXT-CONCEPT-001"
        },
        "child_count": 0
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}

{
  "limit": 20,
  "offset": 0,
  "total": 1,
  "data": [
    {
      "id": 50770954,
      "type": "STORE",
      "code": "store001",
      "external_id": "EXT-001",
      "name": "Main Street Store",
      "description": "Downtown flagship store",
      "is_active": true,
      "is_admin": false,
      "is_ou_enabled": false,
      "last_updated_on": "2024-01-15T10:30:00Z",
      "email": "[email protected]",
      "mobile": "919686000000",
      "landline": "",
      "latitude": "12.9716",
      "longitude": "77.5946",
      "external_id_1": "ALT-EXT-001",
      "external_id_2": "",
      "parentZoneId": 75152646,
      "parentConceptId": 75216471,
      "attributes": {
        "store_region": "South",
        "store_size": "Large"
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}

Response parameters

Parameter	Type	Description
limit	integer	Records returned per page.
offset	integer	Starting position of returned records.
total	integer	Total locations matching the criteria.
data	array	Array of location objects matching the request criteria.
. id	integer	Unique identifier for the location.
. type	string	Location type (`STORE`).
. code	string	Unique store code.
. external_id	string	Primary external identifier.
. name	string	Store name.
. description	string	Store description.
. is_active	boolean	Whether the store is active.
. is_admin	boolean	Whether this is an admin store.
. is_ou_enabled	boolean	Whether organization unit is enabled.
. last_updated_on	string	ISO 8601 timestamp of last update.
. email	string	Store email address.
. mobile	string	Store mobile number.
. landline	string	Store landline number.
. latitude	string	Latitude coordinate.
. longitude	string	Longitude coordinate.
. external_id_1	string	Additional external identifier.
. external_id_2	string	Additional external identifier.
. parentZoneId	integer	Parent zone ID.
. parentConceptId	integer	Parent concept ID.
. attributes	object	Custom fields as key-value pairs. Returned when `includeCFs=true`.
. hierarchy	object	Hierarchy information. Returned when `includeChildren=true`.
. . area_parent	object	Parent area/zone information.
. . . id	integer	Unique identifier for the parent zone.
. . . type	string	Entity type (`ZONE`).
. . . display_type	string	Display name for the entity type.
. . . name	string	Name of the parent zone.
. . . code	string	Unique code of the parent zone.
. . . external_id	string	External identifier of the parent zone.
. . group_parent	object	Parent concept/group information.
. . . id	integer	Unique identifier for the parent concept.
. . . type	string	Entity type (`CONCEPT`).
. . . display_type	string	Display name for the entity type.
. . . name	string	Name of the parent concept.
. . . code	string	Unique code of the parent concept.
. . . external_id	string	External identifier of the parent concept.
. . children	array	Child locations. Returned when `includeChildren=true`.
. . . id	integer	Unique identifier for the child location.
. . . type	string	Entity type (`STORE`, `ZONE`, `CONCEPT`).
. . . display_type	string	Display name for the entity type.
. . . name	string	Name of the child location.
. . . code	string	Unique code of the child location.
. . . external_id	string	External identifier of the child location.
. . . isOrgUnit	boolean	Whether this is an organization unit.
. . child_count	integer	Total child location count.

Error and warning codes

Code	Type	Description
INVALID_LOCATIONS_Q_FORMAT	Error	Invalid `q` format. Use `field:value` pairs separated by commas.
ENTITY_CODES_MAX_30_EXCEEDED	Error	`entityCodes` contains more than 30 codes.
INVALID_LOCATIONS_SORT_BY	Error	Invalid `sortBy`. Use `entityCode`, `name`, or `lastUpdated`.
INVALID_LOCATIONS_SORT_ORDER	Error	Invalid `sortOrder`. Use `ASC` or `DESC`.
LOCATIONS_LIMIT_OUT_OF_RANGE	Error	`limit` must be between 1 and 100.
LOCATIONS_OFFSET_NEGATIVE	Error	`offset` cannot be negative.
LOCATIONS_CHILDREN_LIMIT_OUT_OF_RANGE	Error	`childrenLimit` must be between 1 and 100.
LOCATIONS_CHILDREN_OFFSET_NEGATIVE	Error	`childrenOffset` cannot be negative.
INCLUDE_CHILDREN_REQUIRES_SINGLE_ENTITY_CODE	Warning	`includeChildren` requires exactly one code in `entityCodes`.