Accounts

Multiple Operators can be associated with an EVRYTHNG Platform account. Through use of the Roles API each can be given the appropriate permissions and levels of scope necessary for their role in the application.

From each Operator's perspective, they each have a unique access to each account they are associated with, and are granted an Operator API Key for each.

API Status
General Availability:
/accounts
/accounts/:accountId
/accounts/:accountId/shortDomains
/accounts/:accountId/domains

Jump To ↓

AccountDocument Data Model
AccessDocument Data Model
Read all Accounts
Read an Account
Update an Account
Update Account Configuration
Read Account Accesses
Read an Account Access
Read all Short Domains
Read all Domains

AccountDocument Data Model

.name (string)
    Friendly name of this resource. Must be between 1 and 30
    characters.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.customFields (object)
    Object of case-sensititve key-value pairs of custom fields
    associated with the resource.

.imageUrl (string)
    The account Dashboard logo.

.tfaRequired (boolean, read-only)
    Whether two-factor authentication is required for this
    account.

.defaultUrl (string)
    Invalid GS1 scans will redirect to this URL.
    
.configuration (object)
	Object containing account related configuration.

{
  "type": "object",
  "description": "An object representing a Platform account.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource. Must be between 1 and 30 characters.",
      "minLength": 1,
      "maxLength": 30
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "imageUrl": {
      "type": "string",
      "description": "The account Dashboard logo."
    },
    "tfaRequired": {
      "type": "boolean",
      "description": "Whether two-factor authentication is required for this account.",
      "readOnly": true
    },
    "defaultUrl": {
      "type": "string",
      "description": "Invalid GS1 scans will redirect to this URL."
    },
    "configuration": {
      "type": "object",
      "description": "Object containing account related configuration."
    }  
  },
  "x-filterable-fields": [ "name" ]
}

{
  "id": "UhpHrg39QCy9dsSddN8xhwnb",
  "createdAt": 1471862431010,
  "customFields": {
    "region": "en-gb"
  },
  "updatedAt": 1510593794364,
  "name": "Example Account",
  "imageUrl": "https://avatars1.githubusercontent.com/u/5732010?v=4&s=460",
  "tfaRequired": true,
  "defaultUrl": "https://developers.evrythng.com",
  "configuration": {
    "uniqueIdentifiers": {
      "products": [
        "gs1:01",
        "gs1:22"
      ]
    }
  }
}

📘
Account Configuration API
See the Account Configuration section for full details on the account configuration functionality.

Filterable Fields

This resource type can be filtered using the following fields and operators.

Field	Type	Operators
`name`	String	`=`

AccessDocument Data Model

The AccessDocument contains role and authentication information for an account.

.account (string, read-only)
    The account ID.

.apiKey (string, read-only)
    The account's Operator API key.

.id (string, read-only)
    The ID of this resource.

.operator (string, read-only)
    The account's user ID.

.role (string)
    The ID of the currently assigned role.

{
  "type": "object",
  "description": "An object representing an account's access record.",
  "properties": {
    "account": {
      "type": "string",
      "description": "The account ID.",
      "readOnly": true,
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "apiKey": {
      "type": "string",
      "description": "The account's Operator API key.",
      "readOnly": true,
      "pattern": "^[abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789]{80}$"
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "operator": {
      "type": "string",
      "description": "The account's user ID.",
      "readOnly": true,
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "role": {
      "type": "string",
      "description": "The ID of the currently assigned role.",
      "minLength": 4,
      "maxLength": 24
    }
  }
}

{
  "id": "57bad69fc18104025b292da8",
  "account": "UhpHrg39QCy9dsSddN8xhwnb",
  "operator": "UEp4rDGsnpCAF6xABbys5Amc",
  "apiKey": "AGiWrH5OteA4aHiMFiwnwF08p3PQvPIr9GJX...",
  "role": "admin"
}

Read All Accounts

Read an array of all accounts visible to an Operator with their API key.

GET /accounts
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts'

operator.sharedAccount().read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UhpHrg39QCy38dht93kiuwnb",
    "createdAt": 1471862430889,
    "customFields": {},
    "updatedAt": 1471862431010,
    "name": "Main Account",
    "tfaRequired": false
  }
]

Read an Account

Read an account by its ID by sending a GET request to the /accounts/:accountId endpoint.

GET /accounts/:accountId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts/UhpHrg39QCy9dsSddN8xhwnb'

const accountId = 'UhpHrg39QCy9dsSddN8xhwnb';

operator.sharedAccount(acccountId).read()
  .then(console.log)

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "id": "UhpHrg39QCy9dsSddN8xhwnb",
  "createdAt": 1471862430889,
  "customFields": {},
  "updatedAt": 1471862431010,
  "name": "Main Account",
  "tfaRequired": false,
  "configuration": {
    "uniqueIdentifiers": {
      "products": [
        "gs1:01",
        "gs1:22"
      ]
    }
  }
}

Update an Account

Update an account with new user information or custom fields by sending an AccountDocument with only the fields to be updated. For example, the name, or imageUrl which will be displayed in the Dashboard.

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://$EVT_API_DOMAIN/accounts/UhpHrg39QCy38dht93kiuwnb'
  -d '{ 
    "imageUrl": "https://example.com/image.png",
    "configuration": {
      "uniqueIdentifiers": {
        "products": [
          "gs1:01",
          "gs1:22"
        ]
      }
    }
  }'

