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
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
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
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
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
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
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
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
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
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
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.