Quick Start Guide
This guide walks through the complete flow of creating a social media profile analysis report with the Socialprofiler API, using People search: you describe the person, pick their accounts, and confirm.
Overview
1. Authenticate → Get a JWT token
2. Create Report → Send what you know about the person, get a report ID
3. Run a search → Get ranked accounts per network
4. Pick (optional) → Tell the search which account is them
5. Confirm → Choose the accounts the report is built from
6. Wait → SSE or GET /check/{reportId}
7. Get Report → Read the results
Prerequisites
- A Socialprofiler account (sign up at dashboard.socialprofiler.com)
- Report credits or an active subscription. Creating a report checks that you have one; the credit itself is spent the first time you read the finished report.
- cURL or any HTTP client
Step-by-Step Integration
Step 1: Authenticate
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/signin \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"password": "your_password",
"token": true
}'
Response:
{
"status": "success",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Save the token and send it as Authorization: Bearer <token> on every later request.
Step 2: Create a Report
Send what you know about the person in fields. One of name, username (an @handle) or
phone is required; the rest is optional and narrows the search.
curl -X POST https://dashboard.socialprofiler.com/api/v1/create \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"fields": {
"name": "Jane Doe",
"location": "Austin",
"work": "nurse"
}
}'
Response:
{
"id": "68af01be012b843fd7bc2bf4"
}
Save the id: it is your report ID.
Step 3: Run a Search Round
curl -X POST https://dashboard.socialprofiler.com/api/v1/people-search/run/68af01be012b843fd7bc2bf4 \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"fields": {"name": "Jane Doe", "location": "Austin", "work": "nurse"}
}'
Response (shortened):
{
"ok": true,
"round": 1,
"order": ["ig", "fb", "tw", "tt"],
"panels": {
"ig": {
"ok": true,
"source": "ig",
"tier": 2,
"total": 37,
"results": [
{
"id": "123456789",
"source": "ig",
"username": "janedoe",
"fullname": "Jane Doe",
"image": "https://...",
"link": "https://instagram.com/janedoe",
"pinned": false,
"picked": false,
"matched": ["name", "place"]
}
],
"pins": []
}
},
"picked": [],
"search_state": {"rounds": 1, "rounds_left": 29}
}
There is one panel per network, ranked. order puts the most useful network first. A card with a
badReason (for example private) cannot be built into a report. Source codes: ig Instagram,
fb Facebook, tw X (Twitter), tt TikTok, li LinkedIn (where enabled).
To refine, run another round with more fields. See the People search guide
for refinement questions, sending a round in parts, and the first look.
Step 4: Pick the Account (optional)
When one account is clearly the person, send it in picked of the next round. The search then
pins the same person's accounts in the other networks to the top:
curl -X POST https://dashboard.socialprofiler.com/api/v1/people-search/run/68af01be012b843fd7bc2bf4 \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"fields": {"name": "Jane Doe", "location": "Austin", "work": "nurse"},
"picked": [{"source": "ig", "id": "123456789"}]
}'
Cards the identity graph placed carry a confidence band (CONFIRMED, SURE or STRONG), never
a number.
Step 5: Confirm
Confirm the accounts the report should be built from. A signed-in account is required; a guest
session gets 401.
curl -X POST https://dashboard.socialprofiler.com/api/v1/create/68af01be012b843fd7bc2bf4/confirm \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '[
{"source": "ig", "id": "123456789"},
{"source": "fb", "id": "987654321"}
]'
The report is built from one account per network (the first one listed). Confirming is final for
that selection: a repeat confirm is 409.
Response:
{
"estimatedTime": 240,
"loadTimeout": 150,
"loads": [
{"type": "follows", "status": "inprogress", "id": "123456789", "source": "ig"}
]
}
estimatedTimeandloadTimeoutare in seconds.estimatedTime: 0means nothing is left to wait for: read the report now.loadslists accounts whose data is still loading (inited,inprogress), loaded (done) or failed (error, with the reason inerror). A failed account cannot be in the report; remove it withPOST /people-search/drop/{reportId}and confirm again.
Step 6: Wait for the Data
Open the SSE stream and wait for the follows events of the confirmed accounts to be done:
curl -N https://dashboard.socialprofiler.com/api/v1/sse/68af01be012b843fd7bc2bf4 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
event: ping
data: {"type":"ping","status":"inited"}
event: follows
data: {"type":"follows","status":"inprogress","id":"123456789","source":"ig"}
event: follows
data: {"type":"follows","status":"done","id":"123456789","source":"ig"}
event: summary
data: {"type":"summary","status":"done"}
Or poll GET /check/{reportId} until ready is true:
curl https://dashboard.socialprofiler.com/api/v1/check/68af01be012b843fd7bc2bf4 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
{
"generated": false,
"ready": true,
"hasSource": true
}
ready: true means the data is loaded and the report can be read. generated becomes true once
the owner has read the report (see Report Pipeline); it does not mean
the AI summary is ready. The summary arrives as the SSE summary event, then you fetch
GET /report/{reportId}/summary.
Step 7: Get the Report
curl https://dashboard.socialprofiler.com/api/v1/report/68af01be012b843fd7bc2bf4 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
GET /report/{reportId} returns the slim ReportPage:
{
"profiles": [
{
"source": "ig",
"id": "123456789",
"username": "janedoe",
"fullname": "Jane Doe",
"image": "https://...",
"link": "https://instagram.com/janedoe",
"categoriesCount": 12,
"totalInterests": 45,
"topInterests": [
{"id": "int_1", "name": "Entertainment", "share": 0.25, "relative": 1.0},
{"id": "int_2", "name": "Health & Fitness", "share": 0.18, "relative": 0.72}
]
}
],
"highlights": {
"topCategories": [],
"topInterests": [],
"redzoneInterests": []
},
"redFlags": [],
"friendsPreview": {"items": [], "hasMore": true},
"interestCategoriesPreview": []
}
The heavy lists are separate calls: GET /report/{reportId}/interests (full category trees),
GET /report/{reportId}/friends, GET /report/{reportId}/summary and the per-interest pages. The first read by the report's owner spends the
report credit. See the Report Pipeline for all report endpoints.
Complete Example (Python)
import time
import requests
API_BASE = 'https://dashboard.socialprofiler.com/api/v1'
def create_report(email: str, password: str, name: str, location: str = ''):
# Step 1: Authenticate
auth = requests.post(f'{API_BASE}/auth/signin', json={
'email': email, 'password': password, 'token': True,
})
auth.raise_for_status()
headers = {'Authorization': f'Bearer {auth.json()["token"]}'}
# Step 2: Create the report
fields = {'name': name}
if location:
fields['location'] = location
created = requests.post(f'{API_BASE}/create', headers=headers, json={'fields': fields})
created.raise_for_status()
report_id = created.json()['id']
# Step 3: Run a search round
run = requests.post(
f'{API_BASE}/people-search/run/{report_id}',
headers=headers,
json={'fields': fields},
)
run.raise_for_status()
panels = run.json()['panels']
# Choose the top card of the best network that has a buildable account.
# In a real client, let the user choose.
chosen = None
for source in run.json()['order']:
panel = panels.get(source, {})
for card in panel.get('results', []):
if not card.get('badReason'):
chosen = {'source': card['source'], 'id': card['id']}
break
if chosen:
break
if not chosen:
raise RuntimeError('no account to build a report from')
# Step 5: Confirm (needs a signed-in account)
confirm = requests.post(
f'{API_BASE}/create/{report_id}/confirm', headers=headers, json=[chosen],
)
confirm.raise_for_status()
body = confirm.json()
# estimatedTime and loadTimeout are in SECONDS.
if body['estimatedTime'] > 0:
deadline = time.time() + body['estimatedTime'] + body['loadTimeout']
while time.time() < deadline:
check = requests.get(f'{API_BASE}/check/{report_id}', headers=headers).json()
if check.get('loadError'):
raise RuntimeError(f'could not load {check.get("errorSource")}: {check["loadError"]}')
if check.get('ready'):
break
time.sleep(5)
# Step 7: Read the report
report = requests.get(f'{API_BASE}/report/{report_id}', headers=headers)
report.raise_for_status()
return report.json()
report = create_report('your@email.com', 'your_password', 'Jane Doe', 'Austin')
print(f'Total interests: {report["profiles"][0]["totalInterests"]}')
The loop polls GET /check/{reportId} for brevity; an SSE stream (see Real-time Updates)
reacts faster and shows which account failed.
Next Steps
- People Search Guide - Every call of the search, refinement and confirm
- Report Pipeline Guide - Progress, the readiness check and the report endpoints
- Real-time Updates (SSE) - How to use Server-Sent Events
- Error Handling - Common errors and solutions
- API Reference - Complete endpoint documentation