Skip to main content

Quick Start Guide

This guide walks you through the complete flow of creating a social media profile analysis report using the Socialprofiler API.

Overview​

The report creation flow consists of 6 steps:

1. Authenticate     → Get JWT token
2. Create Report    → Initialize search, get report ID
3. Get Profiles     → Retrieve matched profiles
4. Add Profiles     → Select profiles to analyze
5. Confirm          → Start the analysis
6. Get Report       → Retrieve results

Prerequisites​

  • A Socialprofiler account (sign up at dashboard.socialprofiler.com)
  • Active subscription or available report credits
  • cURL or any HTTP client

Step-by-Step Integration​

Step 1: Authenticate​

Get a JWT token for API access:

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.eyJ1c2VySWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEiLCJleHAiOjE3MDk4MjQwMDB9.abc123..."
}

Save the token value - you'll use it in all subsequent requests.

Step 2: Create Report​

Start a new report by searching for a social media profile:

curl -X POST https://dashboard.socialprofiler.com/api/v1/create \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "ig",
    "username": "jenniferaniston"
  }'

Source codes:

  • ig - Instagram
  • tw - Twitter
  • fb - Facebook
  • tt - TikTok
  • li - LinkedIn

Response:

{
  "id": "68af01be012b843fd7bc2bf4"
}

Save the id value - this is your report ID.

Step 3: Get Matched Profiles​

Retrieve the list of profiles found:

curl https://dashboard.socialprofiler.com/api/v1/create/68af01be012b843fd7bc2bf4 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

{
  "request": {
    "source": "ig",
    "username": "jenniferaniston"
  },
  "profiles": [
    {
      "source": "ig",
      "loaded": true,
      "items": [
        {
          "id": "123456789",
          "source": "ig",
          "username": "jenniferaniston",
          "fullname": "Jennifer Aniston",
          "image": "https://...",
          "link": "https://instagram.com/jenniferaniston"
        }
      ],
      "hasMore": false
    },
    {
      "source": "tw",
      "loaded": true,
      "items": [],
      "hasMore": false
    }
  ]
}

Step 4: Add Profiles to Report​

Add the profiles you want to analyze. One request per account: to include multiple accounts (e.g. from different social networks), call the add endpoint sequentially for each account/source.

curl -X POST https://dashboard.socialprofiler.com/api/v1/create/68af01be012b843fd7bc2bf4/ig/add \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "123456789"
  }'

Response:

{
  "added": true,
  "unloaded": false,
  "status": {
    "type": "follows",
    "status": "inited",
    "id": "123456789",
    "source": "ig"
  }
}

Repeat for each profile you want to include—one POST .../add call per profile/source (no bulk add).

Step 5: Confirm and Start Analysis​

Confirm your selection to start loading profile data. The body must list the same profiles you added in Step 4 (you cannot send a list of accounts in confirm without calling add first).

Steps 1–4 work for an anonymous (guest) session too, but confirm requires a real, signed-in account — it returns 401 if the caller is a guest session with no user ID. Make sure you have signed in (Step 1) with a real account before calling confirm.

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"}
  ]'

Response:

{
  "estimatedTime": 0,
  "loadTimeout": 60000
}
  • estimatedTime: 0 means the data is already loaded
  • Non-zero value indicates milliseconds until data is ready

Step 6: Get the Report​

Retrieve the full analysis report:

curl https://dashboard.socialprofiler.com/api/v1/report/68af01be012b843fd7bc2bf4 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

{
  "profiles": [
    {
      "source": "ig",
      "id": "123456789",
      "username": "jenniferaniston",
      "fullname": "Jennifer Aniston",
      "image": "https://...",
      "link": "https://instagram.com/jenniferaniston",
      "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}
      ],
      "categories": [...],
      "redFlags": [...],
      "friends": {
        "items": [...],
        "hasMore": true,
        "total": 150
      }
    }
  ],
  "summary": {
    "status": "done",
    "result": [
      ["Interests", "Entertainment, Health & Fitness, Travel"],
      ["Personality", "Outgoing and health-conscious individual"]
    ]
  }
}

Monitoring Progress with SSE​

For real-time updates during report generation, connect to the SSE endpoint:

curl -N https://dashboard.socialprofiler.com/api/v1/sse/68af01be012b843fd7bc2bf4 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Event stream:

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"}

Complete Example (Python)​

import requests
import time

API_BASE = 'https://dashboard.socialprofiler.com/api/v1'

def create_report(email: str, password: str, username: str, source: str = 'ig'):
    # Step 1: Authenticate
    auth_response = requests.post(f'{API_BASE}/auth/signin', json={
        'email': email,
        'password': password,
        'token': True
    })
    token = auth_response.json()['token']
    headers = {'Authorization': f'Bearer {token}'}

    # Step 2: Create report
    create_response = requests.post(
        f'{API_BASE}/create',
        headers=headers,
        json={'source': source, 'username': username}
    )
    report_id = create_response.json()['id']
    print(f'Report ID: {report_id}')

    # Step 3: Get profiles
    profiles_response = requests.get(
        f'{API_BASE}/create/{report_id}',
        headers=headers
    )
    profiles = profiles_response.json()['profiles']

    # Step 4: Add first matching profile
    for source_profiles in profiles:
        if source_profiles['items']:
            profile = source_profiles['items'][0]
            requests.post(
                f'{API_BASE}/create/{report_id}/{profile["source"]}/add',
                headers=headers,
                json={'id': profile['id']}
            )
            print(f'Added profile: {profile["username"]}')

            # Step 5: Confirm
            confirm_response = requests.post(
                f'{API_BASE}/create/{report_id}/confirm',
                headers=headers,
                json=[{'source': profile['source'], 'id': profile['id']}]
            )
            estimated_time = confirm_response.json()['estimatedTime']

            if estimated_time > 0:
                print(f'Waiting {estimated_time}ms for data...')
                time.sleep(estimated_time / 1000 + 5)

            break

    # Step 6: Get report
    report_response = requests.get(
        f'{API_BASE}/report/{report_id}',
        headers=headers
    )
    return report_response.json()

# Usage
report = create_report(
    email='your@email.com',
    password='your_password',
    username='jenniferaniston',
    source='ig'
)
print(f'Total interests: {report["profiles"][0]["totalInterests"]}')

Next Steps​