Quickstart - VisaFlo

Before You Begin

You need a workspace API key created by a VisaFlo administrator. Keep the key in a server-side secret store. This API is not designed for browser-based requests.

1. Verify Your Key

List your workflow templates. This confirms the key, network path, and workspace scope without creating data.

curl "https://api.vflo.app/api/public/workflow/list" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "VFLO_WORKFLOW_ID",
      "name": "Standard PR Workflow",
      "taskCount": 8
    }
  ]
}

2. Create or Update a Lead

lead/create matches by email. If the workspace already has an open lead for that email, the call updates it instead of creating a duplicate, so retries and repeated webhook deliveries are safe without a search first.

curl -X POST "https://api.vflo.app/api/public/lead/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+16135550100",
    "countryOfResidence": "Canada",
    "stage": "Consultation Booked",
    "consultationTime": "2026-10-01 14:30"
  }'

A new lead returns 201. An existing open lead returns 200 with data.updated: true. Either way, save the returned data.id in your source system. See Create a lead for every field and the update rules.

3. Create a Follow-up

Use the VisaFlo lead, client, or case ID to create operational work.

curl -X POST "https://api.vflo.app/api/public/task/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review new web intake",
    "priority": "high",
    "status": "open",
    "entity": { "type": "lead", "id": "VFLO_LEAD_ID" }
  }'

Production Checklist

Search before creating a client or case. lead/create already matches leads by email.
Persist VisaFlo IDs after a successful create.
Retry only transient failures such as 429 and 5xx responses.
Do not retry a malformed 400 request without correcting it.
Keep the API key on a server, never in a browser or client-side extension.