CleverFlow

Connect Cosmo to CleverFlow to look up, create and update runs — leads, deals and other workflow records — from chat.

The CleverFlow integration lets Cosmo look up your CleverFlow workflows and records ("runs"), create new runs and update existing ones. You identify workspaces and workflows by name or key and fields by the label you see in the CleverFlow app — no internal ids needed. Cosmo can find a run by name for you, so you don't need to keep run ids yourself.

Before you connect

CleverFlow does not use a sign-in window. It uses an API token, issued by your CleverFlow account team. Ask them for:

Item	Example	Used for
API token	`9f3c…`	Connecting

That is all Cosmo needs: it looks up your workspace, workflow keys and field labels with the token.

Changes Cosmo makes are recorded in CleverFlow as made by the user who owns the token, so each member connects with their own token. Connecting CleverFlow never connects it for anyone else in your organization.

Connecting

Open Cosmo Desktop → Customize → Integrations.
Find CleverFlow under "Add new integration" and click Connect.
Enter a label (for example Work) and paste your API token.
Cosmo checks the token with CleverFlow before saving it. A token CleverFlow refuses is rejected on the spot, with nothing stored.

The token is stored with your connection on the Cosmo server, and Cosmo only sends it to api.cleverflow.com.

What you can do

Tool	What it does
`create_cleverflow_run`	Create a run in a workflow, with field values. Returns the run id (for example `LEAD-1042`).
`update_cleverflow_run`	Change fields on an existing run. Only the fields you name change.
`list_cleverflow_workflows`	List your workflows and their keys, or one workflow's field labels and steps.
`find_cleverflow_runs`	Find runs in a workflow, optionally by part of their name, with their field values.
`get_cleverflow_run`	Read one run — status, current step and every filled-in field.

Example requests:

"What workflows do I have in CleverFlow?"
"Find Sara Khan in the leads workflow and show me her details."
"Create a lead for Sara Khan, email sara@example.com, source Website."
"Mark Sara Khan's lead as Qualified and set the viewing date to 5 October."

Cosmo only creates or updates a run when you ask it to. After a create or update it can read the run back to confirm every field saved.

How reading works

CleverFlow's published Run API can only create and update runs. To look runs up, Cosmo uses the same endpoints the CleverFlow web app uses, with your API token. Two consequences:

Search is by run name. Cosmo can find "Sara Khan" but not "the lead with email sara@example.com". It checks up to the 1,000 most recent runs in a workflow and tells you if it stopped before the end.
These endpoints are not part of CleverFlow's published API. If CleverFlow changes them, looking runs up can stop working while creating and updating keep working. Tell your Cosmo admin if it does.

Looking up your workspace counts as activity in CleverFlow, so the token's user shows as recently active.

Things to know

Unmatched field labels are skipped silently. CleverFlow does not report a misspelled or renamed label as an error, so a run can be created with a field left empty. Check your first few records in CleverFlow.
Updates are stricter than creates. On update, numbers must be plain numbers, dropdown values must be an existing option, dates must be YYYY-MM-DD, and phone numbers must be the structured form. A single invalid value means CleverFlow saves nothing from that update.
Fields can't be cleared. The Run API does not accept an empty value on update.
Duplicates. Some workflows reject a second run with the same name or the same email/phone. An "already exists" or "Duplicate data found" answer means the record is already there.
Users and linked records on update need internal CleverFlow ids; set them when you create the run instead, or ask your CleverFlow account team.
Dropdown options aren't listed. Cosmo can show a dropdown field's label but not its list of allowed values, so on update use the option text exactly as it appears in CleverFlow.

Troubleshooting

Problem	What to check
"CleverFlow rejected that API token" when connecting	The token was copied in full, and has not been revoked. Ask your CleverFlow account team for a new one.
A connected CleverFlow starts failing with a token error	The token expired or was revoked. Disconnect CleverFlow and connect it again with a new token.
Workspace or workflow not found	Names are case-sensitive; a workflow key (for example `LEAD`) is more reliable than a workflow name. Updates use the workspace slug, not its display name.
Run not found on update	Check the workspace slug and the run id returned when the run was created.
A run Cosmo can't find	Search matches the run name only, and covers the 1,000 most recent runs. Try part of the name, or the run id (for example `LEAD-1042`).