API Endpoints — Refgrow Docs

Overview

The Refgrow API allows you to integrate affiliate functionality directly into your application. This reference documents the available endpoints, required parameters, and response formats.

All API requests require authentication using your API key, which you can find in your program settings under the "API" tab.

Authentication

To authenticate API requests, include your API key in the request headers:

JSON

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Base URL

All API endpoints use the following base URL:

Bash

https://refgrow.com/api/v1

Affiliate Endpoints

GET/affiliates - List Affiliates

Retrieves a list of all affiliates in your program.

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of affiliates to return (default: 20, max: 100)
`offset`	integer	Number of affiliates to skip (for pagination)
`status`	string	Filter affiliates by status (active, pending, blocked)

Response Example

JSON

{
  "success": true,
  "data": {
    "affiliates": [
      {
        "id": "aff_123456",
        "email": "affiliate@example.com",
        "name": "John Doe",
        "status": "active",
        "createdAt": "2023-06-15T10:30:00Z",
        "totalEarnings": 1250.75,
        "pendingEarnings": 350.25,
        "paidEarnings": 900.50,
        "conversionRate": 0.12,
        "clickCount": 1840,
        "conversionCount": 221
      }
    ],
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

GET/affiliates/:email - Get Affiliate Details

Retrieves detailed information about a specific affiliate by email address.

URL Parameters

Parameter	Type	Description
`email`	string	The affiliate's email address

Response Example

JSON

{
  "success": true,
  "data": {
    "affiliate": {
      "id": "aff_123456",
      "email": "affiliate@example.com",
      "name": "John Doe",
      "status": "active",
      "createdAt": "2023-06-15T10:30:00Z",
      "totalEarnings": 1250.75,
      "pendingEarnings": 350.25,
      "paidEarnings": 900.50,
      "conversionRate": 0.12,
      "clickCount": 1840,
      "conversionCount": 221,
      "referralCode": "JOHNDOE10",
      "paymentMethod": "paypal",
      "paymentDetails": "affiliate@example.com"
    }
  }
}

POST/affiliates - Create Affiliate

Creates a new affiliate in your program.

Request Body Parameters

Parameter	Type	Required	Description
`email`	string	Yes	The affiliate's email address
`name`	string	Yes	The affiliate's full name
`referralCode`	string	No	Custom referral code (if not provided, one will be generated)
`customFields`	object	No	Any additional custom data for the affiliate

Response Example

JSON

{
  "success": true,
  "data": {
    "affiliate": {
      "id": "aff_123456",
      "email": "affiliate@example.com",
      "name": "John Doe",
      "status": "active",
      "createdAt": "2023-06-15T10:30:00Z",
      "referralCode": "JOHNDOE10"
    }
  }
}

Referral Endpoints

GET/referrals - List Referrals

Retrieves a list of referrals in your program.

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of referrals to return (default: 20, max: 100)
`offset`	integer	Number of referrals to skip (for pagination)

Response Example

JSON

{
  "success": true,
  "data": {
    "referrals": [
      {
        "email": "referred@example.com",
        "referral_code": "JOHNDOE10",
        "affiliate_email": "affiliate@example.com",
        "created_at": "2023-06-18T14:25:30Z"
      }
    ],
    "total": 120,
    "limit": 20,
    "offset": 0
  }
}

POST/referrals - Create Referral

Creates a new referral attribution.

Request Body Parameters

Parameter	Type	Required	Description
`email`	string	Yes	The referred customer's email address
`referral_code`	string	Yes	The affiliate's referral code

Response Example

JSON

{
  "success": true,
  "data": {
    "referral": {
      "email": "referred@example.com",
      "referral_code": "JOHNDOE10",
      "created_at": "2023-06-18T15:10:45Z"
    }
  }
}

GET/referrals/:email - Get Referral by Email

Retrieves referral information for a specific email address.

URL Parameters

Parameter	Type	Description
`email`	string	The referred customer's email address

Conversion Endpoints

GET/conversions - List Conversions

Retrieves a list of conversions (registrations and purchases) in your program.

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of conversions to return (default: 20, max: 100)
`offset`	integer	Number of conversions to skip (for pagination)

Response Example

JSON

{
  "success": true,
  "data": {
    "conversions": [
      {
        "id": 12345,
        "customer_email": "customer@example.com",
        "amount": 99.99,
        "commission_amount": 20.00,
        "status": "pending",
        "created_at": "2023-06-18T15:10:45Z",
        "referral_code": "JOHNDOE10"
      }
    ],
    "total": 32,
    "limit": 20,
    "offset": 0
  }
}

POST/conversions - Create Conversion

Creates a new conversion record.

Request Body Parameters

Parameter	Type	Required	Description
`customer_email`	string	Yes	The customer's email address
`amount`	number	Yes	The purchase amount or value of the conversion
`referral_code`	string	No	The affiliate's referral code (used for attribution if no prior referral exists)

Response Example

JSON

{
  "success": true,
  "data": {
    "conversion": {
      "id": 12345,
      "customer_email": "customer@example.com",
      "amount": 99.99,
      "commission_amount": 20.00,
      "referral_code": "JOHNDOE10",
      "created_at": "2023-06-18T15:10:45Z"
    }
  }
}

Coupon Endpoints

GET/coupons - List Coupons

Retrieves a list of coupons in your program.

Response Example

JSON

{
  "success": true,
  "data": {
    "coupons": [
      {
        "id": 1,
        "code": "PARTNER20",
        "affiliate_email": "affiliate@example.com",
        "discount_type": "percentage",
        "discount_value": 20,
        "created_at": "2023-06-15T10:30:00Z"
      }
    ],
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

POST/coupons - Create Coupon

Creates a new coupon linked to an affiliate.

Request Body Parameters

Parameter	Type	Required	Description
`code`	string	Yes	The coupon code
`affiliate_email`	string	Yes	The email of the affiliate to link the coupon to

Response Example

JSON

{
  "success": true,
  "data": {
    "coupon": {
      "id": 1,
      "code": "PARTNER20",
      "affiliate_email": "affiliate@example.com",
      "created_at": "2023-06-15T10:30:00Z"
    }
  }
}

Error Responses

When an error occurs, the API will return an appropriate HTTP status code along with a JSON response containing error details:

JSON

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid affiliate ID format",
    "details": {
      "field": "affiliateId",
      "issue": "must be a string beginning with 'aff_'"
    }
  }
}

Common Error Codes

Error Code	HTTP Status	Description
`authentication_error`	401	Invalid API key or authentication token
`permission_denied`	403	The authenticated user doesn't have permission for the requested operation
`resource_not_found`	404	The requested resource (affiliate, commission, etc.) doesn't exist
`invalid_request`	400	The request parameters are invalid or incomplete
`rate_limit_exceeded`	429	You've exceeded the API rate limit
`server_error`	500	An internal server error occurred

Next Steps

Explore Refgrow's tracking options
Learn about webhooks for real-time notifications
Understand how to secure your API integration