RefRef

https://refref.ai/docs
Admin
RefRef is an open source referral marketing platform that helps businesses build and manage referral...
Tokens:28,340
Snippets:381
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Successful response for get program by ID

Source: https://refref.ai/docs/api/get-program-by-id

Example 200 response body containing the program object with id, name, description, startDate, endDate, status, createdAt, and updatedAt fields.

```json
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "startDate": "2019-08-24",
    "endDate": "2019-08-24",
    "status": "active",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

--------------------------------

### 200 response for GET /programs

Source: https://refref.ai/docs/api/get-programs

Example successful response containing a list of programs and pagination metadata. The response includes fields like id, name, description, startDate, endDate, status, createdAt, updatedAt, and meta with total, limit, and offset.

```json
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "startDate": "2019-08-24",
      "endDate": "2019-08-24",
      "status": "active",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

--------------------------------

### Successful response for get all participants

Source: https://refref.ai/docs/api/get-participants

Example of a 200 response containing a list of participants and pagination metadata.

```json
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
      "firstName": "string",
      "lastName": "string",
      "email": "user@example.com",
      "status": "active",
      "joinedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

--------------------------------

### Quick Start: Pull and Start RefRef with Docker Compose

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest RefRef image and start the containers with docker-compose. Requires Docker 20.10+ and Docker Compose.

```bash
# Pull the latest RefRef image
docker pull refref/refref:latest
 
# Create a docker-compose.yml file with the necessary configuration
# Start the containers
docker-compose up -d
```

--------------------------------

### GET /programs

Source: https://refref.ai/docs/api/get-programs

Retrieves a list of all programs. Supports filtering by status and pagination through limit and offset parameters.

```APIDOC
## GET /programs

### Description
Retrieves a list of all programs.

### Method
GET

### Endpoint
/`programs`

### Parameters
#### Query Parameters
- **`status`** (string) - Optional - Filter programs by status. Value in: `"active" | "inactive" | "completed"`
- **`limit`** (integer) - Optional - Maximum number of programs to return. Default: `20` Minimum: `1` Maximum: `100`
- **`offset`** (integer) - Optional - Number of programs to skip. Default: `0` Minimum: `0`

### Authentication
API key authentication via header `api-key` or query parameter `api-key`.

### Request Example
```
curl -X GET "https://api.refref.com/v1/programs?status=active" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
Successful operation

#### Response Example
```
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "startDate": "2019-08-24",
      "endDate": "2019-08-24",
      "status": "active",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

### Error Responses
- 401 - Unauthorized
- 500 - Internal Server Error
```

--------------------------------

### Successful response for get participant by ID

Source: https://refref.ai/docs/api/get-participant-by-id

Example of a 200 response containing the participant data. The response includes id, programId, firstName, lastName, email, status, joinedAt, createdAt, and updatedAt.

```JSON
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "status": "active",
    "joinedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

--------------------------------

### GET /programs/{programId}

Source: https://refref.ai/docs/api/get-program-by-id

Retrieves a specific program by its unique identifier. Requires API key authentication via header or query parameter.

```APIDOC
## GET /programs/{programId}

### Description
Retrieve a specific program by its ID.

### Method
GET

### Endpoint
/programs/{programId}

### Authentication
- **api-key** (string, header) - Required - API key authentication.
- **api-key** (string, query) - Required - API key authentication via query parameter.

### Path Parameters
- **programId** (string, format: uuid) - Required - ID of the program to retrieve.

### Request Example
```
curl -X GET "https://api.refref.com/v1/programs/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data.id** (string) - The program ID.
- **data.name** (string) - The program name.
- **data.description** (string) - The program description.
- **data.startDate** (string, date) - The program start date.
- **data.endDate** (string, date) - The program end date.
- **data.status** (string) - The program status (e.g., active).
- **data.createdAt** (string, date-time) - The program creation timestamp.
- **data.updatedAt** (string, date-time) - The program last update timestamp.

#### Response Example
```
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "startDate": "2019-08-24",
    "endDate": "2019-08-24",
    "status": "active",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

### Error Responses
- **401** - Unauthorized.
- **404** - Not found.
- **500** - Internal server error.

```

--------------------------------

### cURL request to GET /programs

