Skip to content

Status Identifiers

A Status is the main entity for the Stativate Plattform and therefore the main API operations are targeting one specific status. To make the API integration as simple as possible there are two different ways to target a specific status. You can either use the status id or a status key.

A list of all the identifiers for a status can be read using the list status endpoint. This will return all status you are an owner of. The response format will look like:

[
  {
    "statusId": "A0aEMOe6n7qMhcExample",
    "statusKey": "statuskey-1-example",
    "shareId": "xkwd5e",
    "name": "Status One"
  }
]

Status ID

Every status automatically gets a unique id when created. This id is meant to be used with endpoints that require a :statusId.

Status ID tutorial

For details on how to use a statusId, see the update status value tutorial.

Using the statusId is usually a good choice to update a static status. Imagine you want to automatically update a status showing one kpi of your business. The status creation will only happen once and therefore might as well be done manually. The updates can then be done by API using the statusId.

Advantages using statusId

For use-cases with a small number of status that need no dynamic creation, server-generated ids offer a simple way to manually maintain the status and send just value updates via API.

A statusId is unique throughout the entire Stativate platform, so there will never be two status with the same statusId. That means a status also has the same statusId for all users allowed to access it. For use-cases where multiple users access the same status via API, the statusId is the identifier to use.

Possible downsides using statusId

In some cases a server-generated statusId makes things harder than neccessary to integrate.

In use-cases with dynamically created status, the handling of statusId might require id mapping. Data source entities usually have their own identifiers. When a status for each record from a data source is created that would mean every mapping between statusId and the source records id would have to be saved to know what status to update in the next run.

Status Key

For use-cases with dynamic status creation, the Stativate API can be used with IDs defined on client-side. Those client-generated IDs are called status keys in the API. A status key is simply an id for a status that you can define yourself.

Status key tutorial

For details on how to use a statusKey, see the create or update status tutorial.

Advantages using statusKey

There is no need to maintain a mapping between data source ids and the Stativate status IDs. Status can simply be used with identifiers coming from the data source.

Possible downsides using statusKey

Stativate does not ensure uniqueness for status keys across user accounts, so multiple users can not use the same status based on a status key.

You will have to ensure uniqueness yourself, otherwise you will overwrite your existing status when unintentionally using the same status key.