Endpoints

Every request goes to the same base URL, over HTTPS, with your API key in the Authorization header:

Most lists come 25 at a time, as { "data": [...], "nextCursor": "..." }. Ask for up to 100 with ?limit=. When nextCursor isn't null, send it back as ?cursor= for the next page. GET /trails, GET /crm/connections and GET /crm/owners return everything at once, with no nextCursor.

The endpoints for trails, leads, Do Not Contact, workflows, CRM and reports answer an error with { "error": "...", "code": "..." }: a sentence to show a person and a code to switch on. The file and job endpoints keep their own shapes. Every code is in Error handling.

Only writes, runs and Bridgeant messages count toward your monthly API calls. Reads don't: every GET, and POST /dnc/check. Writes need a read-and-write key, and the ones that change a trail, a routing team, your Do Not Contact list or a CRM need a read-and-write key made by an admin.

Read your trails and their runs, see where each row went, pause and resume a trail, and change who is on a routing team. The Trails and leads guide shows each request and response.

Read the single leads your trails took in from a form, Typeform, a webhook or an email: the ones waiting for review, the ones held, or all of them, with each lead's score, owner and timeline.

Search, add to and check your Do Not Contact list. The Do Not Contact guide shows how each value is matched.

Upload one file so a job can run on it. Send it as multipart form data with the file in a field named "file". Accepts .xlsx, .xls, and .csv. Returns the file's id, which you pass as inputFileId when you create a job.

To feed a trail instead, add a folderId field with the id of a watched folder. The file lands in that folder exactly as if someone had dropped it there or emailed it in, it shows in Files, and the trail watching the folder runs on it. You do not create a job: the trail is the job. The folder id is the last part of the folder's URL in Files, and an id that is not one of your folders returns a 404 without storing anything.

Run one tool on one file. Send JSON with the file's id (inputFileId), the tool to run (toolType), and that tool's settings (configJson). Returns a job id with a status of "queued". The job runs in the background; poll it with GET /jobs/:id.

Check a job's status. Call this every couple of seconds until status is "completed" or "failed". While it runs, status moves queued → processing → completed (or failed). When it completes, outputFileId and outputFileName point to the result.

Download a file by its id. Use the outputFileId from a completed job to get the result, or an input file's id to get back what you uploaded. The response is the file itself, not JSON.

When you have many files to run through the same tool with the same settings, batch does it in one request instead of one job per file. Batch is on the Agency plan. It supports six tools: Excel to CSV, CSV to Excel, Clean Headers, Data Health Check, Deduplicate, and Transpose.

One batch counts as a single API call against your rate limit, no matter how many files. An Agency batch takes up to 50 files and 500,000 rows across all of them.

Create a batch: one tool, one configJson, many files. Upload each file first with POST /uploads, then pass their ids in the fileIds array. Returns a batchId plus ready-made URLs to poll progress and download the combined result.

Poll a batch. Returns a progress summary and the status of every job in it. Poll the pollUrl from the create step every 5 to 10 seconds until completed plus failed equals total. A poll is a read, so it doesn't count toward your monthly API calls.

Download every successful file in the batch as one ZIP. Call the downloadUrl once every file has finished. Called earlier, it returns a ZIP of only the files finished so far, or a 400 if none have finished. If some files failed, you still get a ZIP of the ones that worked; if every file failed, this returns 400 because there is nothing to download.

GET /workflows lists the workflows saved in the workspace, including ones shared with it. POST /workflows/run runs one on a file you uploaded, by its name or its id, and returns a job to poll with GET /jobs/:id, like any other job. It counts toward your monthly jobs and your monthly API calls.

Names are matched exactly, ignoring case. If two saved workflows share the name, the request returns 409 with code ambiguous_workflow_name and both ids, so you can run the one you mean by its id. A workflow whose last step is CRM Formatter can't run on the API: push the finished file with POST /jobs/:id/push instead.

Push a finished file to a CRM you connected in the app. CRMs are connected in the app only, because connecting means signing in to the CRM in a browser.

POST /jobs/:id/push starts the push. It returns 200 when the push finished within the request, or 202 with status pushing while it carries on. It uses the workspace's connection for the job's CRM unless you send connectionId, and takes an optional ownerId (one CRM user for every record) or ownerColumn (the column that names each record's owner). GET /jobs/:id/push reports where it is and, once done, what it created and updated.

GET /analytics/:view returns the numbers on the Analytics tab for one view: trails, cleanup, verification, company_active, crm or operator (shown as Jobs in the app). Add days= for the period (7, 30, 90, 365 or all, and 30 when you leave it out) and, on the trails view only, trail= for one trail. Each view needs the plan it needs in the app.

GET /activity lists everything that ran in the workspace and who ran it, the same as Activity on Home. Filter it with q=, tool=, status=, who= and since=. Work done with a key shows the key's name.

POST /bridgeant/ask sends Bridgeant one message as the person who made the key, and uses their Bridgeant messages as a chat turn in the app does. Send message, and optionally conversationId to carry on a conversation and fileId to ask about a file. It needs Starter or up and a read-and-write key whose maker is still in the workspace.

When Bridgeant offers to do something, pendingAction has the id to confirm, a kind (run_plan, run_trail, build_trail, save_trail or change_trail) and a one-line summary. Otherwise pendingAction is null. Its id isn't always the message's id, so confirm the one in pendingAction.

POST /bridgeant/actions/:id/confirm runs it, exactly as the card's button in the app would, and takes no body. A plan answers with ran and jobId, and a trail run with outcome and runId. A trail Bridgeant builds or saves is saved switched off, and a change is saved as the trail's draft: test it and put it live from the trail's page. Only a key made by an admin is offered the trail actions.