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


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.