Integrations Guide

Overview

Fishladder provides a REST API that is compatible with all major automation platforms. You can use it to trigger automations when things happen in Fishladder (e.g. a task is created), or to push data into Fishladder from other tools (e.g. create a task from a form submission).

There are two ways to receive events from Fishladder:

• Webhooks (real-time) — Fishladder sends an HTTP POST to your URL when an event occurs
• Polling (periodic) — Your platform polls an endpoint for new/updated items

Authentication

All API requests require a Bearer token. Generate one from Settings → API Keys. Each key is scoped to a single team.

When configuring your automation platform, set the authentication type to API Key or Bearer Token, and enter your Fishladder API key.

# All requests include this header:
Authorization: Bearer fl_your_key_here

Rate limit, per API key per hour: 1,000 reads and 200 writes, counted separately so a read-heavy integration cannot exhaust its own write budget. Exceeded requests return 429 Too Many Requests with a Retry-After header and a scope field naming which budget ran out.

Available Triggers

These are events that can trigger automations in your workflow platform. They are delivered via webhooks (real-time) or polling endpoints (periodic).

Available Actions

These are things your automation can do in Fishladder. All endpoints use Bearer auth.

Webhook Setup

For real-time triggers, subscribe to webhook events. This is what Zapier and Make use under the hood when you set up a trigger.

Subscribe to events

curl -X POST https://app.ladder.fish/api/v1/webhooks \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc/",
    "events": ["task.created", "task.completed"]
  }'

# Response (201)
{
  "id": "a1b2c3d4",
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "events": ["task.created", "task.completed"],
  "active": true,
  "secret": "64-char-hex-secret-for-hmac-verification",
  "createdAt": "2026-03-06T10:00:00.000Z",
  "updatedAt": "2026-03-06T10:00:00.000Z"
}

List subscriptions

curl https://app.ladder.fish/api/v1/webhooks \
  -H "Authorization: Bearer fl_your_key_here"

# Returns array of active webhook subscriptions

Unsubscribe

curl -X DELETE https://app.ladder.fish/api/v1/webhooks/{id} \
  -H "Authorization: Bearer fl_your_key_here"

# Response: { "ok": true }

Webhook delivery

When an event occurs, Fishladder sends an HTTP POST to your targetUrl with these headers:

Polling Endpoints

Some platforms (including Zapier in basic mode) poll an endpoint periodically instead of using webhooks. These endpoints return items sorted newest-first, so the platform can check for new items since the last poll.

All polling endpoints accept an optional ?since=ISO_DATE query parameter to only return items created/updated after a given timestamp.

curl "https://app.ladder.fish/api/v1/poll/tasks?since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer fl_your_key_here"

Example Payloads

These are the JSON payloads sent via webhooks when events occur.

task.created

{
  "event": "task.created",
  "task": {
    "id": "a1b2c3d4",
    "projectId": "proj-123",
    "title": "Design landing page",
    "assigneeId": "user_abc",
    "priority": "high"
  },
  "timestamp": "2026-03-06T14:30:00.000Z"
}

task.completed

{
  "event": "task.completed",
  "task": {
    "id": "a1b2c3d4",
    "projectId": "proj-123",
    "title": "Design landing page",
    "assigneeId": "user_abc",
    "completedAt": "2026-03-06T16:00:00.000Z"
  },
  "timestamp": "2026-03-06T16:00:00.000Z"
}

application.created

{
  "event": "application.created",
  "application": {
    "id": "app-456",
    "jobId": "job-789",
    "candidateId": "cand-012",
    "stageId": "stage-initial",
    "status": "active"
  },
  "timestamp": "2026-03-06T09:15:00.000Z"
}

candidate.created

{
  "event": "candidate.created",
  "candidate": {
    "id": "cand-012",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]"
  },
  "timestamp": "2026-03-06T09:14:00.000Z"
}

goal.updated

{
  "event": "goal.updated",
  "goal": {
    "id": "goal-abc",
    "title": "Improve retention by 20%",
    "status": "active",
    "color": "#6366f1"
  },
  "timestamp": "2026-03-06T11:00:00.000Z"
}

Platform Guides