Quickstart

Three requests, about five minutes: describe who you want, wait for Origami to go find them, read them back. That’s the whole loop, and every other Leads flow is a variation on it. New to the API? The overview explains how the pieces fit together first.

Building with an AI coding assistant? Download the OpenAPI spec or install the Origami skill.

Prerequisites

An Origami account on a paid plan
An API key (create one in Settings → Developers)
curl and jq

export ORIGAMI_API_KEY=og_live_your_key_here

Step 1: Start a search

POST /leads/searches creates a list, sources leads, and researches them — all from one sentence. The brief is the steer; there is no filter DSL, so say what you’d say to a researcher.

curl -X POST https://origami.chat/api/v3/leads/searches \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Heads of RevOps at 50-500 person US SaaS companies",
    "count": 25
  }'

You get 202 Accepted with a Job already running. Nothing is finished yet — keep id, that’s what you poll next.

{
  "object": "job",
  "id": "3f1c9b2a-0e5d-4a77-9c11-2b6d8e4f5a90",
  "operation": "leads.searches.create",
  "status": "running",
  "phase": "researching",
  "target": null,
  "next_poll_at": "2026-08-25T18:05:12Z",
  "result": null,
  "credits": { "spent": 0, "settled": true }
}

Step 2: Poll the Job

Poll GET /jobs/{job_id} until status is no longer queued or running. Honor next_poll_at (or the Retry-After header). Polling faster than the hint is served from a short-lived cache — it costs you requests without surfacing progress sooner.

JOB_ID=3f1c9b2a-0e5d-4a77-9c11-2b6d8e4f5a90

while true; do
  RESP=$(curl -fsSL -D /tmp/origami-headers \
    "https://origami.chat/api/v3/jobs/$JOB_ID" \
    -H "Authorization: Bearer $ORIGAMI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  case "$STATUS" in queued|running) ;; *) break ;; esac
  WAIT=$(grep -i '^retry-after:' /tmp/origami-headers | awk '{print $2}' | tr -d '\r')
  sleep "${WAIT:-15}"
done
echo "$RESP" | jq .

A sourcing Job stays running with phase: "enriching" until the cells it owns finish, so succeeded genuinely means done — result counts won’t move afterwards. Expect a few minutes for 25 leads.

{
  "object": "job",
  "id": "3f1c9b2a-0e5d-4a77-9c11-2b6d8e4f5a90",
  "operation": "leads.searches.create",
  "status": "succeeded",
  "phase": null,
  "target": { "type": "list", "id": "d290f1ee-6c54-4b01-90e6-d701748f0851" },
  "result": {
    "list_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "search_id": "7c4e2a11-9b80-4d33-a1f0-0c8e6b2d4a71",
    "added": 23,
    "row_ids": ["a1b2c3d4-1111-2222-3333-444455556666"]
  },
  "credits": { "spent": 47.5, "settled": true }
}

Prefer push over poll? Subscribe to job.succeeded and read the Job when the event arrives.

Step 3: Read the rows

result.row_ids are exactly the rows this run added, so you can read them without paging the whole list. Reads are free. Cap is 100 ids per call.

curl "https://origami.chat/api/v3/leads/lists/$LIST_ID/rows?ids=$ROW_ID" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"

{
  "object": "list",
  "items": [
    {
      "object": "row",
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "relevance_score": 82,
      "is_deduplicated": false,
      "is_excluded": false
    }
  ],
  "next_cursor": null,
  "url": "/api/v3/leads/lists/d290f1ee-6c54-4b01-90e6-d701748f0851/rows"
}

To export the whole list, pass format=csv on the same endpoint.

What’s next

You now have a list with 23 researched rows in it. From here:

Build a list

Go deeper on the same search, bring your own rows, add research columns.

Run a campaign

Enroll this list in an email or LinkedIn sequence.

The Job object

Cancelling, credits, and the questions a Job can ask you.

Conventions

Paging, errors, idempotency, and destructive-call previews.

Start at count: 10, read the rows, refine the brief, and only then ask for hundreds with fetch-more on the same search. Refining early is much cheaper than re-running.

Get started

Jobs

Leads

Send

Account

Prerequisites

Step 1: Start a search

Step 2: Poll the Job

Step 3: Read the rows

What’s next

Build a list

Run a campaign

The Job object

Conventions

​Prerequisites

​Step 1: Start a search

​Step 2: Poll the Job

​Step 3: Read the rows

​What’s next

Build a list

Run a campaign

The Job object

Conventions

Prerequisites

Step 1: Start a search

Step 2: Poll the Job

Step 3: Read the rows

What’s next