Home Documentation Workflow Management Service Workflow Integration Guides Workflow Reference Data and Managed Data

Workflow Reference Data and Managed Data

Last updated: April 2026

The Workflow Management Service provides two related data capabilities:

  • Reference Data for lookup-style values used in forms and selections
  • Managed Data for reusable business records that need their own lifecycle and permissions

Use this guide to choose the right API and understand the main endpoints for each.

When to Use Reference Data

Use reference data when you need reusable option lists such as:

  • Countries
  • Sample categories
  • Status selections
  • Hierarchical selections such as parent and child lookups

Reference data is exposed under:

/tenant/{tenantId}/v1/ReferenceData/{dataType}

Reference Data Endpoints

Create Reference Data

POST /tenant/{tenantId}/v1/ReferenceData/sampleTypes
Authorization: Bearer {token}
Content-Type: application/json

{
  "default": ["Food", "Water", "Feed"],
  "workspaceSelections": {
    "workspace-a": ["Food", "Water"],
    "workspace-b": ["Feed"]
  },
  "isActive": true
}

Get All Reference Data for a Type

GET /tenant/{tenantId}/v1/ReferenceData/sampleTypes?activeOnly=true
Authorization: Bearer {token}

Get a Specific Reference Data Entry

GET /tenant/{tenantId}/v1/ReferenceData/sampleTypes/{id}
Authorization: Bearer {token}

Update a Reference Data Entry

PUT /tenant/{tenantId}/v1/ReferenceData/sampleTypes/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "default": ["Food", "Water", "Feed", "Soil"],
  "isActive": true
}

Delete a Reference Data Entry

DELETE /tenant/{tenantId}/v1/ReferenceData/sampleTypes/{id}
Authorization: Bearer {token}

Hierarchical Selections

For hierarchical data, use:

  • GET /tenant/{tenantId}/v1/ReferenceData/{dataType}/selections
  • GET /tenant/{tenantId}/v1/ReferenceData/{dataType}/selections/{parent}
GET /tenant/{tenantId}/v1/ReferenceData/claimedOrigins/selections
Authorization: Bearer {token}

GET /tenant/{tenantId}/v1/ReferenceData/claimedOrigins/selections/europe
Authorization: Bearer {token}

When to Use Managed Data

Use managed data when you need reusable records that behave more like business entities than lookup values, such as:

  • Collection points
  • Client contacts
  • Operational locations
  • Shared business records used by multiple workflows

Managed data includes separate endpoints for:

  • Data type configuration
  • Individual managed data items

Managed Data Type Endpoints

Managed data type configuration endpoints are located at:

/tenant/{tenantId}/v1/ManagedData

Create a Managed Data Type

POST /tenant/{tenantId}/v1/ManagedData
Authorization: Bearer {token}
Content-Type: application/json

{
  "dataType": "CollectionPoint",
  "displayName": "Collection Point",
  "description": "Shared collection point records",
  "readGroups": ["operations-team"],
  "editGroups": ["administrators"],
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "postcode": { "type": "string" }
    }
  },
  "isActive": true
}

List Managed Data Types

GET /tenant/{tenantId}/v1/ManagedData?pageNumber=1&pageSize=20&activeOnly=true
Authorization: Bearer {token}

Retrieve, Update, and Delete a Managed Data Type

  • GET /tenant/{tenantId}/v1/ManagedData/{dataType}
  • PATCH /tenant/{tenantId}/v1/ManagedData/{dataType}
  • DELETE /tenant/{tenantId}/v1/ManagedData/{dataType}

Managed Data Item Endpoints

Managed data item endpoints are located at:

/tenant/{tenantId}/v1/ManagedData/{dataType}/Items

Create a Managed Data Item

POST /tenant/{tenantId}/v1/ManagedData/CollectionPoint/Items
Authorization: Bearer {token}
Content-Type: application/json

{
  "fields": {
    "name": "Warehouse 7",
    "postcode": "AB12 3CD"
  },
  "isActive": true
}

List Managed Data Items

GET /tenant/{tenantId}/v1/ManagedData/CollectionPoint/Items?pageNumber=1&pageSize=20&isActive=true
Authorization: Bearer {token}

The item list is paginated and returns lightweight item objects with id, fields, and isActive.

Get a Managed Data Item

GET /tenant/{tenantId}/v1/ManagedData/CollectionPoint/Items/{id}
Authorization: Bearer {token}

Update a Managed Data Item

PATCH /tenant/{tenantId}/v1/ManagedData/CollectionPoint/Items/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "fields": {
    "name": "Warehouse 7 North"
  }
}

Delete a Managed Data Item

DELETE /tenant/{tenantId}/v1/ManagedData/CollectionPoint/Items/{id}
Authorization: Bearer {token}

Choosing Between Them

Use Reference Data when:

  • You need lookup lists
  • You need hierarchical selections
  • You want simple option sets for forms

Use Managed Data when:

  • You need reusable records with their own fields
  • You need record-level lifecycle management
  • You want to apply read and edit permissions to reusable business entities

📚 API Documentation: For complete schemas and optional fields, visit https://workflow.agglestone.com/swagger.