API Documentation

Integrate Build Emotion with your tools and workflows. Create, read, update, and delete marketing activities programmatically.

Quick Start

1. Get Your API Key

Go to your Settings page and generate an API key.

2. Get Your Project ID

The project ID is the UUID found in your project's URL. When you open a project in the dashboard, the URL will look like:

https://buildemotion.com/user/projects/your-project-id-here

Copy the UUID from the URL (the part after /projects/) and use it in all API requests.

3. Authenticate Requests

Include your API key in the Authorization header (recommended) or X-API-Key header:

Authorization: Bearer sk_live_your_api_key_here

— or —

X-API-Key: sk_live_your_api_key_here

4. Make Your First Request

Create a marketing activity:

curl -X POST https://buildemotion.com/api/projects/{project_id}/marketing-activities/ \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature launch",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
  }'

Authentication

All API requests require authentication using an API key. You can authenticate using any of the following methods:

Method 1: Authorization Header (Recommended)

Authorization: Bearer sk_live_your_api_key_here

Method 2: X-API-Key Header

X-API-Key: sk_live_your_api_key_here

Method 3: Query Parameter (Fallback)

?api_key=sk_live_your_api_key_here

Get Your API Key

Visit your Settings page to generate an API key. Keep it secure and never share it publicly.

Base URL

https://buildemotion.com

All API endpoints are relative to this base URL.

Endpoints

GET/api/projects/{project_id}/marketing-activities/

List all marketing activities for a project. Supports optional date filtering.

Query Parameters:

from_date (optional) - Filter activities from this date (YYYY-MM-DD)
to_date (optional) - Filter activities until this date (YYYY-MM-DD)

Example Request:

GET https://buildemotion.com/api/projects/abc123/marketing-activities/?from_date=2026-01-01&to_date=2026-01-31
Authorization: Bearer sk_live_your_api_key

Example Response:

{
  "marketingActivities": [
    {
      "id": "activity_123",
      "projectId": "abc123",
      "category": "social",
      "subcategory": "Twitter/X",
      "description": "Posted about new feature",
      "date": "2026-01-15",
      "time": "14:30",
      "link": "https://twitter.com/yourpost",
      "created": "2026-01-15T14:30:00Z",
      "modified": "2026-01-15T14:30:00Z"
    }
  ]
}

POST/api/projects/{project_id}/marketing-activities/

Create a new marketing activity.

Request Body (Required Fields):

category (required) - One of: email, directory, social, seo, influencers, paid, offline, other
subcategory (required) - Subcategory string (see categories below)
description (required) - Description of the marketing activity
date (required) - Date in YYYY-MM-DD format

Request Body (Optional Fields):

time (optional) - Time in HH:MM format (24-hour)
link (optional) - URL related to the activity

Example Request:

POST https://buildemotion.com/api/projects/abc123/marketing-activities/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "category": "social",
  "subcategory": "Twitter/X",
  "description": "Posted about new feature launch",
  "date": "2026-01-15",
  "time": "14:30",
  "link": "https://twitter.com/yourpost"
}

Example Response (201 Created):

{
  "marketingActivity": {
    "id": "activity_123",
    "projectId": "abc123",
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature launch",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost",
    "created": "2026-01-15T14:30:00Z",
    "modified": "2026-01-15T14:30:00Z"
  }
}

GET/api/projects/{project_id}/marketing-activities/{activity_id}/

Get a specific marketing activity by ID.

Example Response:

{
  "marketingActivity": {
    "id": "activity_123",
    "projectId": "abc123",
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost",
    "created": "2026-01-15T14:30:00Z",
    "modified": "2026-01-15T14:30:00Z"
  }
}

PATCHPUT/api/projects/{project_id}/marketing-activities/{activity_id}/

Update a marketing activity. PATCH supports partial updates, PUT requires all fields.

Example Request:

PATCH https://buildemotion.com/api/projects/abc123/marketing-activities/activity_123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "description": "Updated description",
  "link": "https://twitter.com/updatedpost"
}

DELETE/api/projects/{project_id}/marketing-activities/{activity_id}/

Delete a marketing activity.

Example Response:

{
  "status": "deleted"
}

Categories & Subcategories

Use these category and subcategory values when creating marketing activities:

📧Emailemail

Subcategories:

Cold EmailNewsletterEmail CampaignFollow-upOther Email

📁Directoriesdirectory

Subcategories:

BetaListProduct HuntIndie HackersHacker NewsRedditOther Directory

📱Social Postsocial

Subcategories:

Twitter/XRedditLinkedInFacebookInstagramTikTokYouTubeOther Social

🔍SEOseo

Subcategories:

Blog ArticlepSEOGuest PostBacklinksContent UpdateComparison PageUse-case PageFAQ PageFree Tool PageFree Course PageOther SEO

⭐Influencersinfluencers

Subcategories:

Micro-influencerMacro-influencerCelebrityIndustry ExpertBrand AmbassadorSponsored PostProduct ReviewUnboxingPodcastOther Influencer

💰Paid Adspaid

Subcategories:

