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. API Endpoints Reference

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
}