Getting Started with Cherry.tv Account API

The Cherry.tv Account API allows you to programmatically register new users on the Cherry.tv platform. This is particularly useful for affiliates and partners who want to streamline the user onboarding process.

Base URL

All API requests should be made to:

https://api.cherry.tv

Authentication

The Account API uses API Key authentication passed as a header. You'll need to include your API key in every request:

X-API-Key: YOUR_API_KEY

Example Request Headers

curl -X POST "https://api.cherry.tv/account/v1/registration" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

User Registration Endpoint

POST `/account/v1/registration`

Request Body

The registration endpoint requires the following parameters:

Parameter	Type	Required	Description
username	string	Yes	Unique username for the new account
password	string	Yes	Password for the new account
email	string	Yes	Email address for the new account
everflow	string	Yes	Everflow tracking parameter
lp	string	Yes	Landing page identifier
ip	string	Yes	User's IP address
utmParams	object	Yes	UTM tracking parameters object

Request Example

{
  "username": "newuser123",
  "password": "securePassword123!",
  "email": "user@example.com",
  "everflow": "ef_12345",
  "lp": "landing_page_1",
  "ip": "192.168.1.100",
  "utmParams": {
    "utm_source": "affiliate",
    "utm_medium": "banner",
    "utm_campaign": "summer2024",
    "utm_term": "signup",
    "utm_content": "header_cta"
  }
}

Response Format

The API returns a JSON response with the following structure:

interface RegisterUserRequestResponse {
  success: boolean;    // Whether the registration was successful
  loginUrl: string;    // URL to redirect the user for login
}

Success Response Example

{
  "success": true,
  "loginUrl": "https://cherry.tv/login?token=abc123xyz"
}

Error Response Example

{
  "success": false,
  "error": "Username already exists",
  "statusCode": 400
}

Code Examples

JavaScript/Node.js

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://api.cherry.tv';

async function registerUser(userData) {
  try {
    const response = await fetch(`${BASE_URL}/account/v1/registration`, {
      method: 'POST',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(userData)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Registration failed:', error);
    throw error;
  }
}

// Usage example
async function example() {
  const newUser = {
    username: 'newuser123',
    password: 'securePassword123!',
    email: 'user@example.com',
    everflow: 'ef_12345',
    lp: 'landing_page_1',
    ip: '192.168.1.100',
    utmParams: {
      utm_source: 'affiliate',
      utm_medium: 'banner',
      utm_campaign: 'summer2024'
    }
  };

  try {
    const result = await registerUser(newUser);
    
    if (result.success) {
      console.log('Registration successful!');
      console.log('Login URL:', result.loginUrl);
      // Redirect user to login URL
      window.location.href = result.loginUrl;
    }
  } catch (error) {
    console.error('Registration error:', error);
  }
}

Python

import requests
import json

class CherryTVAccountAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.cherry.tv"
        self.headers = {
            'X-API-Key': api_key,
            'Content-Type': 'application/json'
        }
    
    def register_user(self, user_data: dict) -> dict:
        """Register a new user account."""
        try:
            response = requests.post(
                f"{self.base_url}/account/v1/registration",
                headers=self.headers,
                json=user_data
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"Registration failed: {e}")
            raise

# Usage example
def main():
    api = CherryTVAccountAPI("your-api-key-here")
    
    user_data = {
        "username": "newuser123",
        "password": "securePassword123!",
        "email": "user@example.com",
        "everflow": "ef_12345",
        "lp": "landing_page_1",
        "ip": "192.168.1.100",
        "utmParams": {
            "utm_source": "affiliate",
            "utm_medium": "banner",
            "utm_campaign": "summer2024"
        }
    }
    
    try:
        result = api.register_user(user_data)
        
        if result.get('success'):
            print("Registration successful!")
            print(f"Login URL: {result.get('loginUrl')}")
        else:
            print("Registration failed")
            
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

PHP

<?php

class CherryTVAccountAPI {
    private $apiKey;
    private $baseUrl = 'https://api.cherry.tv';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function registerUser($userData) {
        $url = $this->baseUrl . '/account/v1/registration';
        
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($userData));
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            throw new Exception("Registration failed with HTTP code: $httpCode");
        }
        
        return json_decode($response, true);
    }
}

// Usage example
try {
    $api = new CherryTVAccountAPI('your-api-key-here');
    
    $userData = [
        'username' => 'newuser123',
        'password' => 'securePassword123!',
        'email' => 'user@example.com',
        'everflow' => 'ef_12345',
        'lp' => 'landing_page_1',
        'ip' => '192.168.1.100',
        'utmParams' => [
            'utm_source' => 'affiliate',
            'utm_medium' => 'banner',
            'utm_campaign' => 'summer2024'
        ]
    ];
    
    $result = $api->registerUser($userData);
    
    if ($result['success']) {
        echo "Registration successful!\n";
        echo "Login URL: " . $result['loginUrl'] . "\n";
    } else {
        echo "Registration failed\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

cURL Example

curl -X POST "https://api.cherry.tv/account/v1/registration" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser123",
    "password": "securePassword123!",
    "email": "user@example.com",
    "everflow": "ef_12345",
    "lp": "landing_page_1",
    "ip": "192.168.1.100",
    "utmParams": {
      "utm_source": "affiliate",
      "utm_medium": "banner",
      "utm_campaign": "summer2024"
    }
  }'

UTM Parameters

The utmParams object should contain standard UTM tracking parameters for analytics and attribution:

Parameter	Description	Example
utm_source	Traffic source	"affiliate"
utm_medium	Marketing medium	"banner"
utm_campaign	Campaign name	"summer2024"
utm_term	Paid search keywords	"signup"
utm_content	Content that was clicked	"header_cta"

Error Handling

The API returns standard HTTP status codes. Common error scenarios include:

400 Bad Request

Missing required fields
Invalid email format
Username already exists
Password doesn't meet requirements

401 Unauthorized

Invalid or missing API key

500 Internal Server Error

Server-side processing error

Example Error Response

{
  "success": false,
  "error": "Username already exists",
  "statusCode": 400,
  "details": {
    "field": "username",
    "message": "This username is already taken"
  }
}

Best Practices

Validate Input: Always validate user input before sending to the API
Handle Errors: Implement proper error handling for all possible scenarios
Secure Passwords: Enforce strong password requirements
Track Attribution: Use proper UTM parameters for tracking and analytics
Rate Limiting: Implement rate limiting to prevent abuse
HTTPS Only: Always use HTTPS for API requests
API Key Security: Never expose API keys in client-side code

Integration Flow

Collect User Data: Gather registration information from your form
Validate Data: Ensure all required fields are present and valid
Call API: Send registration request to Cherry.tv
Handle Response: Process success/error responses appropriately
Redirect User: On success, redirect to the provided login URL

Next Steps

Registration API Reference - Complete API documentation
Affiliates API - Access model data and affiliate links
Embedding Guide - Embed Cherry.tv content

Support

If you need help with the Account API or have questions about user registration, please contact your account manager or reach out to our developer support team.

Getting Started with Account API