Skip to content

Partner Onboarding & Integration Guide

This guide details the integration flow for the Social Signal Partner API. Partners can programmatically provision client accounts (Users) and register/configure tracking domains (Domains).

1. Authentication

All requests to the Partner API must be authenticated using your Partner API Key. Pass this key in the Authorization header as a Bearer token:

Authorization: Bearer <YOUR_PARTNER_API_KEY>
  • Base URL: https://beacon.socialsignal.ai/api/v2
  • Partner ID (PID) for this integration: SDL

2. Accounts Management & One-Shot Provisioning (/partner/accounts)

The Accounts API provides the primary interface for managing client accounts. It supports one-shot account creation (provisioning User + Login + Primary Domain in a single POST call) and hydrated object inspection (GET with ?expand=domains,logins,metrics).

2.1 One-Shot Account Provisioning

Provision a complete client account, admin login, and primary tracking domain in 1 single HTTP request.

  • Method: POST
  • Path: /partner/accounts
  • Example Request (HTTPie):
http POST https://beacon.socialsignal.ai/api/v2/partner/accounts \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  _id="SDLR_D10000" \
  company="Super Dealer LLC" \
  login:='{"email":"admin@superdealer.com","password":"SecurePassword123!"}' \
  domain:='{"domain":"superdealer.com","monthlyCredits":250,"enablement":true}' \
  --ignore-stdin
  • Example Response (201 Created):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "company": "Super Dealer LLC",
  "status": "active",
  "logins": [
    { "email": "admin@superdealer.com", "_id": "SDLR_D10000", "pid": "SDL", "type": "user" }
  ],
  "domains": [
    {
      "_id": "SDLR_D10000",
      "pid": "SDL",
      "domain": "superdealer.com",
      "monthlyCredits": 250,
      "enablement": true,
      "status": "active"
    }
  ]
}

2.2 Get Account Details (Hydrated)

Retrieve a full composite account object including associated logins, domains, and KPI metrics.

  • Method: GET
  • Path: /partner/accounts/SDLR_D10000?expand=domains,logins,metrics
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/accounts/SDLR_D10000?expand=domains,logins,metrics" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin

2.3 List Partner Accounts

Retrieve all client accounts belonging to your partner identity.

  • Method: GET
  • Path: /partner/accounts
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/accounts?expand=domains,logins" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin

3. Legacy User & Domain Endpoints Reference (Standalone)

2.1 Create Partner User

Provision a new client account under your reselling partner identity.

[!NOTE] If a user with that _id already exists, the call returns 409 and changes nothing. That includes an archived user: create does not bring it back, restore it with PATCH (see 2.4). A _id that belongs to another partner also returns 409.

  • Method: POST
  • Path: /partner/users
  • Request Body:
{
  "_id": "SDLR_D10000",
  "company": "Super Dealer",
  "domains": ["superdealer.com"]
}
  • Example Request (HTTPie):
http POST https://beacon.socialsignal.ai/api/v2/partner/users \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  _id="SDLR_D10000" \
  company="Super Dealer" \
  domains:='["superdealer.com"]' \
  --ignore-stdin
  • Example Response (201 Created):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "company": "Super Dealer",
  "domains": ["superdealer.com"],
  "status": "active"
}

2.2 List Partner Users

Retrieve all active and non-archived user records belonging to your partner ID (SDL).

  • Method: GET
  • Path: /partner/users
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "_id": "SDLR_D10000",
    "pid": "SDL",
    "company": "Super Dealer",
    "domains": ["superdealer.com"],
    "status": "active"
  }
]

2.3 Get Partner User

Retrieve details of a specific user account under your partner namespace.

  • Method: GET
  • Path: /partner/users/SDLR_D10000
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000 \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "company": "Super Dealer",
  "domains": ["superdealer.com"],
  "status": "active"
}

2.4 Update Partner User

Modify fields on a specific user record. Only the fields you send change.

[!NOTE] An archived user can only be restored: send {"status": "active"} and nothing else. Any other change to an archived user returns 404.

  • Method: PATCH
  • Path: /partner/users/SDLR_D10000
  • Request Body:
{
  "company": "Super Dealer Group",
  "status": "active"
}
  • Example Request (HTTPie):
http PATCH https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000 \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  company="Super Dealer Group" \
  status="active" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "company": "Super Dealer Group",
  "domains": ["superdealer.com"],
  "status": "active"
}

2.5 Delete/Archive Partner User

Archives a client user account. Only status changes (to archived): the account's plan, credits, domains and settings stay as they were. Within a few minutes its tracking and lead collection stop, and its API key and sign-in are refused with 403 ACCOUNT_INACTIVE. The call is safe to repeat, and an archived user no longer appears in your user list. To bring the account back, PATCH it with {"status": "active"} (see 2.4); creating a user with the same _id returns 409 and does not restore it.

  • Method: DELETE
  • Path: /partner/users/SDLR_D10000
  • Example Request (HTTPie):
