Skip to main content

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"}
]
}
  • estimatedTime and loadTimeout are in seconds.
  • estimatedTime: 0 means nothing is left to wait for: read the report now.
  • loads lists accounts whose data is still loading (inited, inprogress), loaded (done) or failed (error, with the reason in error). A failed account cannot be in the report; remove it with POST /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​