Custom attributes

A custom attribute is a field your organisation adds to a record: a cost centre code, a pay band, a compliance date. A definition says what the field is and which records it applies to. A value is that field’s data on one record.

All paths are under https://{tenant}.flowstate.inc/api/v1. Custom attributes are live data; scenarioId is ignored.

{entity} is employees, contractors, vacancies, teams or projects. There :id accepts a Flowstate id or the record’s externalId. :definitionId is always the definition’s Flowstate id.

Definitions are also managed in the app at Settings → Resourcing → Custom Attributes.

The definition object

The value object

GET /{entity}/:id on employees, contractors, vacancies, teams and projects includes the record’s values as customAttributes, so you rarely need the value list endpoint.

List definitions

GET /org/:orgId/custom-attributes

curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/custom-attributes?entityType=EMPLOYEE&limit=100" \
  -H "Authorization: Bearer private_..."

{
  "data": [
    {
      "id": "clx2d3e4f5g6h7i8j9k0l1m2n",
      "name": "Cost Centre Code",
      "attributeKey": "cost_centre_code",
      "fieldType": "STRING",
      "entityTypes": ["EMPLOYEE", "CONTRACTOR"],
      "description": "Finance cost centre code.",
      "isRequired": false,
      "isActive": true,
      "sortOrder": 0,
      "selectOptions": null,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 100, "total": 1, "hasNextPage": false }
}

Retrieve a definition

GET /org/:orgId/custom-attributes/:definitionId

Returns the definition object.

Create a definition

POST /org/:orgId/custom-attributes

Without attributeKey, one is made from name: accents dropped, lower-cased, every run of other characters replaced by _. "Cost Centre Code" becomes cost_centre_code. If that key is taken, _2, _3 and so on is added.

Create SELECT attributes in the app, where their options are set.

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/custom-attributes" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cost Centre Code",
    "fieldType": "STRING",
    "entityTypes": ["EMPLOYEE", "CONTRACTOR"],
    "description": "Finance cost centre code."
  }'

201 Created with the definition object.

Update a definition

PATCH /org/:orgId/custom-attributes/:definitionId

Takes name, entityTypes, description, isRequired, isActive and sortOrder, all optional. attributeKey is ignored.

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/custom-attributes/clx2d3e4f5g6h7i8j9k0l1m2n" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "isRequired": true, "entityTypes": ["EMPLOYEE", "CONTRACTOR", "VACANCY"] }'

200 OK with the updated definition.

Delete a definition

DELETE /org/:orgId/custom-attributes/:definitionId

Deletes the definition and every value set with it, on every record. This can’t be undone.

{ "data": { "id": "clx2d3e4f5g6h7i8j9k0l1m2n", "deleted": true } }

List a record’s values

GET /org/:orgId/{entity}/:id/custom-attributes

Returns every value on the record, in definition sortOrder. Not paginated.

curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/HR-10442/custom-attributes" \
  -H "Authorization: Bearer private_..."

{
  "data": [
    {
      "id": "clx8v9w0x1y2z3a4b5c6d7e8f",
      "definitionId": "clx2d3e4f5g6h7i8j9k0l1m2n",
      "entityType": "EMPLOYEE",
      "entityId": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "stringValue": "ENG-001",
      "numberValue": null,
      "dateValue": null,
      "dateRangeStart": null,
      "dateRangeEnd": null,
      "selectValue": null,
      "currencyCode": null,
      "currencyAmount": null,
      "createdAt": "2026-04-08T10:00:00.000Z",
      "updatedAt": "2026-04-08T10:00:00.000Z",
      "definition": {
        "id": "clx2d3e4f5g6h7i8j9k0l1m2n",
        "name": "Cost Centre Code",
        "attributeKey": "cost_centre_code",
        "fieldType": "STRING",
        "entityTypes": ["EMPLOYEE", "CONTRACTOR"],
        "description": "Finance cost centre code.",
        "isRequired": false,
        "isActive": true,
        "sortOrder": 0,
        "selectOptions": null,
        "createdAt": "2026-03-01T10:00:00.000Z",
        "updatedAt": "2026-03-01T10:00:00.000Z"
      }
    }
  ]
}

Set a value

PUT /org/:orgId/{entity}/:id/custom-attributes/:definitionId

Creates the value or replaces it. Send the fields for the definition’s fieldType; every value field you leave out is cleared.

The definition’s entityTypes must include the record’s type.

curl -X PUT "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/projects/JIRA-MOB/custom-attributes/clx4f5g6h7i8j9k0l1m2n3o4p" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "currencyCode": "GBP", "currencyAmount": 125000 }'

200 OK with the value object.

Clear a value

DELETE /org/:orgId/{entity}/:id/custom-attributes/:definitionId

{ "data": { "definitionId": "clx2d3e4f5g6h7i8j9k0l1m2n", "entityId": "clx1a2b3c4d5e6f7g8h9i0j1k", "deleted": true } }

Sync a field from your HR system

1. GET /custom-attributes?entityType=EMPLOYEE and find the definition by attributeKey. Create it if it’s missing.
2. For each person, PUT /employees/{externalId}/custom-attributes/{definitionId} with the value.
3. For a person whose field is now empty, DELETE the value.

Functional groups and positions

Values on functional groups and positions are set under the functional groups resource. See Functional groups.

Errors

See Errors for the error body.