Add Concepts in Bulk

Time	Status	User Agent
Retrieving recent requests…

Create up to 100 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.

Example request

curl -X POST "https://{host}/v2/locations/concepts?inheritLocale=false" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "concept-retail",
      "name": "Retail Concept",
      "groupParentCode": "concept-root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Retail channel concept",
      "isActive": true,
      "externalIds": {"erpId": "ERP-C-001"},
      "customFields": {"conceptcf1": "value1"}
    }
  ]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/concepts?inheritLocale=false' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQCJleHAiOTEZdW7eAj_5ITFRQaHlvzLNoMfNCZP70deZeUGOy6tssRXIh043D_6pOrt1APKgQdxdxqUt8MrWmICfHEHHkzX6inaPdW6vbjn89rZVGfIjfMKkFUAVaNeLbPJJtOIfMTWoKbKrB6HDm6i5NgkYLVusL_C9Qmq3mMtivzwLjo0ufIL46mMot9JQ' \
--data '[
    {
      "code": "concept-retail1",
      "name": "Retail Concept1",
      
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Retail channel concept",
      "isActive": true,
      "externalIds": {"erpId": "ERP-C-001"},
      "customFields": {"conceptcf1": "value1"}
    }
  ]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/concepts?inheritLocale=false' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWap4g4OWCn56arcY7pGTyjw' \
--data '[
    {
        "code": "concept-retail5",
        "name": "concept retail5",
        "groupParentCode": "root",
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "description": "Retail channel concept",
        "isActive": true,
        "customFields": {
            "conceptcf1": "value1"
        }
    }
]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/concepts?inheritLocale=false' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQiatw6pIDUBihK
--data '[
    {
        "code": "concept-retail6",
        "name": "conceptretail6",
        "groupParentCode": "root",
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "description": "Retail channel concept",
        "isActive": true,
        "externalIds": {
            "erpId": "ERP-C-005"
        },
        "customFields": {
            "conceptcf1": "value1"
        }
    }
]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/concepts?inheritLocale=true' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWiatw6pIDUBihKKbkzY4tLIdWw' \
--data '[
    {
        "code": "concept-retail7",
        "name": "conceptretail7",
        "groupParentCode": "root",
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "description": "Retail channel concept",
        "isActive": true,
        "externalIds": {
            "erpId": "ERP-C-006"
        },
        "customFields": {
            "conceptcf1": "value1"
        }
    }
]'

Prerequisites

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 100 items per request.

Field	Type	Required	Description
`code`	string	Required	Unique code for the concept 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 concept. Accepts letters, digits, underscores, and spaces. Cannot equal `root` (any case). Max 100 characters. Case-insensitive.
`groupParentCode`	string	Optional	Code of the parent concept this concept belongs to. When provided, it 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` when omitted.
`isOrgUnit`	boolean	Optional	Whether this concept acts as an organizational unit. When omitted, the field is not set. If you pass `true`, make sure `IS_OU_ENABLED` is enabled for your org, if it isn't, the request fails with error. To get this enabled, raise a ticket to the PST team.
`externalIds`	object	Optional	Object containing key-value pairs of external identifiers for the concept (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 concept (for example, `{"fieldName": "value"}`). Keys must match custom fields configured for the org (matched case-insensitively).

API Quick Reference

{{https://{host}/v2/locations/concepts}}
└─ {{locations}}
├─ {{addConcepts}}({{CreateConceptRequest}}) -> {{BulkResponse}}
├─ {{CreateConceptRequest}} []
│   ├─ {{code}} (string, required)
│   ├─ {{name}} (string, required)
│   ├─ {{groupParentCode}} (string)
│   ├─ {{language}} (string, conditional)
│   ├─ {{currency}} (string, conditional)
│   ├─ {{timezone}} (string, conditional)
│   ├─ {{description}} (string)
│   ├─ {{isActive}} (boolean)
│   ├─ {{isOrgUnit}} (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": 75251060,
      "result": {
        "code": "concept-retail",
        "name": "Retail Concept",
        "description": "Retail channel concept",
        "isActive": true,
        "externalIds": {"erpId": "ERP-C-001"},
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "groupParentCode": "concept-root",
        "customFields": {"conceptcf1": "value1"}
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251165,
            "result": {
                "code": "concept-retail1",
                "name": "Retail Concept1",
                "description": "Retail channel concept",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-C-001"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "customFields": {
                    "conceptcf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251176,
            "result": {
                "code": "concept-retail5",
                "name": "concept retail5",
                "description": "Retail channel concept",
                "isActive": true,
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "groupParentCode": "root",
                "customFields": {
                    "conceptcf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251181,
            "result": {
                "code": "concept-retail6",
                "name": "conceptretail6",
                "description": "Retail channel concept",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-C-005"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "groupParentCode": "root",
                "customFields": {
                    "conceptcf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251186,
            "result": {
                "code": "concept-retail7",
                "name": "conceptretail7",
                "description": "Retail channel concept",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-C-006"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "groupParentCode": "root",
                "customFields": {
                    "conceptcf1": "value1"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 75251062,
      "result": {
        "code": "concept-retail",
        "name": "Retail Concept",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "groupParentCode": "concept-root"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "concept-retail",
        "name": "Retail Concept Duplicate",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "groupParentCode": "concept-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 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
`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 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 `externalIds` keys or values. 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 `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.
`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.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalIds` 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.
`SERVICE_CALL_FAILED`	1213	Error	The concept couldn't be created because the ID generation service or authentication service returned an error. Retry the request. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.
`OU_CANNOT_BE_ENABLED`	1226	Error	OU cannot be enabled for this concept as org level configuration is not set