API Reference

Learn how to programmatically interact with your affiliate program data.

API Introduction

Welcome to the Refgrow API documentation. This API allows you to programmatically interact with your affiliate program data, including affiliates and referrals.

The base URL for all API endpoints is: https://refgrow.com

Authentication

API requests must be authenticated. Authentication can be handled via API Keys (recommended for programmatic access) or potentially session cookies if used within the Refgrow dashboard context.

To use API Keys:

  1. Generate an API Key from your Refgrow project settings (Project Settings → API Keys → Generate New Key).
  2. Include the API Key in the `Authorization` header of your requests as a Bearer token:
Authorization: Bearer <YOUR_API_KEY>

All API requests must be made over HTTPS.

Affiliates

Endpoints for managing affiliates within your project.

List Affiliates

GET /api/v1/affiliates

Retrieves a list of affiliates associated with your project. Supports pagination and filtering.

Query Parameters

ParameterTypeRequiredDescription
limitintegerOptionalNumber of affiliates to return (default: 20).
offsetintegerOptionalNumber of affiliates to skip (for pagination, default: 0).
statusstringOptionalFilter by status (e.g., 'active', 'inactive').

Example Request

curl -X GET "https://refgrow.com/api/v1/affiliates?limit=10&status=active" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 123,
      "user_email": "affiliate1@example.com",
      "referral_code": "REF123",
      "created_at": "2024-01-15T10:00:00.000Z",
      "status": "active",
      "clicks": 58,
      "signups": 12,
      "purchases": 5, 
      "unpaid_earnings": "50.00", 
      "total_earnings": "150.00" 
    },
    {
      "id": 125,
      "user_email": "affiliate2@example.com",
      "referral_code": "AFF2",
      "created_at": "2024-03-20T14:00:00.000Z",
      "status": "active",
      "clicks": 120,
      "signups": 25,
      "purchases": 15,
      "unpaid_earnings": "110.50",
      "total_earnings": "320.75"
    }
    // ... more affiliates
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 55,
    "has_more": true
  }
}

Error Responses

  • 401 Unauthorized: Missing or invalid API key.
  • 403 Forbidden: API key doesn't have permission to access this resource.

Create Affiliate

POST /api/v1/affiliates

Creates a new affiliate for your project.

Request Body (JSON)

ParameterTypeRequiredDescription
emailstringYesThe email address of the affiliate. Must be unique per project.
referral_codestringOptionalA unique referral code for the affiliate. If omitted, one will be generated automatically.

Example Request

curl -X POST "https://refgrow.com/api/v1/affiliates" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
      "email": "new.affiliate@example.com",
      "referral_code": "NEWCODE"
    }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 124,
    "user_email": "new.affiliate@example.com",
    "referral_code": "NEWCODE",
    "unpaid_earnings": null,  
    "total_earnings": null,   
    "created_at": "2024-07-29T12:30:00.000Z",
    "status": "active" 
    // Note: Calculated fields like clicks, signups, purchases, earnings 
    // are typically not returned on creation. Fetch separately if needed.
  }
}

Error Responses

  • 400 Bad Request: Invalid email or other parameters.
  • 409 Conflict: Email or referral code already exists for this project.

Retrieve Affiliate

GET /api/v1/affiliates/:email

Retrieves details, including calculated stats, for a specific affiliate by their email address.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the affiliate to retrieve.

Example Request

curl -X GET "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "user_email": "affiliate1@example.com",
    "referral_code": "REF123",
    "created_at": "2024-01-15T10:00:00.000Z",
    "status": "active",
    "clicks": 58,
    "signups": 12,
    "purchases": 5,
    "unpaid_earnings": "50.00", 
    "total_earnings": "150.00" 
  }
}

Error Responses

  • 400 Bad Request: Invalid email format in URL.
  • 404 Not Found: Affiliate with the specified email not found for this project.

Update Affiliate

PUT /api/v1/affiliates/:email

Updates specific details for an existing affiliate identified by their email address.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the affiliate to update.

Request Body (JSON)

Include only the fields you want to update.

ParameterTypeDescription
emailstringNew email address for the affiliate. Must be unique per project.
referral_codestringNew unique referral code for the affiliate.
statusstringUpdate the status ('active' or 'inactive').

Example Request

curl -X PUT "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
      "status": "inactive"
    }'

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "user_email": "affiliate1@example.com", 
    "referral_code": "REF123", 
    "unpaid_earnings": null, 
    "total_earnings": null,  
    "created_at": "2024-01-15T10:00:00.000Z", 
    "status": "inactive" 
    // Note: Calculated fields are not typically returned on update.
    // The core affiliate fields (email, code, status) are updated.
  }
}

Error Responses

  • 400 Bad Request: Invalid parameters or email format in URL.
  • 404 Not Found: Affiliate not found.
  • 409 Conflict: New email or referral code conflicts with another affiliate.

Delete Affiliate

DELETE /api/v1/affiliates/:email

Permanently deletes an affiliate (identified by email) and all associated data.

Warning: This action is irreversible.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the affiliate to delete.

