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.

• 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.

• 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

Soft-deletes a client user account. This marks their status as archived and disables their tracking capabilities.

• 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 completely replace the tracking configuration of a domain for a specific user.

[!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.

• 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

Soft-deletes a domain configuration. This sets the status to archived and sets enablement to false.

• 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
  }
]