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:

Generate an API Key from your Refgrow project settings (Project Settings → API Keys → Generate New Key).
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

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of affiliates to return (default: 20).
`offset`	integer	Optional	Number of affiliates to skip (for pagination, default: 0).
`status`	string	Optional	Filter 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)

Parameter	Type	Required	Description
`email`	string	Yes	The email address of the affiliate. Must be unique per project.
`referral_code`	string	Optional	A 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

Parameter	Type	Description
`email`	string	The 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

Parameter	Type	Description
`email`	string	The URL-encoded email address of the affiliate to update.

Request Body (JSON)

Include only the fields you want to update.

Parameter	Type	Description
`email`	string	New email address for the affiliate. Must be unique per project.
`referral_code`	string	New unique referral code for the affiliate.
`status`	string	Update 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

Parameter	Type	Description
`email`	string	The 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

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of referrals to return (default: 20).
`offset`	integer	Optional	Number of referrals to skip (for pagination, default: 0).
`affiliate_id`	integer	Optional	Filter referrals by the associated affiliate ID.
`status`	string	Optional	Filter 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)

Parameter	Type	Required	Description
`email`	string	Yes	The email address of the referred user. Must be unique per project.
`affiliate_id`	integer	Optional	The ID of the affiliate who referred this user. If omitted, the user will be considered a direct signup unless status indicates otherwise.
`status`	string	Optional	The 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

Parameter	Type	Description
`email`	string	The 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

Parameter	Type	Description
`email`	string	The URL-encoded email address of the referred user to update.

Request Body (JSON)

Include only the fields you want to update.

Parameter	Type	Description
`email`	string	New email address for the referred user. Must be unique per project.
`affiliate_id`	integer \| null	Change the associated affiliate ID, or set to `null` to disassociate.
`status`	string	Update 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

Parameter	Type	Description
`email`	string	The 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.