Source: https://refref.ai/docs/api/get-programs

Sends a GET request to https://api.refref.com/v1/programs with the status query parameter set to 'active'. Requires an API key in the 'api-key' header.

```bash
curl -X GET "https://api.refref.com/v1/programs?status=active" \
  -H "api-key: <token>"
```

--------------------------------

### cURL request to get all participants

Source: https://refref.ai/docs/api/get-participants

Use this cURL command to fetch participants with optional query parameters. The API key is passed in the 'api-key' header.

```bash
curl -X GET "https://api.refref.com/v1/participants?programId=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=active" \
  -H "api-key: <token>"
```

--------------------------------

### GET /participants

Source: https://refref.ai/docs/api/get-participants

Retrieves a list of all participants. Supports filtering by program ID and status, and pagination with limit and offset.

```APIDOC
## [GET] /participants

### Description
Retrieve a list of all participants

### Method
GET

### Endpoint
/participants

### Parameters
#### Query Parameters
- **programId** (string) - Optional - Filter participants by program ID. Format: `"uuid"`
- **status** (string) - Optional - Filter participants by status. Value in: `"active" | "inactive" | "completed"`
- **limit** (integer) - Optional - Maximum number of participants to return. Default: `20`, Minimum: `1`, Maximum: `100`
- **offset** (integer) - Optional - Number of participants to skip. Default: `0`, Minimum: `0`

### Request Example
```
curl -X GET "https://api.refref.com/v1/participants?programId=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=active" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data** (array) - List of participants
  - **id** (string) - Participant ID
  - **programId** (string) - Program ID
  - **firstName** (string) - First name
  - **lastName** (string) - Last name
  - **email** (string) - Email address
  - **status** (string) - Participant status
  - **joinedAt** (string) - Join date
  - **createdAt** (string) - Creation date
  - **updatedAt** (string) - Last update date
- **meta** (object) - Pagination metadata
  - **total** (integer) - Total number of participants
  - **limit** (integer) - Limit used
  - **offset** (integer) - Offset used

#### Response Example
```
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
      "firstName": "string",
      "lastName": "string",
      "email": "user@example.com",
      "status": "active",
      "joinedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

### Authentication
- **api-key** (header) - API key authentication
- **api-key** (query) - API key authentication via query parameter

### Error Responses
- **401** - Unauthorized
- **500** - Internal Server Error
```

--------------------------------

### Fire events with refcode

Source: https://refref.ai/docs/platform/installation/attribution-script

When a qualifying event occurs (signup, purchase, etc.), include the refcode in your event creation. This example shows a fetch request to the RefRef API.

```javascript
// After user signs up
await fetch('https://api.refref.app/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_API_KEY}`
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    externalId: user.id, // Your user's ID
    eventType: 'signup',
    refcode: storedRefcode, // The refcode from attribution
    metadata: {
      email: user.email,
      signupDate: new Date().toISOString()
    }
  })
});
```

--------------------------------

### Customize Widget Styling

Source: https://refref.ai/docs/platform/installation/widget

Customize the widget's appearance using CSS custom properties. The example shows light and dark theme overrides.

```css
refref-widget {
  --refref-primary-color: #3b82f6;
  --refref-border-radius: 8px;
  --refref-font-family: 'Inter', sans-serif;
  --refref-background: #ffffff;
  --refref-text-color: #1f2937;
}
 
/* Dark theme */
refref-widget[theme="dark"] {
  --refref-background: #1f2937;
  --refref-text-color: #f9fafb;
}
```

--------------------------------

### cURL request to get program by ID

Source: https://refref.ai/docs/api/get-program-by-id

Use this cURL command to retrieve a program by its ID. Requires an API key passed in the api-key header. The programId is a UUID path parameter.

```bash
curl -X GET "https://api.refref.com/v1/programs/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

--------------------------------

### Sample Docker Compose Configuration for RefRef

Source: https://refref.ai/docs/platform/self-hosting/docker

A docker-compose.yml file defining RefRef, PostgreSQL, and Redis services. Sets environment variables for database and Redis connections, and uses named volumes for data persistence.

