Skip to main content

Complete Workflow (Step-by-Step)

This page describes the entire report flow in one place: from authentication to retrieving the final report. Use it as a single reference when integrating the API. The search itself is described in detail in the People search guide.

Path parameters are written here as :reportId, :source, etc.; in the API and OpenAPI spec the same segments use curly-brace placeholders (see API reference).

In a Nutshell​

  1. Sign in → get a JWT token.
  2. Create report → send what you know about the person (fields), receive a report ID.
  3. Run a search round → get a ranked panel of accounts per network; repeat to refine.
  4. Pick accounts (optional) → tell the search which account is the person; the other networks' matches are pinned.
  5. Confirm → choose the accounts the report is built from; get the estimated time.
  6. Wait → use SSE or poll GET /check/:reportId until the data is ready.
  7. Get report → fetch the report and related endpoints (friends, interests, summary).

Important: Send Authorization: Bearer <token> on every request after sign-in (including GET requests). Missing the header on a later step leads to 403 "access denied".


1. Authenticate​

Call POST /auth/signin with your account email and password, and "token": true to receive a JWT in the response. Store that token and send it in the Authorization: Bearer <token> header on all subsequent requests. The token is valid for 24 hours; with remember left at its default (true) the session can be refreshed for up to 90 days. See Authentication for details and Google OAuth.


2. Create Report (Get Report ID)​

Call POST /create with the token and a fields object:

{ "fields": { "name": "Jane Doe", "location": "Austin", "work": "nurse" } }

One of name, username (an @handle) or phone is required. The response is { "id": "<reportId>" }. Save this report ID; it is used in all following steps.

A body without fields is the deprecated classic form (see Classic search).


3. Run a Search Round​

Call POST /people-search/run/:reportId with the same fields to get one ranked panel per network (ig, fb, tw, tt, and li where enabled). Each card is an account: id, source, username, fullname, image, link, and a badReason when a report cannot be built from it (private, notFound, zeroFollows, followsPrivate, optOut, unloaded, unmapped, unexpected).

Refine with another round: add facts to fields, answer the panel's question, or pick an account. Rounds are free but capped per report (429 when the cap is reached). To fill the first tab quickly, send one request per network with a shared round_key, and a stage: "quick" first look beside each; the People search guide has the details.


4. Pick Accounts (Optional)​

Send the chosen accounts in picked of the next round: up to 3 per network. A pick pins the same person's accounts in the other networks to the top of their panels. The user can also give an exact account (POST /people-search/account/:reportId), look a handle up everywhere (POST /people-search/lookup/handle), or give a LinkedIn link (POST /people-search/linkedin/:reportId).


5. Confirm Selection​

Call POST /create/:reportId/confirm with a JSON array of the accounts to build the report from, for example:

[ { "source": "ig", "id": "ig_profile_id" }, { "source": "fb", "id": "fb_profile_id" } ].

The report is built from one account per network (the first one listed for that network). More accounts of a network, up to 3, are kept as the report's selected profiles.

A signed-in account is required. A guest session gets 401.

The response has estimatedTime and loadTimeout in seconds (estimatedTime: 0 means nothing is left to wait for), loads (the state of each account that is still loading or has failed) and not_in_report (confirmed LinkedIn accounts, which are never part of the report). If a load fails (status: "error"), remove that account with POST /people-search/drop/:reportId and confirm again.

A repeat confirm returns 409 ("report profiles were already confirmed") unless it was undone with drop.

Confirming does not spend a report credit. The credit check happens on POST /create (see the 402 FAQ below), and the credit is spent the first time the owner reads the finished report (GET /report/:reportId); there is no separate "spend" call.


6. Wait Until the Data Is Ready​

If estimatedTime > 0, wait before fetching the report. You can:

  • SSE (recommended): GET /sse/:reportId to receive real-time progress (follows per account, then summary). See Real-time Updates (SSE).
  • Poll: GET /check/:reportId until ready === true. generated becomes true once the owner has read the report; it does not mean the AI summary is ready.

