Step 4: Manage schemas

Each task in a journey includes a schema that defines the structure of data you must submit. This schema specifies the expected fields, types, and validation rules for completing the task. To understand the schema for passing customer data, check the User data schema reference

Use the Retrieve task schema (/journey/task/schema) endpoint to retrieve the schema for any task assigned to a journey instance.

​

When to retrieve a task schema

You should fetch a task’s schema when:

• Preparing to submit data for a task
• Dynamically generating input fields in your UI
• Confirming the required fields and their formats
• Validating data before submitting it

​

Prerequisites

Before sending the request, make sure you have:

• Access token – Get this from the Authenticate step
• Task ID – Returned when you Retrieve tasks
• (Optional) Instance ID – Needed in some journey configurations

​

Retrieve task schema (API request)

Send a POST request to the /journey/task/schema endpoint. Your request should be in this format:

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/task/schema \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "taskId": "your-task-id"
  }'

If your journey configuration requires it, include the instanceId in the request body as well:

{
  "taskId": "your-task-id",
  "instanceId": "your-instance-id"
}

If your request runs successfully, then you will receive response like this:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "document": {
      "type": "object",
      "properties": {
        "type": { "type": "string" },
        "file": { "type": "string", "format": "base64" }
      },
      "required": ["type", "file"]
    }
  },
  "required": ["document"]
}

​

How to use the schema

The schema defines:

• The field names (e.g., document.type)
• The data types (e.g., string, array, object)
• Which fields are required
• Any format restrictions (e.g., base64 for file uploads)

You must use this structure when submitting task data.

​

Best practices

• Always retrieve the latest schema before submitting data.
• If the schema changes, update your integration to match the new structure.
• Validate your input locally using the schema before calling the API.

​

Next step

Go to Submit task data to complete tasks using the retrieved schema.