Time	Status	User Agent
Retrieving recent requests…

Add concepts in bulk

Create up to 50 concepts in a single request. Each concept 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.

Note: Only users with the ADMIN_USER entity type can call this endpoint. Requests from non-admin users return HTTP 400 for every item.

Example request

curl -X POST "https://{host}/v2/locations/concepts" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "concept-north",
      "name": "North Concept",
      "groupParentCode": "concept-root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Northern region concept",
      "isActive": true
    }
  ]'

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).
The authenticated user must have the ADMIN_USER entity type.
When inheritLocale is false (the default), the org must have the specified language, currency, and timezone values configured.
When inheritLocale is true, a valid groupParentCode must be provided so that locale settings can be inherited from the parent concept.

Query parameters

Field	Type	Required	Description
`inheritLocale`	boolean	Optional	When `true`, a concept inherits `language`, `currency`, and `timezone` from its parent concept. A valid `groupParentCode` must be provided for inheritance to work. If the parent concept also lacks locale settings, the request fails. Defaults to `false`.

Body parameters

Pass a JSON array of concept objects. Maximum 50 items per request.

Field	Type	Required	Description
`code`	string	Required	Unique code for the concept in the org. Accepts lowercase letters, digits, periods (`.`), underscores (`_`), and hyphens (`-`). Must start with a lowercase letter or digit. Max 50 characters.
`name`	string	Required	Display name for the concept. Accepts letters, digits, underscores, and spaces. Cannot equal `root` (any case).
`groupParentCode`	string	Optional	Code of the parent concept this concept belongs to. When provided, must be an existing active concept in the org. Omit to create a root-level concept.
`language`	string	Conditional	IETF BCP 47 language code for the concept (for example, `en-IN`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`currency`	string	Conditional	ISO 4217 currency code for the concept (for example, `INR`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`timezone`	string	Conditional	IANA timezone name for the concept (for example, `Asia/Kolkata`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`description`	string	Optional	Free-text description of the concept.
`isActive`	boolean	Optional	Whether the concept is active. Defaults to `true`. A warning is returned when this field is omitted.
`isOrgUnit`	boolean	Optional	Whether this concept acts as an organizational unit. When omitted, the field is not set.
`externalId`	array	Optional	External IDs for the concept. Max five entries. Each value must be non-blank, unique within the request, and not already assigned to another entity in the org.
`attributes`	object	Optional	Custom field values for the concept. Keys must match fields configured for the org (matched case-insensitively).

Example response

{
  "response": [
    {
      "entityId": 50826309,
      "result": {
        "code": "concept-north",
        "name": "North Concept",
        "description": "Northern region concept",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "groupParentCode": "concept-root"
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 50826311,
      "result": {
        "code": "concept-north",
        "name": "North Concept",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "concept-north",
        "name": "North Concept Duplicate",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata"
      },
      "errors": [
        {
          "status": false,
          "message": "Code already Exists Orgs",
          "code": 1220
        }
      ],
      "warnings": []
    }
  ],
  "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 concept. Absent when the item failed.
`.result`	object	Echo of the submitted concept 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
`NOT_AN_ADMIN_USER`	1209	Error	The authenticated user is not an admin. HTTP 400.
`BULK_REQUEST_LIMIT_EXCEEDED`	1246	Error	The request contains more than 50 items. Maximum allowed is 50. 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_ROOT_NOT_ALLOWED`	1210	Error	`name` cannot equal `root` (any case). HTTP 400.
`CODE_ALREADY_EXISTS_ORG`	1220	Error	A concept 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 concept with this name already exists in the org. HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	A required field is missing. Applies to locale fields (when `inheritLocale` is `false`) and blank `externalId` entries. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	A field value is invalid. Applies to a `groupParentCode` that does not match an active concept, locale values not enabled for the org, more than five `externalId` entries, and invalid `attributes` key names. HTTP 400.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalId` values are already assigned to another entity in the org. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalId` values in the same request. HTTP 400.
`ORG_ENTITY_TYPE_LIMIT_EXCEEDED`	1225	Error	The org has reached its configured limit for concepts. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.