```yaml
version: '3.8'
 
services:
  refref:
    image: refref/refref:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/refref
      - REDIS_URL=redis://redis:6379
      # Add other environment variables as needed
    depends_on:
      - db
      - redis
 
  db:
    image: postgres:14
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=refref
 
  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
 
volumes:
  postgres_data:
  redis_data:
```

--------------------------------

### Initialize Without JWT

Source: https://refref.ai/docs/platform/widget

Initialize the widget without JWT authentication using only externalId. Only use if 'Enforce Referral Authentication' is disabled in product settings.

```javascript
window.RefRef.init({
  productId: 'your-product-id',
  externalId: 'user-123' // Your user's unique identifier
});
```

--------------------------------

### Upgrading RefRef Docker Deployment

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest image and restart containers. Always back up data before upgrading.

```bash
# Pull the latest image (or specific version)
docker pull refref/refref:latest
 
# Restart your containers
docker-compose down
docker-compose up -d
```

--------------------------------

### cURL request to get participant by ID

Source: https://refref.ai/docs/api/get-participant-by-id

Use this cURL command to retrieve a participant by their ID. Replace <token> with your API key. The participantId is a UUID.

```cURL
curl -X GET "https://api.refref.com/v1/participants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

--------------------------------

### GET /participants/{participantId}

Source: https://refref.ai/docs/api/get-participant-by-id

Retrieves a specific participant by their ID. The participant ID is provided as a path parameter, and the response contains the participant's details.

```APIDOC
## GET /participants/{participantId}

### Description
Retrieve a specific participant by their ID

### Method
GET

### Endpoint
/participants/{participantId}

### Parameters
#### Path Parameters
- **participantId** (string) - Required - ID of the participant to retrieve. Format: `"uuid"`

#### Headers
- **api-key** (string) - Required - API key authentication. In: `header`

#### Query Parameters
- **api-key** (string) - Required - API key authentication via query parameter. In: `query`

### Request Example
```
curl -X GET "https://api.refref.com/v1/participants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data** (object) - Participant data
  - **id** (string) - Participant ID
  - **programId** (string) - Program ID
  - **firstName** (string) - First name
  - **lastName** (string) - Last name
  - **email** (string) - Email address
  - **status** (string) - Status (e.g., "active")
  - **joinedAt** (string) - Join date (ISO 8601)
  - **createdAt** (string) - Creation date (ISO 8601)
  - **updatedAt** (string) - Last update date (ISO 8601)

#### Response Example
```
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "status": "active",
    "joinedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

### Error Responses
- **401** - Unauthorized
- **404** - Not Found
- **500** - Internal Server Error
```

--------------------------------

### Add RefRef Attribution Script and Widget

Source: https://refref.ai/docs

Embed the attribution script and widget to track referral codes and enable sharing. The widget initialization requires your product ID and a JWT token from your backend.

```html
<!-- Attribution Script -->
<script src="https://assets.refref.app/attribution.js" defer></script>
 
<!-- Widget -->
<script src="https://assets.refref.ai/widget.js"></script>
<script>
  window.RefRef.init({
    productId: 'your-product-id',
    token: 'jwt-token-from-your-backend'
  });
</script>
```

--------------------------------

### Initialize & Trigger Widget

Source: https://refref.ai/docs/platform/widget

Basic initialization of the RefRef widget with a JWT token fetched from your backend. The widget displays a floating button once initialized.

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.ai/widget.js"></script>
</head>
<body>
  <!-- Your content -->
 
  <script>
    // Initialize widget with JWT token from your backend
    fetch('/api/refref-token')
      .then(res => res.json())
      .then(data => {
        window.RefRef.init({
          productId: 'your-product-id',
          token: data.token
        });
      });
  </script>
</body>
</html>
```

--------------------------------

### Add the attribution script tag (CDN)

Source: https://refref.ai/docs/platform/installation/attribution-script

Add this script tag to your website's <head> or before the closing </body> tag. The defer attribute ensures the script runs after the page loads without blocking rendering.

```html
<script src="https://assets.refref.app/attribution.js" defer></script>
```

--------------------------------

### Control Widget Layout

Source: https://refref.ai/docs/platform/installation/widget

Set the widget's layout properties such as width, max-width, and margin using CSS.

```css
refref-widget {
  display: block;
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
}
```
Tokens:
Raw