http DELETE https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000 \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "success": true
}

2.6 Create/Replace Domain Config

Add or replace the tracking configuration of a domain for a specific user.

[!NOTE] The call replaces the settings in the request body: any you leave out go back to their defaults (enablement false, credits 0, minVisitsToMatch 2, status active), so send every value you want to keep. Settings this API does not expose, such as the lead delivery flow and other configuration, are never changed. instantCredits is never lowered. To change one field, use PATCH (see 2.9). The user must not be archived.

[!NOTE] The monthlyCredits field must be set to one of the allowed subscription increments: 0, 75, 250, 1000, or 2500.

  • Method: PUT
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com
  • Request Body:
{
  "enablement": true,
  "instantCredits": 100,
  "weeklyCredits": 0,
  "monthlyCredits": 250,
  "minVisitsToMatch": 2,
  "status": "active"
}
  • Example Request (HTTPie):
http PUT https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  enablement:=true \
  instantCredits:=100 \
  weeklyCredits:=0 \
  monthlyCredits:=250 \
  minVisitsToMatch:=2 \
  status="active" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "domain": "superdealer.com",
  "enablement": true,
  "instantCredits": 100,
  "weeklyCredits": 0,
  "monthlyCredits": 250,
  "minVisitsToMatch": 2,
  "status": "active",
  "collectLeads": false
}

2.7 List Partner Domains

Retrieve all configured domains for a specific user.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/domains
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "_id": "SDLR_D10000",
    "pid": "SDL",
    "domain": "superdealer.com",
    "enablement": true,
    "instantCredits": 100,
    "weeklyCredits": 0,
    "monthlyCredits": 250,
    "minVisitsToMatch": 2,
    "status": "active",
    "collectLeads": false
  }
]

2.8 Get Partner Domain Config

Retrieve configuration details for a specific registered domain.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "domain": "superdealer.com",
  "enablement": true,
  "instantCredits": 100,
  "weeklyCredits": 0,
  "monthlyCredits": 250,
  "minVisitsToMatch": 2,
  "status": "active",
  "collectLeads": false
}

2.9 Update Partner Domain Config

Selectively update properties of an active domain config.

[!NOTE] An archived domain can only be restored: send {"status": "active"}, optionally with "enablement": true, and nothing else. Any other change to an archived domain returns 404. A domain under an archived user cannot be restored until the user is.

  • Method: PATCH
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com
  • Request Body:
{
  "minVisitsToMatch": 3,
  "enablement": false
}
  • Example Request (HTTPie):
http PATCH https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  minVisitsToMatch:=3 \
  enablement:=false \
  --ignore-stdin
  • Example Response (200 OK):
{
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "domain": "superdealer.com",
  "enablement": false,
  "instantCredits": 100,
  "weeklyCredits": 0,
  "monthlyCredits": 250,
  "minVisitsToMatch": 3,
  "status": "active",
  "collectLeads": false
}

2.10 Delete/Archive Domain Config

Archives a domain configuration: status becomes archived and enablement becomes false. Everything else on the configuration, including its credits, is kept, and the domain stays in the user's domains list. Tracking for that domain stops within a few minutes. The call is safe to repeat. To bring it back, PATCH it (see 2.9) with {"status": "active", "enablement": true}.

  • Method: DELETE
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com
  • Example Request (HTTPie):
http DELETE https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "success": true
}

3. Login Credentials Management

Use these endpoints to provision and manage access credentials for partner sub-users.

3.1 Provision User Login

Create a login email and password for a provisioned partner user account.

  • Method: POST
  • Path: /partner/logins
  • Example Request (HTTPie):
http POST https://beacon.socialsignal.ai/api/v2/partner/logins \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  email="jane@superdealer.com" \
  password="SuperSecurePassword123!" \
  _id="SDLR_D10000" \
  --ignore-stdin
  • Example Response (201 Created):
{
  "email": "jane@superdealer.com",
  "_id": "SDLR_D10000",
  "pid": "SDL",
  "type": "user"
}

3.2 List Partner Logins

Retrieve login credentials provisioned under your partner account.

  • Method: GET
  • Path: /partner/logins
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/logins \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin

3.3 Get Login Record

Retrieve single login details by email.

  • Method: GET
  • Path: /partner/logins/jane@superdealer.com
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/logins/jane@superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin

3.4 Reset Login Password

Update/reset the password for a user login email.

  • Method: PATCH
  • Path: /partner/logins/jane@superdealer.com
  • Example Request (HTTPie):
