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
- Sign in → get a JWT token.
- Create report → send what you know about the person (
fields), receive a report ID. - Run a search round → get a ranked panel of accounts per network; repeat to refine.
- Pick accounts (optional) → tell the search which account is the person; the other networks' matches are pinned.
- Confirm → choose the accounts the report is built from; get the estimated time.
- Wait → use SSE or poll
GET /check/:reportIduntil the data is ready. - 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/:reportIdto receive real-time progress (followsper account, thensummary). See Real-time Updates (SSE). - Poll:
GET /check/:reportIduntilready === true.generatedbecomestrueonce 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.
7. Get the Report and Related Data
- Report page:
GET /report/:reportIdreturns the slim ReportPage (per-source rows with counts and top interests, merged highlights,redFlags,friendsPreview,interestCategoriesPreview; optional?sortByRedFlags=true&limit=…,If-None-Matchfor 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 embeddedsummaryis deprecated; preferGET /report/:reportIdplusGET /report/:reportId/summary. - Per source:
GET /report/:reportId/:source. - Friends (unified):
GET /report/:reportId/friends?limit=…&offset=…(sortByRedFlagssupported). - 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/:interestIdandGET /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 SSEsummaryevent, 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.