Workflow Migration

Looking for a general overview?

This section is for developers building integrations. If you're a Terros user looking to understand how Workflows work, see the Workflows Overview in the Help Center.

Terros is transitioning from the legacy account status system to the new Workflows system. If you have an existing integration — whether it's a Zapier automation, a custom script, or a CRM sync — this guide explains what's changing and how to update your API calls.

What's Changing

The legacy system tracked account progress using three separate concepts:

Legacy Concept	What It Did	New Equivalent
Account Statuses	A list of stages an account could be in (e.g. "Not Home", "Sold")	Workflow Stages
Dispositions	Outcomes reps recorded on contacts (e.g. "Not Interested", "Call Back")	Workflow Actions
Event Outcomes	Results of calendar events (e.g. "No Show", "Cancelled")	Workflow Actions on the account

All three are now unified under a single Workflow — a configurable pipeline of stages and actions.

How Account Data is Changing

When you fetch an account (e.g. via POST /account/get), the response includes both old and new fields during the transition. Here's what to look for:

Legacy Fields (Deprecated)

These fields still appear in responses for backward compatibility, but they are no longer the source of truth:

{
  "statusId": "AS.abc123",
  "statusHistory": [
    { "statusId": "AS.abc123", "statusChangedDate": 1710000000000 }
  ]
}

New Workflow Fields

These are the fields to use going forward:

{
  "workflowId": "WF.xyz789",
  "workflowStageId": "S.Pitched",
  "workflowHistory": [
    {
      "stageId": "S.Pitched",
      "actionId": "A.knocked",
      "userId": "U:abc",
      "timestamp": 1710000000000
    }
  ]
}

Side-by-Side Comparison

What You Need	Legacy Field	New Field
Current stage of an account	statusId	workflowStageId
History of stage changes	statusHistory	workflowHistory
Which pipeline the account is in	(not applicable)	workflowId
What action was taken	contacts[].dispositionId	workflowHistory[].actionId
Calendar event result	calendarEvent.outcomeId	Workflow action on the underlying account

How to Look Up Stage and Action Names

The IDs in workflowStageId and workflowHistory are references, not human-readable names.

The easiest way is to open the Workflow editor in Terros — select your workflow and you'll see the names and IDs for all stages and actions right in the UI.

Look up stage and action names via the API

Fetch the workflow definition:

curl -X POST "https://api.terros.com/workflow/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $TERROS_API_KEY" \
  -d '{ "workflowId": "WF.xyz789" }'

The response includes stages and actions arrays. Match stageId and actionId values to get the name for each.

Or list all workflows for your company:

curl -X POST "https://api.terros.com/workflow/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $TERROS_API_KEY" \
  -d '{}'

Updating Your Integration

If you read account data (GET)

1. Replace references to statusId with workflowStageId.
2. Replace references to statusHistory with workflowHistory.
3. If you need the stage name, fetch the workflow definition once and cache it — stages don't change often.

If you write account data (upsert/update)

When creating or updating accounts via POST /account/upsert, you can still send statusId during the transition period. However, if your company has been migrated to Workflows, use the workflowActionOrStageId field instead — it accepts either a workflow action ID (A.xxx) or a stage ID (S.xxx). Using an action ID is recommended because it records the action in the account's workflow history, not just the stage change.

If you use webhooks

Outbound webhooks continue to fire on account changes. The webhook payload will include both legacy and workflow fields. Update your webhook handler to read from the workflow* fields.

If you filter or search accounts

POST /account/list accepts statusIds (legacy) or the workflow equivalents: workflowId, stageIds, and actionIds. Migrate your filters to use the workflow fields. The actionIds filter lets you find accounts by their last workflow action.

If you use contact/list

Companies on Workflows should switch from POST /contact/list to POST /activity/list. The activity list returns workflow action history (who did what, when, and where) instead of legacy contact/disposition records.

How to Tell if Your Company Has Been Migrated

If your company is on the new system, accounts will have a workflowId field populated. You can also check with your Terros admin — the Workflows system is visible under Settings → Workflows in the web app.

Timeline

• Now: Both legacy and workflow fields are available on all responses. Either can be used.
• After migration: Workflow fields are the source of truth. Legacy fields are kept in sync but may be removed in a future API version.

Need Help?

• Check your workflow configuration at Settings → Workflows in the Terros web app.
• Contact Terros support for help mapping your existing integration to the new workflow fields.