API Reference¶

The Workflow Engine exposes a REST API for managing contacts, workflow templates, and workflow instances.

Base URL: https://workflow.nominate.ai

Health Check¶

GET /health¶

Check if the service is running.

curl https://workflow.nominate.ai/health

Response:

{"status": "healthy"}

Contacts¶

GET /api/contacts¶

List all contacts with optional filters.

Query Parameters:

Parameter	Type	Description
`county`	string	Filter by county
`tag`	string	Filter by tag
`organization`	string	Filter by organization

curl "https://workflow.nominate.ai/api/contacts?county=Maricopa&tag=volunteer"

GET /api/contacts/search¶

Search contacts by name, email, or phone.

Query Parameters:

Parameter	Type	Description
`q`	string	Search query

curl "https://workflow.nominate.ai/api/contacts/search?q=smith"

GET /api/contacts/{contact_id}¶

Get a single contact by ID.

curl https://workflow.nominate.ai/api/contacts/abc123

POST /api/contacts¶

Create a new contact.

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Contact name
`email`	string	No	Email address
`phone`	string	No	Phone number
`county`	string	No	County name
`organization`	string	No	Organization
`role`	string	No	Role/title
`tags`	array	No	List of tags
`metadata`	object	No	Custom key-value data

curl -X POST https://workflow.nominate.ai/api/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "county": "Pima",
    "tags": ["captain", "active"]
  }'

PATCH /api/contacts/{contact_id}¶

Update an existing contact. Only include fields you want to change.

curl -X PATCH https://workflow.nominate.ai/api/contacts/abc123 \
  -H "Content-Type: application/json" \
  -d '{"tags": ["captain", "priority"]}'

DELETE /api/contacts/{contact_id}¶

Delete a contact.

curl -X DELETE https://workflow.nominate.ai/api/contacts/abc123

POST /api/contacts/{contact_id}/tags/{tag}¶

Add a tag to a contact.

curl -X POST https://workflow.nominate.ai/api/contacts/abc123/tags/vip

DELETE /api/contacts/{contact_id}/tags/{tag}¶

Remove a tag from a contact.

curl -X DELETE https://workflow.nominate.ai/api/contacts/abc123/tags/vip

Workflow Templates¶

GET /api/workflows¶

List all workflow templates.

Query Parameters:

Parameter	Type	Description
`tag`	string	Filter by tag

curl https://workflow.nominate.ai/api/workflows

GET /api/workflows/{template_id}¶

Get a workflow template by ID.

curl https://workflow.nominate.ai/api/workflows/county-outreach-v1

POST /api/workflows¶

Create a new workflow template.

curl -X POST https://workflow.nominate.ai/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Follow-up",
    "start_node": "send_email",
    "nodes": {
      "send_email": {
        "type": "action",
        "action": "email",
        "label": "Send Email",
        "transitions": {
          "sent": "end_success",
          "failed": "end_failed"
        }
      },
      "end_success": {
        "type": "end",
        "label": "Success"
      },
      "end_failed": {
        "type": "end",
        "label": "Failed",
        "end_status": "failed"
      }
    }
  }'

PATCH /api/workflows/{template_id}¶

Update a workflow template.

DELETE /api/workflows/{template_id}¶

Delete a workflow template.

POST /api/workflows/{template_id}/clone¶

Clone a workflow template with a new name.

curl -X POST "https://workflow.nominate.ai/api/workflows/county-outreach-v1/clone?new_name=county-outreach-v2"

GET /api/workflows/{template_id}/validate¶

Validate a workflow template's graph structure.

curl https://workflow.nominate.ai/api/workflows/county-outreach-v1/validate

Workflow Instances¶

GET /api/instances¶

List workflow instances with optional filters.

Query Parameters:

Parameter	Type	Description
`contact_id`	string	Filter by contact
`template_id`	string	Filter by template
`status`	string	Filter by status
`tag`	string	Filter by tag

curl "https://workflow.nominate.ai/api/instances?status=active"

GET /api/instances/{instance_id}¶

Get a workflow instance by ID.

POST /api/instances¶

Create a new workflow instance for a contact.

Request Body:

Field	Type	Required	Description
`contact_id`	string	Yes	Contact to enroll
`template_id`	string	Yes	Workflow template
`tags`	array	No	Instance tags
`metadata`	object	No	Custom data

curl -X POST https://workflow.nominate.ai/api/instances \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "abc123",
    "template_id": "county-outreach-v1"
  }'

DELETE /api/instances/{instance_id}¶

Delete a workflow instance.

POST /api/instances/{instance_id}/start¶

Start a pending workflow instance.

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/start

POST /api/instances/{instance_id}/pause¶

Pause an active workflow instance.

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/pause

POST /api/instances/{instance_id}/resume¶

Resume a paused workflow instance.

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/resume

POST /api/instances/{instance_id}/transition¶

Transition the workflow to the next node based on an outcome.

Request Body:

Field	Type	Required	Description
`outcome`	string	Yes	Transition outcome
`actor`	string	No	Who triggered this
`message`	string	No	Optional note
`data`	object	No	Additional data

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/transition \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "answered_interested",
    "actor": "staff:jane",
    "message": "Contact was very engaged, scheduled follow-up"
  }'

POST /api/instances/{instance_id}/state¶

Update the instance state (for decision evaluation).

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/state \
  -H "Content-Type: application/json" \
  -d '{
    "updates": {
      "call_notes": "Very interested in volunteering",
      "preferred_contact": "text"
    }
  }'

POST /api/instances/{instance_id}/notes¶

Add a note to the instance timeline.

curl -X POST https://workflow.nominate.ai/api/instances/xyz789/notes \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Left voicemail, will try again tomorrow",
    "actor": "staff:jane"
  }'

GET /api/instances/{instance_id}/timeline¶

Get the full event timeline for an instance.

curl https://workflow.nominate.ai/api/instances/xyz789/timeline

Instance Statuses¶

Status	Description
`pending`	Created but not started
`active`	Currently in progress
`paused`	Temporarily paused
`waiting`	Waiting for time/event
`completed`	Finished successfully
`failed`	Ended with failure
`cancelled`	Manually cancelled