bitcain docs
API Reference

Referrals

Referral program - generate codes, track referrals, earn rewards, and manage payouts

Get Referral Code

GET
/api/v1/referrals/code

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://loading/api/v1/referrals/code"
{
  "code": "string",
  "is_active": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "max_uses": 1,
  "metadata": {},
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "current_uses": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create Referral Code

POST
/api/v1/referrals/code

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Request Body

application/json

code?|

Custom referral code (auto-generated if not provided)

expires_at?|

Code expiration date

max_uses?|

Maximum number of uses

metadata?

Additional metadata

Response Body

application/json

application/json

curl -X POST "https://loading/api/v1/referrals/code" \  -H "Content-Type: application/json" \  -d '{}'
{
  "code": "string",
  "is_active": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "max_uses": 1,
  "metadata": {},
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "current_uses": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Track Referral

POST
/api/v1/referrals/track

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Request Body

application/json

referral_code*string

Referral code to use

Length1 <= length <= 20

Response Body

application/json

application/json

curl -X POST "https://loading/api/v1/referrals/track" \  -H "Content-Type: application/json" \  -d '{    "referral_code": "string"  }'
{
  "referral_code": "string",
  "status": "pending",
  "verification_metadata": {},
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "referrer_id": "4751ff8a-bd55-443e-9163-37cba794193e",
  "referred_id": "4e8ef7e7-026b-4de9-835c-804fee004463",
  "referral_code_id": "f6c3fcad-829d-4cd3-993f-fe09dc7e1db7",
  "verified_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
GET
/api/v1/referrals/link

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://loading/api/v1/referrals/link"
{
  "code": "string",
  "referral_url": "string",
  "shareable_text": "string"
}

Get Referral Stats

GET
/api/v1/referrals/stats

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://loading/api/v1/referrals/stats"
{
  "total_referrals": 0,
  "verified_referrals": 0,
  "pending_referrals": 0,
  "total_earnings": "0",
  "pending_earnings": "0",
  "paid_earnings": "0",
  "total_payouts": 0,
  "last_payout_date": "2019-08-24T14:15:22Z",
  "current_tier_name": "string",
  "commission_rate": "string"
}

Get User Tier

GET
/api/v1/referrals/tier

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://loading/api/v1/referrals/tier"
{
  "tier_id": "b1cd8bf0-c8eb-4fce-9cae-ebe5317fe7f6",
  "current_tier": "string",
  "tier_level": 0,
  "commission_rate": "string",
  "min_referrals": 0,
  "max_referrals": 0,
  "current_referral_count": 0,
  "next_tier": "string",
  "next_tier_level": 0,
  "next_tier_min_referrals": 0,
  "progress_to_next_tier": 0
}

Get Referral History

GET
/api/v1/referrals/history

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Maximum referrals to return

Default50
Range1 <= value <= 200
offset?integer

Offset for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/referrals/history"
[
  {
    "referral_code": "string",
    "status": "pending",
    "verification_metadata": {},
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "referrer_id": "4751ff8a-bd55-443e-9163-37cba794193e",
    "referred_id": "4e8ef7e7-026b-4de9-835c-804fee004463",
    "referral_code_id": "f6c3fcad-829d-4cd3-993f-fe09dc7e1db7",
    "verified_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Get Referral Rewards

GET
/api/v1/referrals/rewards

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Maximum rewards to return

Default50
Range1 <= value <= 200
offset?integer

Offset for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/referrals/rewards"
[
  {
    "reward_type": "signup_bonus",
    "amount": "string",
    "currency": "USD",
    "status": "pending",
    "metadata": {},
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "referral_id": "2d946960-d63d-4137-b67f-4dc8d4a3067c",
    "referrer_id": "4751ff8a-bd55-443e-9163-37cba794193e",
    "referred_id": "4e8ef7e7-026b-4de9-835c-804fee004463",
    "tier_id": "b1cd8bf0-c8eb-4fce-9cae-ebe5317fe7f6",
    "tier_name": "string",
    "commission_rate": "string",
    "paid_at": "2019-08-24T14:15:22Z",
    "payout_id": "89e4daf5-d103-4869-b9da-3d54ecc98dfe",
    "transaction_reference": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Get Payout History

GET
/api/v1/referrals/payouts

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Maximum payouts to return

Default50
Range1 <= value <= 200
offset?integer

Offset for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/referrals/payouts"
[
  {
    "payout_schedule": "weekly",
    "amount": "string",
    "currency": "USD",
    "payment_method": "string",
    "payment_details": {},
    "metadata": {},
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
    "status": "pending",
    "transaction_id": "string",
    "transaction_hash": "string",
    "processed_at": "2019-08-24T14:15:22Z",
    "failed_reason": "string",
    "retry_count": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Request Payout

POST
/api/v1/referrals/payouts/request

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X POST "https://loading/api/v1/referrals/payouts/request"
{}

Preferences

Previous Page

Social

Next Page