Example Request

curl -X DELETE "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

  • 400 Bad Request: Invalid email format in URL.
  • 404 Not Found: Affiliate not found.
  • 500 Internal Server Error: If an error occurs during the deletion cascade.

Referrals

Endpoints for managing referred users associated with your affiliates.

List Referrals

GET /api/v1/referrals

Retrieves a list of referred users for your project. Supports pagination and filtering.

Query Parameters

ParameterTypeRequiredDescription
limitintegerOptionalNumber of referrals to return (default: 20).
offsetintegerOptionalNumber of referrals to skip (for pagination, default: 0).
affiliate_idintegerOptionalFilter referrals by the associated affiliate ID.
statusstringOptionalFilter by conversion status (e.g., 'pending', 'converted', 'direct', 'direct_signup').

Example Request

curl -X GET "https://refgrow.com/api/v1/referrals?affiliate_id=123&status=converted" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 501,
      "user_email": "customer1@example.com",
      "conversion_status": "converted",
      "conversion_date": "2024-02-10T11:05:00.000Z",
      "created_at": "2024-02-01T09:00:00.000Z",
      "affiliate_id": 123,
      "affiliate_code": "REF123"
    },
    // ... more referred users
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 5,
    "has_more": false
  }
}

Error Responses

  • 401 Unauthorized: Missing or invalid API key.
  • 403 Forbidden: API key doesn't have permission to access this resource.

Create Referral

POST /api/v1/referrals

Manually creates a new referred user record. This is typically handled automatically by tracking, but can be used for manual attribution.

Request Body (JSON)

ParameterTypeRequiredDescription
emailstringYesThe email address of the referred user. Must be unique per project.
affiliate_idintegerOptionalThe ID of the affiliate who referred this user. If omitted, the user will be considered a direct signup unless status indicates otherwise.
statusstringOptionalThe conversion status ('pending', 'converted', 'direct', 'direct_signup'). Defaults to 'pending'. If set to 'converted' or 'direct', `conversion_date` will be set to the current time.

Example Request

curl -X POST "https://refgrow.com/api/v1/referrals" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
      "email": "manual.customer@example.com",
      "affiliate_id": 123,
      "status": "converted"
    }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 502,
    "user_email": "manual.customer@example.com",
    "affiliate_id": 123,
    "conversion_status": "converted",
    "conversion_date": "2024-07-29T13:00:00.000Z",
    "created_at": "2024-07-29T13:00:00.000Z"
  }
}

Error Responses

  • 400 Bad Request: Invalid email or other parameters.
  • 404 Not Found: Specified `affiliate_id` does not exist.
  • 409 Conflict: Referred user with this email already exists for this project.

Retrieve Referral

GET /api/v1/referrals/:email

Retrieves details for a specific referred user by their email address.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the referred user to retrieve.

Example Request

curl -X GET "https://refgrow.com/api/v1/referrals/customer1%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 501,
    "user_email": "customer1@example.com",
    "conversion_status": "converted",
    "conversion_date": "2024-02-10T11:05:00.000Z",
    "created_at": "2024-02-01T09:00:00.000Z",
    "affiliate_id": 123,
    "affiliate_code": "REF123"
  }
}

Error Responses

  • 400 Bad Request: Invalid email format in URL.
  • 404 Not Found: Referred user not found for this project.

Update Referral

PUT /api/v1/referrals/:email

Updates specific details for an existing referred user identified by their email address.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the referred user to update.

Request Body (JSON)

Include only the fields you want to update.

ParameterTypeDescription
emailstringNew email address for the referred user. Must be unique per project.
affiliate_idinteger | nullChange the associated affiliate ID, or set to `null` to disassociate.
statusstringUpdate the conversion status ('pending', 'converted', 'direct', 'direct_signup'). Setting to 'converted' or 'direct' updates `conversion_date`.

Example Request

curl -X PUT "https://refgrow.com/api/v1/referrals/manual.customer%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
      "affiliate_id": null,
      "status": "direct"
    }'

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 502,
    "user_email": "manual.customer@example.com",
    "affiliate_id": null,
    "conversion_status": "direct",
    "conversion_date": "2024-07-29T13:15:00.000Z", // Updated conversion date
    "created_at": "2024-07-29T13:00:00.000Z"
  }
}

Error Responses

  • 400 Bad Request: Invalid parameters or email format in URL.
  • 404 Not Found: Referred user or specified `affiliate_id` not found.
  • 409 Conflict: New email conflicts with another referred user.

Delete Referral

DELETE /api/v1/referrals/:email

Permanently deletes a referred user record (identified by email) and any associated conversion records.

Warning: This action is irreversible.

Path Parameters

ParameterTypeDescription
emailstringThe URL-encoded email address of the referred user to delete.

Example Request

curl -X DELETE "https://refgrow.com/api/v1/referrals/manual.customer%40example.com" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

  • 400 Bad Request: Invalid email format in URL.
  • 404 Not Found: Referred user not found.
  • 500 Internal Server Error: If an error occurs during deletion.