Google AdsFacebook AdsInstagram AdsLinkedIn AdsTwitter/X AdsYouTube AdsTikTok AdsDisplay AdsSearch AdsRetargetingOther Paid AdsSponsorshipOther Paid

🌍Offlineoffline

Subcategories:

BillboardsPrint AdsTrade ShowsNetworking EventsDirect MailOther Offline

🤝Partnershippartnership

Subcategories:

Affiliate ProgramPartner ProgramReseller ProgramCo-marketingOther Partnership

✨Otherother

Subcategories:

PartnershipEventPRInternal Cross PromotionOther

Error Handling

The API uses standard HTTP status codes. Error responses include a message in the response body:

401 Unauthorized

{
  "error": "Authentication required. Provide valid API key in Authorization header (Bearer sk_live_...) or user session."
}

400 Bad Request

{
  "error": "Category is required"
}

404 Not Found

{
  "error": "Project not found"
}

Code Examples

JavaScript / Node.js

const createMarketingActivity = async (projectId, activityData) => {
  const response = await fetch(
    `https://buildemotion.com/api/projects/${projectId}/marketing-activities/`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        category: 'social',
        subcategory: 'Twitter/X',
        description: 'Posted about new feature',
        date: '2026-01-15',
        time: '14:30',
        link: 'https://twitter.com/yourpost'
      })
    }
  );
  
  return await response.json();
};

Python

import requests

API_KEY = "sk_live_your_api_key"
BASE_URL = "https://buildemotion.com"

def create_marketing_activity(project_id, activity_data):
    url = f"{BASE_URL}/api/projects/{project_id}/marketing-activities/"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, json=activity_data, headers=headers)
    return response.json()

# Example usage
activity = {
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
}

result = create_marketing_activity("your-project-id", activity)

cURL

curl -X POST https://buildemotion.com/api/projects/abc123/marketing-activities/ \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
  }'

Best Practices

Keep Your API Key Secure

Never commit your API key to version control or expose it in client-side code.

Use Date Filtering

When listing activities, use from_date and to_date parameters to reduce response size and improve performance.

Handle Errors Gracefully

Always check response status codes and handle errors appropriately in your application.

Validate Data Before Sending

Ensure dates are in YYYY-MM-DD format and times are in HH:MM format (24-hour) before making requests.

Ready to Get Started?

Get your API key and start integrating Build Emotion into your workflow.

Get API Key Go to Dashboard

Build Emotion

not featurefeel the difference

API Documentation

Integrate Build Emotion with your tools and workflows. Create, read, update, and delete marketing activities programmatically.

Quick Start

1. Get Your API Key

Go to your Settings page and generate an API key.

2. Get Your Project ID

The project ID is the UUID found in your project's URL. When you open a project in the dashboard, the URL will look like:

https://buildemotion.com/user/projects/your-project-id-here

Copy the UUID from the URL (the part after /projects/) and use it in all API requests.

3. Authenticate Requests

Include your API key in the Authorization header (recommended) or X-API-Key header:

Authorization: Bearer sk_live_your_api_key_here

— or —

X-API-Key: sk_live_your_api_key_here

4. Make Your First Request

Create a marketing activity:

curl -X POST https://buildemotion.com/api/projects/{project_id}/marketing-activities/ \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature launch",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
  }'

Authentication

All API requests require authentication using an API key. You can authenticate using any of the following methods:

Method 1: Authorization Header (Recommended)

Authorization: Bearer sk_live_your_api_key_here

Method 2: X-API-Key Header

X-API-Key: sk_live_your_api_key_here

Method 3: Query Parameter (Fallback)

?api_key=sk_live_your_api_key_here

Get Your API Key

Visit your Settings page to generate an API key. Keep it secure and never share it publicly.

Base URL

https://buildemotion.com

All API endpoints are relative to this base URL.

Endpoints

GET/api/projects/{project_id}/marketing-activities/

List all marketing activities for a project. Supports optional date filtering.

Query Parameters:

from_date (optional) - Filter activities from this date (YYYY-MM-DD)
to_date (optional) - Filter activities until this date (YYYY-MM-DD)

Example Request:

GET https://buildemotion.com/api/projects/abc123/marketing-activities/?from_date=2026-01-01&to_date=2026-01-31
Authorization: Bearer sk_live_your_api_key

Example Response:

{
  "marketingActivities": [
    {
      "id": "activity_123",
      "projectId": "abc123",
      "category": "social",
      "subcategory": "Twitter/X",
      "description": "Posted about new feature",
      "date": "2026-01-15",
      "time": "14:30",
      "link": "https://twitter.com/yourpost",
      "created": "2026-01-15T14:30:00Z",
      "modified": "2026-01-15T14:30:00Z"
    }
  ]
}

POST/api/projects/{project_id}/marketing-activities/

Create a new marketing activity.

Request Body (Required Fields):

category (required) - One of: email, directory, social, seo, influencers, paid, offline, other
subcategory (required) - Subcategory string (see categories below)
description (required) - Description of the marketing activity
date (required) - Date in YYYY-MM-DD format

