Logo
Dashboard

API Documentation

API Endpoints

Overview

Welcome to the GrabPenny API documentation. Our API allows you to programmatically create and manage social media marketing campaigns.

Base URL

https://grabpenny.com/api/v1/client/

Response Format

All API responses are returned in JSON format.

Quick Start

Get started quickly with our Postman collection:

Download Postman Collection

Import this collection into Postman to test all API endpoints with pre-configured requests.

Authentication

All API requests require authentication using an API key. You can generate API keys from your API Keys page.

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://grabpenny.com/api/v1/client/auth/me/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Validate API Key

GET /api/v1/client/auth/me/

Validates your API key and returns account information.

Request

No request body required.

Response

{
  "account": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe",
    "country": {
      "code": "US",
      "name": "United States"
    },
    "balance": {
      "amount": 1000.0,
      "currency": "$",
      "formatted": "$1000.00"
    },
    "created_at": "2024-01-01T00:00:00Z"
  },
  "api_key": {
    "name": "My API Key",
    "created_at": "2024-01-01T00:00:00Z",
    "last_used": "2024-01-15T10:30:00Z"
  }
}

List Available Tasks

GET /api/v1/client/tasks/

Returns a list of available task types for creating campaigns.

Request

No request body required.

Response

{
  "tasks": [
    {
      "id": 1,
      "code": "INSTAGRAM_FOLLOW",
      "name": "Instagram Follow",
      "description": "Users will follow the Instagram account",
      "platform": "Instagram",
      "cost_per_engagement": 0.5,
      "currency": "$",
      "min_engagements": 10,
      "max_engagements": 10000,
      "is_active": true
    },
    {
      "id": 2,
      "code": "YOUTUBE_SUBSCRIBE",
      "name": "YouTube Subscribe",
      "description": "Users will subscribe to the YouTube channel",
      "platform": "Youtube",
      "cost_per_engagement": 0.75,
      "currency": "$",
      "min_engagements": 10,
      "max_engagements": 10000,
      "is_active": true
    }
  ]
}

Create Campaign

POST /api/v1/client/campaigns/create/

Creates a new campaign with the specified parameters.

Request Body

Parameter Type Required Description
task_type_id integer Yes ID of the task type (from /tasks/ endpoint)
name string Yes Campaign name
link string Yes URL to the social media profile/content
required_executions integer Yes Number of engagements required (min: 10)
max_per_day integer No Maximum engagements per day (0 = unlimited)
gender integer No Target gender: -1 (All), 0 (Male), 1 (Female)
misc_data object No Additional campaign data

Example Request

curl -X POST https://grabpenny.com/api/v1/client/campaigns/create/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type_id": 1,
    "name": "My Instagram Campaign",
    "link": "https://instagram.com/myprofile",
    "required_executions": 100,
    "max_per_day": 20,
    "gender": -1
  }'

Response

{
  "campaign": {
    "id": 456,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "My Instagram Campaign",
    "link": "https://instagram.com/myprofile",
    "task_type": {
      "id": 1,
      "code": "INSTAGRAM_FOLLOW",
      "name": "Instagram Follow"
    },
    "required_executions": 100,
    "remaining_executions": 100,
    "status": "Running",
    "total_cost": 50.0,
    "currency": "$",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "balance": {
    "amount": 950.0,
    "formatted": "$950.00"
  }
}

Error Responses

Status Code Error Description
400 Bad Request Missing or invalid parameters
400 Insufficient Balance Account doesn't have enough balance
401 Unauthorized Invalid or missing API key