Add Zones in Bulk

Time	Status	User Agent
Retrieving recent requests…

Create up to 100 zones in a single request. Each zone is validated and persisted independently; a failure in one item doesn't block the others. The response reflects the outcome of each item individually, and the HTTP status reflects the overall result: 201 If all items succeeded, 207 If some failed, or 400 If all failed.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/locations/zones' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQiOiJ-mgebTf2bDNTavfeQ' \
--data '[
    {
      "code": "zone-north1",
      "name": "North Zone1",
      "areaParentCode": "root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Northern region zone",
      "isActive": true,
      "externalIds": {"erpId": "ERP-Z-002"},
      "customFields": {"zonecf1": "value1"}
    }
  ]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/zones?inheritLocale=false' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQi-mgebTf2bD' \
--data '[
    {
      "code": "zone-north2",
      "name": "North Zone2",
      "areaParentCode": "root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Northern region zone",
      "isActive": true,
      "externalIds": {"erpId": "ERP-Z-003"},
      "customFields": {"zonecf1": "value1"}
    }
  ]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/zones?inheritLocale=true' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWEmRNpf-mgebTf2bDNTav' \
--data '[
    {
      "code": "zone-north3",
      "name": "North Zone3",
      "areaParentCode": "root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Northern region zone",
      "isActive": true,
      "externalIds": {"erpId": "ERP-Z-004"},
      "customFields": {"zonecf1": "value1"}
    }
  ]'

Prerequisites

The parent zone (areaParentCode) must exist and be active in the org before creating zones.
When inheritLocale is false (the default), the org must have the specified language, currency, and timezone values configured.

Query parameters

Field	Type	Required	Description
`inheritLocale`	boolean	Optional	When `true`, a zone inherits `language`, `currency`, and `timezone` from its parent zone if those fields are not provided in the request. If the parent zone also lacks locale settings, the request fails. Defaults to `false`.

Body parameters

Pass a JSON array of zone objects. Maximum 100 items per request.

