Besides managing accounts and their base attributes such as name, imageUrl and the account's defaultUrl you can also define and manage account-specific configuration attributes.
This API gives you the possibility to define and manage configurations such as your account's unique identifiers settings, your custom dashboards, your labelling designations, and more.
You are still able to read all configurations at the parent Accounts API under the configuration JSON object, however, this configuration API allows you to manage each specific attribute without running the risk of deleting/editing other configuration traits unintentionally.
API Status
General Availability:
/accounts/:accountId/configuration/uniqueIdentifiers
/accounts/:accountId/configuration/bi
/accounts/:accountId/configuration/dashboards
/accounts/:accountId/configuration/consumerEngagement
/accounts/:accountId/configuration/activateApplication
/accounts/:accountId/configuration/resourceSchemas
/accounts/:accountId/configuration/epcisCaptureApp
/accounts/:accountId/configuration/brandIntegrity
AccountConfiguration Data Model
Read All Configurations
Read an Account Configuration
Add or Update an Account Configuration
Delete an Account Configuration resource
Unique identifiers
AccountConfigurationDocument Data Model
Object containing account related configuration.
.bi (AccountConfigurationBiDocument)
Configuration for Business Intelligence integrations.
.brands (array of string, max. 25)
An array of brand strings that one can find in a product
resource.
.consumerEngagmentment (AccountConfigurationConsumerEngagementDocument)
Definitions for the Amplify dashboard within the Product
Cloud.
.dashboards (array of AccountConfigurationDashboardsDocument)
Configuration of custom dashboards associated with the
account
.labels (AccountConfigurationLabelsDocument)
Labels for specific identifiers on a given resource type,
such as products.
.regions (array of AccountConfigurationRegionsDocument)
A list of regions that you use to support web applications
and the way they interact with world-wide actions on your
resources.An array of regions with specific ISO country
codes.
.resourceSchemas (AccountConfigurationResourceSchemasDocument)
Schemas associated with specific resources, such as products
or places.
.types (AccountConfigurationTypesDocument)
An array of resource type schemas for a given resource type,
such as Thngs.
.uniqueIdentifiers (AccountConfigurationUniqueIdentifiersDocument)
Object containing lists of identifier keys which are meant
to be unique for a particular entity.
{
"type": "object",
"description": "Object containing account related configuration.",
"properties": {
"bi": {
"type": "object",
"description": "Configuration for Business Intelligence integrations.",
"example": [
{
"clientCode": "FOO",
"groupIds": [10, 11],
"models": ["amplify", "core"]
}
]
},
"brands": {
"type": "array",
"description": "An array of brand strings that one can find in a product resource.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": ["The Green Brand", "The Blue Brand", "The Yellow Brand"]
},
"maxItems": 25,
"uniqueItems": true
},
"consumerEngagmentment": {
"type": "object",
"description": "Definitions for the Amplify dashboard within the Product Cloud.",
"additionalProperties": false,
"properties": {
"biDashboards": {
"type": "array",
"description": "Configuration for faceted dashboard.",
"items": {
"additionalProperties": false,
"type": "object",
"description": "Object containing configurations for each faceted dashboard.",
"properties": {
"id": {
"type": "string",
"description": "ID of the dashboard.",
"example": ["amplify::amplify_scans", "amplify::amplify_locations", "amplify::amplify_products", "amplify::amplify_technology"]
},
"name": {
"type": "string",
"description": "Name of the dashboard."
}
}
}
},
"customDashboardId": {
"type": "string",
"description": "ID of the dashboard.",
"example": "amplify::amplify_beta_nonserialized"
},
"name": {
"type": "string",
"description": "Name of the dashboard.",
"example": "All scan activity"
},
"views": {
"type": "array",
"description": "Items displayed in consumer engagement dashboard.",
"items": {
"additionalProperties": false,
"type": "object",
"description": "Configuration of item displayed in consumer engagement dashboard.",
"properties": {
"color": {
"type": "string",
"description": "Color of the item.",
"example": ["#00943d", "red"]
},
"filters": {
"type": "object",
"description": "Filters to apply to the item.",
"example": [
{
"Brand": "The Orange Brand,The Red Brand",
"Scan Country": "GB"
}
]
},
"name": {
"type": "string",
"description": "Name of the item.",
"example": []
]
}
}
}
}
}
},
"dashboards": {
"type": "array",
"description": "Configuration of custom dashboards associated with the account",
"items": {
"type": "object",
"required": ["name", "id"],
"properties": {
"name": {
"type": "string",
"example": ["Factory Activation", "Brand Protection"]
},
"id": {
"type": "string",
"example": ["activate::factory_activation_dashboard_alpha", "authenticate::brand_protection_dashboard_alpha"]
}
}
}
},
"labels": {
"type": "object",
"description": "Labels for specific identifiers on a given resource type, such as products.",
"example": [
{
"product": {
"identifiers": {
"gs1:01": [
{ "default": "Global Trade Identification Number" }
]
},
"place": {
"identifiers": {
"gs1:414": [
{
"default": "Factory",
"FR": "Usine"
}
]
}
}
}
}
]
},
"regions": {
"type": "array",
"description": "A list of regions that you use to support web applications and the way they interact with world-wide actions on your resources.An array of regions with specific ISO country codes.",
"items": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": { "type": "string" }
},
"regionName": { "type": "string" }
}
},
"example": [[ { "countries": [ "SE", "NO"],
"regionName": "Northern Europe"
}
]
]
},
"resourceSchemas": {
"type": "object",
"description": "Schemas associated with specific resources, such as products or places.",
"additionalProperties": false,
"example": [
{
"retailStore": null,
"type": "place",
"identifiers": {
"gs1:414": {
"title": "Location ID",
"type": "string",
"minLength": 2,
"maxLength": 64
}
}
}
]
},
"types": {
"type": "object",
"description": "An array of resource type schemas for a given resource type, such as Thngs.",
"example": [
{
"thngs": [
{
"type": "Batch",
"schema": "location/of/schema"
},
{
"type": "Pallet",
"schema": "location/of/schema"
},
{
"type": "Case",
"schema": "location/of/schema"
},
{
"type": "Item",
"schema": "location/of/schema"
}
]
},
{
"places": [
{
"type": "Factory",
"schema": "location/of/schema"
},
{
"type": "Warehouse",
"schema": "location/of/schema"
},
{
"type": "Distribution Centre",
"schema": "location/of/schema"
}
]
}
]
},
"uniqueIdentifiers": {
"type": "object",
"description": "Object containing lists of identifier keys which are meant to be unique for a particular entity.",
"additionalProperties": false,
"properties": {
"products": {
"type": "array",
"description": "Array of identifier keys meant to be unique for product entity. Identifiers used in product \"identifiers\" field will be concatenated in the order specified in the \"products\" array and used as unique identifier for a given product which means that user will not be able to create two products with the same unique identifiers.",
"items": { "type": "string" }
},
"thngs": {
"type": "array",
"description": "Array of identifier keys meant to be unique for thng entity.",
"items": {
"type": "object",
"description": "Identifier keys meant to be unique for thng entity.",
"additionalProperties": false,
"properties": {
"product": {
"type": "array",
"description": "Array of Product identifier keys.",
"items": {
"type": "string",
"example": ["gs1:01"]
}
},
"thng": {
"type": "array",
"description": "Array of Thng identifier keys.",
"items": {
"type": "string",
"example": ["gs1:21"]
}
}
}
}
}
}
}
}
}
TODO
Read All Configurations
To read all the existing configurations you should use the Accounts API.
Enable Configurations for your account
The configuration attribute on an account resource is not a mandatory field. Therefore, in order to make any configuration management via this API, you should make sure you first add a configuration JSON object to your account resource.
You can do that via the Accounts API as so:
PUT /accounts/:accountId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
AccountDocument (subset)
curl -i -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X PUT 'https://$API_URL/accounts/UhpHrg39QCy38dht93kiuwnb'
-d '{
"configuration": {}
}'
const accountId = 'UhpHrg39QCy38dht93kiuwnb';
const payload = {
configuration: {}
};
operator.sharedAccount(accountId).update(payload)
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "UhpHrg39QCy38dht93kiuwnb",
"createdAt": 1471862430889,
"customFields": {},
"updatedAt": 1471862431010,
"name": "Main Account",
"tfaRequired": false,
"configuration": {}
}
]
Read an Account Configuration
Read an account configuration by its ID and resource name by sending a GET request to the /accounts/:accountId/configuration/:resourceName endpoint.
GET /accounts/:accountId/configuration/uniqueIdentifers
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
curl -H "Authorization: $OPERATOR_API_KEY" \
-X GET 'https://$API_URL/accounts/UhpHrg39QCy9dsSddN8xhwnb/configuration/uniqueIdentifiers'
HTTP/1.1 200 Ok
Content-Type: application/json
{
"products": [
"gs1:01",
"gs1:22"
]
}
Add or Update an Account Configuration
Add or update account configurations by sending a PUT request to the /accounts/:accountId/configuration/:resourceName endpoint.
Remember to use the payload specified for the resourceName you want, check them out in the AccountConfiguration Data Model section above.
PUT /accounts/:accountId/configuration/uniqueIdentifiers
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
AccountDocument (subset)
curl -i -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X PUT 'https://$API_URL/accounts/UhpHrg39QCy38dht93kiuwnb/configuration/uniqueIdentifiers'
-d '{
"products": [
"gs1:01"
]
}'
HTTP/1.1 200 OK
Content-Type: application/json
{
"products": [
"gs1:01"
]
}
Delete an Account Configuration resource
You can delete an entire configuration resource by making a DELETE request to the /accounts/:accountId/configuration/:resourceName endpoint.
Caution!
Deleting the configuration resource will delete all fields within that configuration attribute, regardless of its type (object, array, string, etc).
Deleting particular fields within a configuration object is not supported.
DELETE /accounts/:accountId/configuration/uniqueIdentifiers
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
curl -i -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X DELETE 'https://$API_URL/accounts/UhpHrg39QCy38dht93kiuwnb/configuration/uniqueIdentifiers'
HTTP/1.1 204 No Content
Unique identifiers
Follow the syntax below for updating unique identifier account configuration.
Products
A single unique identifier per Product is supported.
Unique Identifiers are a list of identifier keys for products or thngs. For example, if your array consists of ["gs1:01", "gs1:22", "gs1:8003"], then any product that has one or more of those identifier keys will have a unique identifier value associated with it.
The unique identifier is additive in array order, so if the product has multiple qualifying identifier keys then the unique identifier for the product will be a pipe-delimited concatenation of these values, e.g. gs1:01:1234|gs1:22:5678.
Attempting to create or update another Product with the same unique identifier will result in a 409 conflict error response.
Thngs
Multiple unique identifiers per Thng are supported.
Each object represents a potential matching unique identifier on a Thng, so the maximum possible number of unique identifiers for a given Thng is equal to the number of objects in the array.
Thng identifier uniqueness supports concatenation of the Thng's Product identifier and one or more Thng identifiers.
For example, consider the following payload:
{
"thngs": [
{
"product":["gs1:01"],
"thng":["gs1:21"]
},
{
"thng":["gs1:250"]
}
]
}
If a Thng has the following identifiers:
gs1:21:10230456, gs1:250:AxBCxDEF
And its associated Product has the following identifier:
gs1:01:90870654
Then two unique identifier values will be created:
gs1:01:90870654|gs1:21:10230456, gs1:250:AxBCxDEF
Attempting to create or update another Thng with the same gs1:250 value, or the same combination of gs1:01 (on the Product) and gs1:21 (on the Thng) values will result in a 409 conflict error response
The combination of a gs1:01 identifier key on a Product and a gs1:21 identifier key on a Thng is also known as a Serialized GTIN, or SGTIN. This data can also be embedded in an RFID tag as an Electronic Product Code, or EPC.