Skip to content

Partners API

The Partners API manages the partner/referral program for accountants, advisors, and consultants who refer clients to Carbon Connect. It includes partner registration, authentication, dashboard analytics, referral tracking, commission management, and admin oversight.

Authentication Model

Partners have a separate authentication flow from regular users. Partner tokens use the same JWT format but do not include a tenant_id. Partner-authenticated endpoints use a dedicated CurrentPartner dependency.

Partner Registration and Login

POST /partners/register

Register a new partner account. Partners start with pending status and must be approved by an admin before they can generate referrals.

Authentication: Not required

{
  "email": "advisor@consulting.com",
  "password": "SecureP@ss1",
  "company_name": "Green Advisory Ltd",
  "contact_name": "John Doe",
  "partner_type": "accountant",
  "phone": "+49 30 123456",
  "website": "https://green-advisory.com"
}

{
  "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "email": "advisor@consulting.com",
  "company_name": "Green Advisory Ltd",
  "contact_name": "John Doe",
  "partner_type": "accountant",
  "status": "pending",
  "tier": "bronze",
  "referral_code": "GAL-2025-ABC123",
  "created_at": "2025-01-15T10:30:00Z"
}

curl -X POST https://api.carbonconnect.io/api/v1/partners/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "advisor@consulting.com",
    "password": "SecureP@ss1",
    "company_name": "Green Advisory Ltd",
    "contact_name": "John Doe",
    "partner_type": "accountant"
  }'

Status Codes:

Code Description
201 Partner registered
400 Email already registered
422 Validation error

POST /partners/login

Authenticate a partner and obtain JWT tokens. Uses OAuth2 password flow.

Authentication: Not required

Content-Type: application/x-www-form-urlencoded

username=advisor@consulting.com&password=SecureP@ss1

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

curl -X POST https://api.carbonconnect.io/api/v1/partners/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=advisor@consulting.com&password=SecureP@ss1"

Status Codes:

Code Description
200 Login successful
401 Incorrect email or password
403 Partner account suspended or inactive

Partner Profile

GET /partners/me

Get the current partner's profile.

Authentication: Required (Partner token)

curl -X GET https://api.carbonconnect.io/api/v1/partners/me \
  -H "Authorization: Bearer <partner_token>"

PATCH /partners/me

Update the current partner's profile.

Authentication: Required (Partner token)

{
  "company_name": "Green Advisory Partners",
  "phone": "+49 30 654321",
  "website": "https://green-advisory-partners.com"
}

curl -X PATCH https://api.carbonconnect.io/api/v1/partners/me \
  -H "Authorization: Bearer <partner_token>" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Green Advisory Partners"}'

Partner Analytics

GET /partners/dashboard

Get dashboard statistics for the current partner including referral counts, conversion rates, and commission totals.

Authentication: Required (Partner token)

{
  "total_referrals": 45,
  "active_referrals": 12,
  "converted_referrals": 8,
  "conversion_rate": 0.178,
  "total_commission_earned": 12500.0,
  "pending_commission": 3200.0,
  "paid_commission": 9300.0
}

curl -X GET https://api.carbonconnect.io/api/v1/partners/dashboard \
  -H "Authorization: Bearer <partner_token>"

GET /partners/performance

Get performance metrics over time for the current partner.

Authentication: Required (Partner token)

{
  "items": [
    {
      "month": "2025-01",
      "referrals": 5,
      "conversions": 2,
      "commission": 1500.0
    },
    {
      "month": "2024-12",
      "referrals": 8,
      "conversions": 3,
      "commission": 2200.0
    }
  ],
  "total_months": 12
}

curl -X GET "https://api.carbonconnect.io/api/v1/partners/performance?months=12" \
  -H "Authorization: Bearer <partner_token>"

Query Parameters:

Parameter Type Default Description
months integer 12 Number of months to look back

Referral Tracking

GET /partners/referrals

List referrals for the current partner.

Authentication: Required (Partner token)