Field	Type	Required	Description
`code`	string	Required	Unique code for the zone in the org. Accepts only lowercase letters, digits, periods (`.`), underscores (`_`), and hyphens (`-`). Must start with a lowercase letter or digit. Max 50 characters.
`name`	string	Required	Unique name for the zone. Accepts letters, digits, underscores, and spaces. Cannot equal `root` (any case). Max 100 characters. Case-insensitive.
`areaParentCode`	string	Required	Code of the parent zone this zone belongs to. Must be an existing active zone in the org.
`language`	string	Conditional	IETF BCP 47 language code for the zone (for example, `en-IN`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`currency`	string	Conditional	ISO 4217 currency code for the zone (for example, `INR`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`timezone`	string	Conditional	IANA timezone name for the zone (for example, `Asia/Kolkata`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`description`	string	Optional	Free-text description of the zone.
`isActive`	boolean	Optional	Whether the zone is active. Defaults to `true` when omitted.
`externalIds`	object	Optional	Object containing key-value pairs of external identifiers for the zone (for example, `{"erpId": "ERP-001"}`). Maximum five entries. Keys and values must be non-blank and no longer than 200 characters each. Values must be unique within the request and not already assigned to another entity in the org.
`customFields`	object	Optional	Object containing custom field key-value pairs for the zone (for example, `{"fieldName": "value"}`). Keys must match custom fields configured for the org (matched case-insensitively).

API Quick Reference

{{https://{host}/v2/locations/zones}}
└─ {{locations}}
├─ {{addZones}}({{CreateZoneRequest}}) -> {{BulkResponse}}
├─ {{CreateZoneRequest}} []
│   ├─ {{code}} (string, required)
│   ├─ {{name}} (string, required)
│   ├─ {{areaParentCode}} (string, required)
│   ├─ {{language}} (string, conditional)
│   ├─ {{currency}} (string, conditional)
│   ├─ {{timezone}} (string, conditional)
│   ├─ {{description}} (string)
│   ├─ {{isActive}} (boolean)
│   ├─ {{externalIds}} (object)
│   │   └─ {{<key>}} (string)
│   └─ {{customFields}} (object)
│       └─ {{<key>}} (string)
└─ {{BulkResponse}}
├─ {{response}} []
│   ├─ {{entityId}} (integer)
│   ├─ {{result}} (object)
│   ├─ {{errors}} []
│   │   ├─ {{code}} (integer)
│   │   ├─ {{message}} (string)
│   │   └─ {{status}} (boolean)
│   └─ {{warnings}} []
│       ├─ {{code}} (integer)
│       ├─ {{message}} (string)
│       └─ {{status}} (boolean)
├─ {{totalCount}} (integer)
└─ {{failureCount}} (integer)

Example response

{
    "response": [
        {
            "entityId": 75251203,
            "result": {
                "code": "zone-north1",
                "name": "North Zone1",
                "description": "Northern region zone",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-Z-002"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "areaParentCode": "root",
                "customFields": {
                    "zonecf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251204,
            "result": {
                "code": "zone-north2",
                "name": "North Zone2",
                "description": "Northern region zone",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-Z-003"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "areaParentCode": "root",
                "customFields": {
                    "zonecf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251205,
            "result": {
                "code": "zone-north3",
                "name": "North Zone3",
                "description": "Northern region zone",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-Z-004"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "areaParentCode": "root",
                "customFields": {
                    "zonecf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 75251058,
      "result": {
        "code": "zone-north",
        "name": "North Zone",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "areaParentCode": "zone-root"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "zone-north",
        "name": "North Zone Duplicate",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "areaParentCode": "zone-root"
      },
      "errors": [
        {
          "status": false,
          "code": 1220,
          "message": "Code already Exists Orgs"
        }
      ],
      "warnings": [
        {
          "status": false,
          "code": 1215,
          "message": "Invalid isActive specified, setting to default"
        }
      ]
    }
  ],
  "totalCount": 2,
  "failureCount": 1
}

Response parameters

Field	Type	Description
`response`	array	One entry per input item, in the same order as the request.
`.entityId`	integer	System-assigned ID of the created zone. Absent when the item failed.
`.result`	object	Echo of the submitted zone object. Always present for all items, whether the item succeeded or failed.
`.errors`	array	Errors for this item. Empty when the item succeeded.
`..code`	integer	Numeric error code.
`..message`	string	Error message.
`..status`	boolean	Status flag for the error entry.
`.warnings`	array	Non-fatal warnings for this item.
`..code`	integer	Numeric warning code.
`..message`	string	Warning message.
`..status`	boolean	Status flag for the warning entry.
`totalCount`	integer	Total number of items in the request.
`failureCount`	integer	Number of items that failed to create.

Error & warning codes

Code	Error number	Type	Description
`BULK_REQUEST_LIMIT_EXCEEDED`	1246	Error	The request contains more than 100 items. Maximum allowed is 100. HTTP 400.
`CODE_NOT_SET`	1247	Error	`code` is missing or blank. HTTP 400.
`NAME_NOT_SET`	1200	Error	`name` is missing or blank. HTTP 400.
`REGEX_MATCH_FAILED`	1219	Error	`code` or `name` failed format validation. HTTP 400.
`NAME_LENGHT_NOT_VALID`	1218	Error	`code` exceeds 50 characters. HTTP 400.
`NAME_LENGTH_EXCEEDS_LIMIT`	1264	Error	`name` exceeds 100 characters. HTTP 400.
`NAME_ROOT_NOT_ALLOWED`	1210	Error	`name` cannot equal `root` (any case). HTTP 400.
`CODE_ALREADY_EXISTS_ORG`	1220	Error	A zone with this code already exists in the org, or a duplicate `code` appears in the same request. HTTP 400.
`NAME_ALREADY_EXISTS_ORG`	1206	Error	A zone with this name already exists in the org. HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	A required field is missing. Applies to `areaParentCode`, locale fields (when `inheritLocale` is `false`), and blank `externalIds` keys or values. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	A field value is invalid. Applies to an `areaParentCode` that does not match an active zone, locale values not enabled for the org, more than five `externalIds` entries, and invalid `customFields` key names. HTTP 400.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalIds` values are already assigned to another entity in the org. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalIds` values in the same request. HTTP 400.
`EXTERNAL_ID_KEY_TOO_LONG`	1261	Error	An `externalIds` key exceeds 200 characters. HTTP 400.
`EXTERNAL_ID_VALUE_TOO_LONG`	1262	Error	An `externalIds` value exceeds 200 characters. HTTP 400.
`ORG_ENTITY_TYPE_LIMIT_EXCEEDED`	1225	Error	The org has reached its configured limit for zones. HTTP 400.
`SERVICE_CALL_FAILED`	1213	Error	The zone couldn't be created because the ID generation service returned an error. Retry the request. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.