Request Body (Optional Fields):

time (optional) - Time in HH:MM format (24-hour)
link (optional) - URL related to the activity

Example Request:

POST https://buildemotion.com/api/projects/abc123/marketing-activities/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "category": "social",
  "subcategory": "Twitter/X",
  "description": "Posted about new feature launch",
  "date": "2026-01-15",
  "time": "14:30",
  "link": "https://twitter.com/yourpost"
}

Example Response (201 Created):

{
  "marketingActivity": {
    "id": "activity_123",
    "projectId": "abc123",
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature launch",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost",
    "created": "2026-01-15T14:30:00Z",
    "modified": "2026-01-15T14:30:00Z"
  }
}

GET/api/projects/{project_id}/marketing-activities/{activity_id}/

Get a specific marketing activity by ID.

Example Response:

{
  "marketingActivity": {
    "id": "activity_123",
    "projectId": "abc123",
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost",
    "created": "2026-01-15T14:30:00Z",
    "modified": "2026-01-15T14:30:00Z"
  }
}

PATCHPUT/api/projects/{project_id}/marketing-activities/{activity_id}/

Update a marketing activity. PATCH supports partial updates, PUT requires all fields.

Example Request:

PATCH https://buildemotion.com/api/projects/abc123/marketing-activities/activity_123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "description": "Updated description",
  "link": "https://twitter.com/updatedpost"
}

DELETE/api/projects/{project_id}/marketing-activities/{activity_id}/

Delete a marketing activity.

Example Response:

{
  "status": "deleted"
}

Categories & Subcategories

Use these category and subcategory values when creating marketing activities:

📧Emailemail

Subcategories:

Cold EmailNewsletterEmail CampaignFollow-upOther Email

📁Directoriesdirectory

Subcategories:

BetaListProduct HuntIndie HackersHacker NewsRedditOther Directory

📱Social Postsocial

Subcategories:

Twitter/XRedditLinkedInFacebookInstagramTikTokYouTubeOther Social

🔍SEOseo

Subcategories:

Blog ArticlepSEOGuest PostBacklinksContent UpdateComparison PageUse-case PageFAQ PageFree Tool PageFree Course PageOther SEO

⭐Influencersinfluencers

Subcategories:

Micro-influencerMacro-influencerCelebrityIndustry ExpertBrand AmbassadorSponsored PostProduct ReviewUnboxingPodcastOther Influencer

💰Paid Adspaid

Subcategories:

Google AdsFacebook AdsInstagram AdsLinkedIn AdsTwitter/X AdsYouTube AdsTikTok AdsDisplay AdsSearch AdsRetargetingOther Paid AdsSponsorshipOther Paid

🌍Offlineoffline

Subcategories:

BillboardsPrint AdsTrade ShowsNetworking EventsDirect MailOther Offline

🤝Partnershippartnership

Subcategories:

Affiliate ProgramPartner ProgramReseller ProgramCo-marketingOther Partnership

✨Otherother

Subcategories:

PartnershipEventPRInternal Cross PromotionOther

Error Handling

The API uses standard HTTP status codes. Error responses include a message in the response body:

401 Unauthorized

{
  "error": "Authentication required. Provide valid API key in Authorization header (Bearer sk_live_...) or user session."
}

400 Bad Request

{
  "error": "Category is required"
}

404 Not Found

{
  "error": "Project not found"
}

Code Examples

JavaScript / Node.js

const createMarketingActivity = async (projectId, activityData) => {
  const response = await fetch(
    `https://buildemotion.com/api/projects/${projectId}/marketing-activities/`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        category: 'social',
        subcategory: 'Twitter/X',
        description: 'Posted about new feature',
        date: '2026-01-15',
        time: '14:30',
        link: 'https://twitter.com/yourpost'
      })
    }
  );
  
  return await response.json();
};

Python

import requests

API_KEY = "sk_live_your_api_key"
BASE_URL = "https://buildemotion.com"

def create_marketing_activity(project_id, activity_data):
    url = f"{BASE_URL}/api/projects/{project_id}/marketing-activities/"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, json=activity_data, headers=headers)
    return response.json()

# Example usage
activity = {
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
}

result = create_marketing_activity("your-project-id", activity)

cURL

curl -X POST https://buildemotion.com/api/projects/abc123/marketing-activities/ \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "social",
    "subcategory": "Twitter/X",
    "description": "Posted about new feature",
    "date": "2026-01-15",
    "time": "14:30",
    "link": "https://twitter.com/yourpost"
  }'

Best Practices

Keep Your API Key Secure

Never commit your API key to version control or expose it in client-side code.

Use Date Filtering

When listing activities, use from_date and to_date parameters to reduce response size and improve performance.

Handle Errors Gracefully

Always check response status codes and handle errors appropriately in your application.

Validate Data Before Sending

Ensure dates are in YYYY-MM-DD format and times are in HH:MM format (24-hour) before making requests.

Ready to Get Started?

Get your API key and start integrating Build Emotion into your workflow.

Get API Key Go to Dashboard