See the Report Pipeline for what each GET /check/:reportId field means.


  • Report page: GET /report/:reportId returns the slim ReportPage (per-source rows with counts and top interests, merged highlights, redFlags, friendsPreview, interestCategoriesPreview; optional ?sortByRedFlags=true&limit=…, If-None-Match for ETag / 304).
  • Full interest trees (lazy detail): GET /report/:reportId/interests; optional ?source=ig|tw|… to fetch one network only.
  • Full monolithic payload: GET /report/:reportId/full. Its embedded summary is deprecated; prefer GET /report/:reportId plus GET /report/:reportId/summary.
  • Per source: GET /report/:reportId/:source.
  • Friends (unified): GET /report/:reportId/friends?limit=…&offset=… (sortByRedFlags supported).
  • Friends (per network): GET /report/:reportId/friends/:source?limit=…&offset=….
  • Common interests with a friend: GET /report/:reportId/:source/common/:friendId.
  • Interest details: GET /report/:reportId/:source/:interestId and GET /report/:reportId/:source/:interestId/profiles.
  • Interest changes over time: GET /report/:reportId/:source/diffs?date=2024-01&type=new.
  • AI summary: GET /report/:reportId/summary (generated asynchronously; wait for the SSE summary event, then fetch it).

Reports can be fetched later by report ID without re-running the flow; store the ID if you need to access the same report again.


FAQ​

I get 403 "access denied" on a GET call. What am I doing wrong?​

You must send the Bearer token on every request after sign-in, including GET requests. Add the header: Authorization: Bearer <your_token>.

In what order do I call the APIs?​

(1) POST /auth/signin → (2) POST /create with fields → (3) POST /people-search/run/:reportId (repeat to refine) → (4) POST /create/:reportId/confirm → (5) wait via GET /sse/:reportId or GET /check/:reportId → (6) GET /report/:reportId. Every call carries the Bearer token. See Quick Start and the People search guide.

Can I change the report after I confirmed?​

Not by confirming again: a repeat confirm returns 409. To change the accounts you can undo the confirm with POST /people-search/drop/:reportId (a report can be confirmed up to 5 times), or create a new report. Once the report has been built it is locked and these calls answer 403 ("report was already generated").

Why is a profile not available or marked with badReason?​

Common reasons: private (account is private), notFound (username does not exist), zeroFollows (profile follows no one, so we cannot analyze interests), followsPrivate (TikTok hid the following list; the account itself is not private), optOut (user requested data removal), unloaded (data not loaded yet), unmapped (profile could not be mapped), unexpected (an unexpected failure). A card with optOut cannot be picked or confirmed.

What if loading fails for an account after I confirmed?​

After confirm, the API loads each account and its subscriptions (follows). If loading fails for one account (for example the account is private or follows are unavailable), you get a per-account error, not an HTTP error. Subscribe to GET /sse/:reportId and handle follows events with status: "error" and the error field (for example private, unloaded). When polling GET /check/:reportId, check loadError and errorSource. The report may still contain data for other accounts. See Error Handling — Profile Loading Errors.

How do I know when the report is ready to fetch?​

Call GET /check/:reportId. When ready === true the data is loaded and the report can be read. generated turns true after the owner's first read of the report. The AI summary is separate: wait for the SSE summary event, then fetch GET /report/:reportId/summary.

What are the source codes (ig, tw, fb, tt, li)?​

They are platform identifiers: ig = Instagram, tw = Twitter / X, fb = Facebook, tt = TikTok, li = LinkedIn. li is searchable and pickable only where the deployment enables it (peopleSearchLinkedinPanel in GET /auth/info), and a LinkedIn account is never the subject of a report.

Does the report ID expire?​

Report IDs are persistent. You can store them and fetch the same report later with GET /report/:reportId as long as you have a valid token and the report belongs to your account.

I got a 402. What does that mean?​

402 comes from POST /create (report creation), not from confirm: your account has no remaining report credits (message: "to continue please upgrade your subscription", or "You have reached search limit. Please Sign up to continue." for a guest session). If you have credits at creation time but run out before you read the finished report, the report page shows blurred/placeholder data instead of an error — check your subscription or purchase more reports in the dashboard.

Can I build one report from several networks?​

Yes. Confirm accounts of several networks in one request; the report is built from one account per network.

Where do I get the profile id to pick or confirm?​

From the cards of POST /people-search/run/:reportId (or .../account, .../seed). Each card has an id and a source; use those same values in picked and in the confirm body. Confirming an account that the report never showed returns 404.