Agentic Organization Search

Introduction

The Agentic Organization Search endpoint takes one sentence, such as Fintech scale-ups headquartered in Berlin, 200 to 500 people, reads it into Organization search filters, runs that search and returns the matching full organization profiles. You do not build the filters yourself: the response tells you which ones were applied, in data.interpretation.

Every result is a complete profile, the same shape Organization search returns, with the same cursor pagination. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.

Use it when the request comes from a person typing what they want, or when you prefer not to map criteria to filter names. To control every filter yourself, use Organization search. To find people rather than organizations, use Agentic Search.

Authorization

Request body

Prompt length: the 1000 token limit is about 4000 characters of English text. It is counted conservatively: four plain ASCII characters count as one token, and every other character (an accented letter, a non-Latin script) counts as one token on its own. A longer prompt returns HTTP 422 with error.code INVALID_PROMPT and costs 0 credits.

No filters: the filters come from the prompt, so the request takes no search filter. Any other field, such as industry or location, returns HTTP 422 with error.code PROMPT_FILTERS_NOT_SUPPORTED and the offending fields in error.details.fields, and costs 0 credits. A filter is refused rather than ignored, because an ignored filter would return results you did not ask for. Describe it in the prompt instead, or send explicit filters to Organization search.

What a prompt can express

A prompt is read into these Organization search filters:

A size word becomes a headcount range: a startup is 1 to 50 employees, a scale-up 51 to 500, a mid-market company 501 to 5000 and an enterprise 5001 and more. Headcount is stored as fixed brackets, and a range only matches the brackets it fully contains (see Organization search), so a size word or round bounds such as 200 to 500 people work best. A founding period such as founded after 2015 becomes foundedYear from 2016.

Organization names and places are kept as you write them, in any language. Organizations store their headquarters city in its local spelling, so München matches more organizations than Munich. Industries are read into the closest values of the industry list.

Anything the prompt asks for that no filter covers, such as funding, revenue or headcount growth, is left out of the search and reported in data.interpretation.warnings, so you can see what the results do not take into account.

Pagination and credits

Agentic Organization Search uses cursor pagination, like Organization search. Each response returns up to perPage organizations (1 to 100, default 25) and a metadata.nextCursor value. To get the following page, send the same prompt again with that value as cursor; nextCursor is null on the last page. The cursor is opaque: send it back unchanged, without parsing or altering it. There is no page parameter, and perPage may change from one page to the next.

The cursor does not expire, and a long pause between two pages is fine: the next page picks up where the previous one stopped. If organizations were refreshed in the meantime, one of them can occasionally repeat or be skipped at the page boundary. What a cursor needs is the same filters. A prompt keeps the filters it was first read into for 24 hours in your workspace, so resending it unchanged, from any of your API keys, always runs the same search. Spaces and line breaks do not count as a change. If you edit the prompt, or come back after 24 hours, the prompt is read again, and a cursor sent with filters other than the ones that produced it returns HTTP 400 and costs 0 credits: start again from the first page, without cursor.

perPage above 100 returns HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED, and a perPage that is not a whole number returns HTTP 422 with error.code INVALID_PAGINATION.

Agentic Organization Search costs 1 credit per page for the search itself, plus 1 credit per organization delivered. The search credit is charged on every page, including when no organization matches. Organizations removed for compliance reasons before the response are not billed. A page that returns 25 organizations costs 26 credits, and a page that returns no organization costs 1 credit. Before it runs, a request needs perPage plus 1 credits available: with fewer, it returns HTTP 402 with INSUFFICIENT_CREDITS and costs nothing. A request refused before the search runs, for any of the reasons listed under Errors, costs 0 credits. Lower perPage to control how many credits a single request can spend.

Tip: data.interpretation.filters is a valid Organization search body. Send it to the free Organization search count endpoint to know how many organizations match in total, or to Organization search to adjust a filter by hand.

Errors

