Referral Attribution Service - API Contract

GET /api/v1/referral-attributions/api/v1/referral-attributions

List all referral attributions

Public

Response Example

{
  "data": [
    {
      "id": "attr_a1b2c3",
      "code": "JAN-VERV-8F3A",
      "mentor_id": "usr_4491",
      "type": "click",
      "status": "pending",
      "new_member_id": null,
      "ip_address": "185.12.34.56",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "referrer_url": "https://instagram.com",
      "occurred_at": "2026-03-20T14:22:00Z",
      "created_at": "2026-03-20T14:22:01Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 312
  }
}

GET /api/v1/referral-attributions/api/v1/referral-attributions/:id

Get a referral attribution by ID

Public

Response Example

{
  "id": "attr_a1b2c3",
  "code": "JAN-VERV-8F3A",
  "mentor_id": "usr_4491",
  "type": "click",
  "status": "pending",
  "new_member_id": null,
  "ip_address": "185.12.34.56",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
  "referrer_url": "https://instagram.com",
  "occurred_at": "2026-03-20T14:22:00Z",
  "created_at": "2026-03-20T14:22:01Z"
}

POST /api/v1/referral-attributions/api/v1/referral-attributions

Record a referral click event (recordReferralClick)

Public

Request Example

{
  "code": "JAN-VERV-8F3A",
  "ip_address": "185.12.34.56",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
  "referrer_url": "https://instagram.com",
  "occurred_at": "2026-03-20T14:22:00Z"
}

Response Example

{
  "id": "attr_a1b2c3",
  "code": "JAN-VERV-8F3A",
  "mentor_id": "usr_4491",
  "type": "click",
  "status": "pending",
  "new_member_id": null,
  "ip_address": "185.12.34.56",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
  "referrer_url": "https://instagram.com",
  "occurred_at": "2026-03-20T14:22:00Z",
  "created_at": "2026-03-20T14:22:01Z"
}

PUT /api/v1/referral-attributions/api/v1/referral-attributions/:id

Confirm a recruitment conversion (confirmRecruitment)

Public

Request Example

{
  "code": "JAN-VERV-8F3A",
  "new_member_id": "usr_5892",
  "confirmed_at": "2026-03-25T10:00:00Z"
}

Response Example

{
  "id": "attr_a1b2c3",
  "code": "JAN-VERV-8F3A",
  "mentor_id": "usr_4491",
  "type": "conversion",
  "status": "confirmed",
  "new_member_id": "usr_5892",
  "confirmed_at": "2026-03-25T10:00:00Z",
  "created_at": "2026-03-20T14:22:01Z"
}

DELETE /api/v1/referral-attributions/api/v1/referral-attributions/:id

Remove a referral attribution record

Public

Response Example

{
  "id": "attr_a1b2c3",
  "deleted": true,
  "deleted_at": "2026-03-26T12:00:00Z"
}

GET /api/v1/referral-attributions/api/v1/referral-attributions/mentor/:mentorId

Get all attributions for a mentor (getAttributionsByMentor)

Public

Response Example

{
  "data": [
    {
      "id": "attr_a1b2c3",
      "code": "JAN-VERV-8F3A",
      "mentor_id": "usr_4491",
      "type": "click",
      "status": "pending",
      "new_member_id": null,
      "occurred_at": "2026-03-20T14:22:00Z"
    },
    {
      "id": "attr_b2c3d4",
      "code": "JAN-VERV-8F3A",
      "mentor_id": "usr_4491",
      "type": "conversion",
      "status": "confirmed",
      "new_member_id": "usr_5892",
      "occurred_at": "2026-03-25T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 38
  }
}

GET /api/v1/referral-attributions/api/v1/referral-attributions/mentor/:mentorId/total

Get total confirmed recruitments count for a mentor (getTotalRecruitments)

Public

Response Example

{
  "mentor_id": "usr_4491",
  "total_clicks": 94,
  "total_conversions": 12,
  "conversion_rate": 0.128,
  "period": "all_time"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}