{
  "items": [
    {
      "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "referral_code": "GAL-2025-ABC123",
      "utm_source": "email",
      "utm_campaign": "q1-outreach",
      "status": "converted",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20,
  "pages": 3
}

curl -X GET "https://api.carbonconnect.io/api/v1/partners/referrals?page=1&status=converted" \
  -H "Authorization: Bearer <partner_token>"

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
page_size integer 20 Items per page
status string -- Filter by referral status

Commission Tracking

GET /partners/commissions

List commissions for the current partner with summary totals.

Authentication: Required (Partner token)

{
  "items": [
    {
      "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "referral_id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "amount": 1500.0,
      "currency": "EUR",
      "status": "approved",
      "period": "2025-01",
      "created_at": "2025-02-01T00:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "pages": 1,
  "total_pending": 3200.0,
  "total_approved": 5800.0,
  "total_paid": 3500.0
}

curl -X GET "https://api.carbonconnect.io/api/v1/partners/commissions?page=1&status=approved" \
  -H "Authorization: Bearer <partner_token>"

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
page_size integer 20 Items per page
status string -- Filter by commission status

Response Summary Fields:

Field Type Description
total_pending float Total pending commission (EUR)
total_approved float Total approved commission (EUR)
total_paid float Total paid commission (EUR)

Public Referral Endpoints

POST /referrals/click

Record a referral link click. This is called when a prospective client clicks a partner's referral link. No authentication is required.

Authentication: Not required

{
  "referral_code": "GAL-2025-ABC123",
  "utm_source": "email",
  "utm_medium": "newsletter",
  "utm_campaign": "q1-outreach",
  "landing_page": "/pricing"
}

{
  "referral_id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "partner_company": "Green Advisory Ltd",
  "message": "Referral click recorded"
}

curl -X POST https://api.carbonconnect.io/api/v1/referrals/click \
  -H "Content-Type: application/json" \
  -d '{"referral_code": "GAL-2025-ABC123", "utm_source": "email"}'

Request Body:

Field Type Required Description
referral_code string Yes Partner's referral code
utm_source string No UTM source parameter
utm_medium string No UTM medium parameter
utm_campaign string No UTM campaign parameter
landing_page string No Landing page path

Status Codes:

Code Description
200 Click recorded
400 Partner is not active
404 Invalid referral code

Admin Partner Management

Admin Access Required

All endpoints under /admin/partners require the authenticated user to have admin or owner role.

GET /admin/partners

List all partners with filtering options.

Authentication: Required (Admin/Owner)

curl -X GET "https://api.carbonconnect.io/api/v1/admin/partners?status=pending&page=1" \
  -H "Authorization: Bearer <admin_token>"

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
page_size integer 20 Items per page
status string -- Filter by partner status
tier string -- Filter by partner tier
partner_type string -- Filter by partner type

GET /admin/partners/{partner_id}

Get a partner by ID with full admin details.

Authentication: Required (Admin/Owner)

curl -X GET https://api.carbonconnect.io/api/v1/admin/partners/p1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_token>"

PATCH /admin/partners/{partner_id}/status

Update a partner's status. Used to approve, suspend, or deactivate partners.

Authentication: Required (Admin/Owner)

{
  "status": "active",
  "notes": "Verified company credentials, approved for referral program"
}

curl -X PATCH https://api.carbonconnect.io/api/v1/admin/partners/p1a2b3c4-d5e6-7890-abcd-ef1234567890/status \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "active", "notes": "Approved"}'

Request Body:

Field Type Required Description
status string Yes New status: pending, active, suspended, inactive
notes string No Admin notes about the status change

PATCH /admin/partners/{partner_id}/tier

Update a partner's tier and commission rates.

Authentication: Required (Admin/Owner)

{
  "tier": "gold",
  "first_year_commission_rate": 0.15,
  "ongoing_commission_rate": 0.05
}

curl -X PATCH https://api.carbonconnect.io/api/v1/admin/partners/p1a2b3c4-d5e6-7890-abcd-ef1234567890/tier \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"tier": "gold", "first_year_commission_rate": 0.15, "ongoing_commission_rate": 0.05}'

Request Body:

Field Type Required Description
tier string Yes Partner tier: bronze, silver, gold, platinum
first_year_commission_rate float No First year commission rate (0-1)
ongoing_commission_rate float No Ongoing annual commission rate (0-1)

Status Codes:

Code Description
200 Partner updated
401 Not authenticated
403 Insufficient permissions
404 Partner not found