http PATCH https://beacon.socialsignal.ai/api/v2/partner/logins/jane@superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  password="NewSecurePassword456!" \
  --ignore-stdin

3.5 Revoke/Delete Login Record

Delete a login record by email.

  • Method: DELETE
  • Path: /partner/logins/jane@superdealer.com
  • Example Request (HTTPie):
http DELETE https://beacon.socialsignal.ai/api/v2/partner/logins/jane@superdealer.com \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin

4. Metrics & Analytics

Use these endpoints to query aggregated metrics and trends across your resold client portfolio for partner portal dashboards.

3.1 Get Partner Metrics Summary

Retrieve partner-wide high-level metrics (active client accounts, domains, credits, and traffic stats).

  • Method: GET
  • Path: /partner/metrics/summary
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/metrics/summary \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "totalUsers": 12,
  "totalDomains": 18,
  "totalCreditsRemaining": 5450,
  "visitsToday": 248,
  "visitsThisWeek": 1850,
  "visitsThisMonth": 7890,
  "leadsToday": 14,
  "leadsThisWeek": 98,
  "leadsThisMonth": 412,
  "overallMatchRate": 5.22
}

3.2 Get Per-Domain Metrics Breakdown

Retrieve a list of all domain records and their respective remaining credits and rolling lead counts.

  • Method: GET
  • Path: /partner/metrics/domains
  • Query Parameters:
  • limit (optional): Pagination size limit (default 20, max 100).
  • offset (optional): Pagination offset (default 0).
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/metrics/domains?limit=5" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "userId": "SDLR_D10000",
    "company": "Super Dealer",
    "domain": "superdealer.com",
    "status": "active",
    "leadsToday": 4,
    "leadsThisWeek": 28,
    "leadsThisMonth": 120,
    "creditsRemaining": 880
  }
]

3.3 Get Partner Performance Timeseries

Retrieve daily rolling visit and lead match counts over a historical window (default 30 days) to plot performance charts.

  • Method: GET
  • Path: /partner/metrics/timeseries
  • Query Parameters:
  • days (optional): Number of historical days to fetch (default 30, max 90).
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/metrics/timeseries?days=7" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "date": "2026-07-15",
    "visits": 180,
    "leads": 9,
    "matchRate": 5.0
  },
  {
    "date": "2026-07-16",
    "visits": 210,
    "leads": 12,
    "matchRate": 5.71
  }
]

3.4 Get User Metrics Summary

Retrieve high-level metrics and remaining credits aggregated across all domains for a specific user under the partner.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/metrics/summary
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/metrics/summary \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "totalUsers": 1,
  "totalDomains": 1,
  "totalCreditsRemaining": 880,
  "visitsToday": 24,
  "visitsThisWeek": 180,
  "visitsThisMonth": 790,
  "leadsToday": 2,
  "leadsThisWeek": 14,
  "leadsThisMonth": 60,
  "overallMatchRate": 7.59
}

3.5 Get User Performance Timeseries

Retrieve daily rolling visit and lead match counts for a specific user over a historical window (default 30 days) to plot client-specific charts.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/metrics/timeseries
  • Query Parameters:
  • days (optional): Number of historical days to fetch (default 30, max 90).
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/metrics/timeseries?days=7" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "date": "2026-07-15",
    "visits": 20,
    "leads": 1,
    "matchRate": 5.0
  }
]

3.6 Get Domain Metrics Summary

Retrieve metrics (credits remaining, match rates, and traffic stats) for a single tracking domain registered to a partner user.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com/metrics/summary
  • Example Request (HTTPie):
http GET https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com/metrics/summary \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
{
  "totalUsers": 1,
  "totalDomains": 1,
  "totalCreditsRemaining": 880,
  "visitsToday": 10,
  "visitsThisWeek": 75,
  "visitsThisMonth": 310,
  "leadsToday": 1,
  "leadsThisWeek": 6,
  "leadsThisMonth": 24,
  "overallMatchRate": 7.74
}

3.7 Get Domain Performance Timeseries

Retrieve daily rolling visit and lead match counts for a specific tracking domain over a historical window (default 30 days) to plot domain-specific charts.

  • Method: GET
  • Path: /partner/users/SDLR_D10000/domains/superdealer.com/metrics/timeseries
  • Query Parameters:
  • days (optional): Number of historical days to fetch (default 30, max 90).
  • Example Request (HTTPie):
http GET "https://beacon.socialsignal.ai/api/v2/partner/users/SDLR_D10000/domains/superdealer.com/metrics/timeseries?days=7" \
  Authorization:"Bearer <YOUR_PARTNER_API_KEY>" \
  --ignore-stdin
  • Example Response (200 OK):
[
  {
    "date": "2026-07-15",
    "visits": 12,
    "leads": 1,
    "matchRate": 8.33
  }
]