Every error below answers before the search runs, and costs 0 credits. When the prompt was read, error.details.interpretation carries the filters and warnings it produced, so you can see why it could not run.

Response structure

Note: This endpoint uses a nested envelope. The top-level V2 data field wraps an inner search payload that contains the actual results array (data.data), the pagination info (data.metadata) and the filters read from the prompt (data.interpretation). See the example response for the exact shape.

Code examples

curl -X POST https://api.reversecontact.com/v2/search/organizations/prompt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fintech scale-ups headquartered in Berlin, 200 to 500 people, that raised a Series B",
    "perPage": 25
  }'

const prompt = "Fintech scale-ups headquartered in Berlin, 200 to 500 people, that raised a Series B";

const promptPage = async (cursor) => {
  const response = await fetch("https://api.reversecontact.com/v2/search/organizations/prompt", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    // The same prompt travels with every page, the cursor only from the second one.
    body: JSON.stringify({ prompt, perPage: 25, cursor })
  });

  return response.json();
};

const firstPage = await promptPage();
const { filters, warnings } = firstPage.data.interpretation;
console.log("Filters applied:", filters, "Not applied:", warnings);

const organizations = firstPage.data.data;
const { nextCursor } = firstPage.data.metadata;
if (nextCursor) {
  const secondPage = await promptPage(nextCursor);
  organizations.push(...secondPage.data.data);
}

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/search/organizations/prompt",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Fintech scale-ups headquartered in Berlin, 200 to 500 people, that raised a Series B",
        "perPage": 25
    }
)

payload = response.json()
interpretation = payload["data"]["interpretation"]
organizations = payload["data"]["data"]
print(f"Filters applied: {interpretation['filters']}")
print(f"Got {len(organizations)} organizations, next cursor: {payload['data']['metadata']['nextCursor']}")

Example response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "com_01jbd6k2q9x4r7t1v3w5y8z0ab",
        "companyName": "Ledgerline",
        "linkedinId": "34567890",
        "publicId": "ledgerline",
        "linkedinUrl": "https://www.social.com/company/ledgerline",
        "employeesCount": 318,
        "followersCount": 14250,
        "employeeCountRange": {
          "start": 201,
          "end": 500
        },
        "websiteUrl": "https://www.ledgerline.example",
        "tagline": "Payments infrastructure for European marketplaces",
        "description": "Ledgerline builds payment and payout infrastructure for marketplaces across Europe. Founded in 2018 in Berlin.",
        "industry": "Financial Services",
        "phone": null,
        "specialities": ["Payments", "Fintech", "Marketplaces"],
        "headquarter": {
          "street1": "Friedrichstraße 68",
          "street2": null,
          "postalCode": "10117",
          "city": "Berlin",
          "geographicArea": "Berlin",
          "country": "DE"
        },
        "logoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
        "foundedOn": {
          "year": 2018
        },
        "locations": [
          {
            "street1": "Friedrichstraße 68",
            "street2": null,
            "postalCode": "10117",
            "city": "Berlin",
            "state": "Berlin",
            "country": "DE"
          }
        ],
        "backgroundUrl": null
      }
    ],
    "metadata": {
      "perPage": 25,
      "count": 1,
      "nextCursor": "cur_01j9y2b7c4d8f0g3h6k9m2n5"
    },
    "interpretation": {
      "filters": {
        "industry": "Financial Services",
        "employeeCountRange": { "min": 200, "max": 500 },
        "location": { "countryCode": "DE", "city": "Berlin" }
      },
      "warnings": ["Not available as filters yet: Series B."]
    }
  },
  "error": null,
  "metadata": {
    "requestId": "req_o1p2r3o4m5p6",
    "executionTimeMs": 2690
  },
  "quotas": {
    "creditsConsumed": 2,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4524,
        "left": 5476
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-10-16T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-10-16T14:16:00.000Z"
      }
    }
  }
}