const accountId = 'UhpHrg39QCy38dht93kiuwnb';
const payload = { 
  imageUrl: 'https://example.com/image.png',
  configuration: {
    uniqueIdentifiers: {
      products: [
        "gs1:01",
        "gs1:22"
      ]
    }
  }
};

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": "Updated Account Name",
  "imageUrl": "https://example.com/image.png",
  "tfaRequired": false,
  "configuration": {
    "uniqueIdentifiers": {
      "products": [
        "gs1:01",
        "gs1:22"
      ]
    }
  }
}

Update Account Configuration

🚧
Deprecation
There's a new way of handling account configurations!
Check out the new Account configurations API.
Managing account configurations via accounts/:accountID will be deprecated on September 30th 2021.

Unique identifiers

Follow the syntax below for updating unique identifier account configuration.

Products

A single unique identifier per Product is supported.

Configuration is an array of identifier keys in configuration.uniqueIdentifiers.products. 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.

Configuration is an array of objects in configuration.uniqueIdentifiers.thngs. 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 configuration:

"uniqueIdentifiers": {
  "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.

Read Account Accesses

Read all available accesses to an account. This translates to the list of Operators who are listed as team members.

GET /accounts/:accountId/accesses
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts/UhpHrg39QCy9dsSddN8xhwnb/accesses'

const accountId = 'UGYYcfmsCy9nQtRwwYcgnfKb';

operator.sharedAccount(accountId).access()
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "57bad69fc18104025b292da8",
    "account": "UhpHrg39QCy9dsSddN8xhwnb",
    "operator": "UEp4rDGsnpCAF6xABbys5Amc",
    "apiKey": "AGiWrH5OteA4aHiM...",
    "role": "admin"
  },
  {
    "id": "58c01cd3f0c7822c00373c5f",
    "account": "UhpHrg39QCy9dsSddN8xhwnb",
    "operator": "UgsmFRw7yQV8GPgKBKTbWhhb",
    "apiKey": "6C2zBd8aKr5HJexd...",
    "role": "admin"
  }
]

Read an Account Access

Read a single account access by ID.

GET /accounts/:accountId/accesses/:accessId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts/UhpHrg39QCy9dsSddN8xhwnb/accesses/57bad69fc18104025b292da8'

const accountId = 'UGYYcfmsCy9nQtRwwYcgnfKb';
const accessId = '57bad69fc18104025b292da8';

operator.sharedAccount(accountId).access(accessId)
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "57bad69fc18104025b292da8",
  "account": "UhpHrg39QCy9dsSddN8xhwnb",
  "operator": "UEp4rDGsnpCAF6xABbys5Amc",
  "apiKey": "AGiWrH5OteA4aHiM...",
  "role": "admin"
}

Read all Short Domains

Read all short domains available to an account.

GET /accounts/:accountId/shortDomains
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts/UhpHrg39QCy9dsSddN8xhwnb/shortDomains'

const accountId = 'UGYYcfmsCy9nQtRwwYcgnfKb';

operator.sharedAccount(accountId).shortDomain()
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  "tn.gg"
]

DomainDocument Data Model

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.id (string, read-only)
    The ID of this resource.

.accountId (string)
    The account this domain belongs to.

.domain (string)
    The domain URL.

{
  "type": "object",
  "description": "A single account domain entry.",
  "properties": {
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "accountId": {
      "type": "string",
      "description": "The account this domain belongs to.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "domain": {
      "type": "string",
      "description": "The domain URL."
    }
  }
}

{
  "createdAt": 1519385011833,
  "updatedAt": 1519385011833,
  "id": "5a8ff9b3a1b3f60013492de7",
  "accountId": "UnFQtmpUMtQBY8wRaEystb5h",
  "domain": "ratqa.tn.gg"
}

Read all Domains

GET /accounts/:accountId/domains
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accounts/UnFQtmpUMtQBY8wRaEystb5h/domains'

const accountId = 'UGYYcfmsCy9nQtRwwYcgnfKb';

operator.sharedAccount(accountId).domain()
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "createdAt": 1519385011833,
    "updatedAt": 1519385011833,
    "id": "5a8ff9b3a1b3f60013492de7",
    "accountId": "UnFQtmpUMtQBY8wRaEystb5h",
    "domain": "ratqa.tn.gg"
  }
]

Accounts

AccountDocument Data Model

📘
Account Configuration API

Filterable Fields

AccessDocument Data Model

Read All Accounts

Read an Account

Update an Account

Update Account Configuration

🚧
Deprecation

Unique identifiers

Products

Thngs

Read Account Accesses

Read an Account Access

Read all Short Domains

DomainDocument Data Model

Read all Domains

AccountDocument Data Model

📘Account Configuration API

Filterable Fields

AccessDocument Data Model

Read All Accounts

Read an Account

Update an Account

Update Account Configuration

🚧Deprecation

Unique identifiers

Products

Thngs

Read Account Accesses

Read an Account Access

Read all Short Domains

DomainDocument Data Model

Read all Domains

📘
Account Configuration API

🚧
Deprecation