Skip to main content
This walkthrough creates a minimal flow using the built-in echo action (no external connection needed), triggers it, and follows the run through to its result.
You’ll need an API key. Export it as GETDIALED_API_KEY and set the base URL — https://api.getdialed.ai/flows in production.
export BASE_URL="https://api.getdialed.ai/flows"
export GETDIALED_API_KEY="<your key>"

​
1. Create a Flow Definition

A definition declares its inputs, then a series of steps containing tasks. This one has a single step with a single task that echoes a message built from the trigger input: 
curl -X POST "$BASE_URL/definitions" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello GetDialed",
    "status": "active",
    "inputs": [
      {"name": "message", "type": "string", "required": true}
    ],
    "steps": [
      {
        "step_id": "step_1",
        "name": "Echo the input",
        "tasks": [
          {
            "task_id": "task_1",
            "task_name": "echo",
            "platform_id": "getdialed",
            "service_id": "getdialed__utils",
            "action_id": "getdialed__utils__echo",
            "parameters": {
              "message": "{{input.message}}"
            }
          }
        ]
      }
    ]
  }'
The response includes the new definition’s id (e.g. def_a1b2c3d4). Note "status": "active" — only active definitions can be triggered.
{{input.message}} is an expression. At runtime it resolves to the message field of the trigger’s input_data.

​
2. Trigger it

curl -X POST "$BASE_URL/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {"message": "hello, world"}
  }'

{
  "job_id": "job_9f8e7d6c",
  "definition_id": "def_a1b2c3d4",
  "status": "pending"
}
Every trigger creates a Job. This one carries a single record, so it produces one Execution. To run the same flow for many records at once (e.g. rows of an uploaded file), pass a records array instead — see Triggering with records.

​
3. Watch it run

Fetch the job: 
curl "$BASE_URL/jobs/job_9f8e7d6c" \
  -H "X-API-Key: $GETDIALED_API_KEY"
The job’s status moves pending → running → completed. List its executions to see per-record results: 
curl "$BASE_URL/jobs/job_9f8e7d6c/executions" \
  -H "X-API-Key: $GETDIALED_API_KEY"
Each execution has its own status, result, and — on failure — an error message.

​
Next steps

Jobs & Executions

The full lifecycle: triggers, jobs, executions, and statuses.

Trigger with records

Fan a file of records out into one execution per row.

Connections

Store credentials for real integrations like Five9.

Build a real flow

A multi-step flow against a live integration.