X-API-Key header or as an api_key query parameter.'
security:
-
default: []
paths:
/api/v1/account/usage:
get:
summary: 'Get account usage and limits'
operationId: getAccountUsageAndLimits
description: 'Retrieve current usage statistics and plan limits for EvenLeads features.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
user:
id: 1
name: 'John Doe'
email: john@example.com
plan:
name: Professional
interval: monthly
limits:
campaigns:
current: 3
max: 5
percentage: 60
leads_storage:
current: 1250
max: 5000
percentage: 25
leads_per_sync:
max: 100
ai_replies_per_month:
current: 45
max: 500
percentage: 9
resets_at: '2025-02-01T00:00:00.000000Z'
manual_syncs_per_month:
current: 12
max: 100
percentage: 12
resets_at: '2025-02-01T00:00:00.000000Z'
keywords_per_campaign:
max: 20
automated_sync_interval_minutes:
value: 60
properties:
success:
type: boolean
example: true
data:
type: object
properties:
user:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'John Doe'
email:
type: string
example: john@example.com
plan:
type: object
properties:
name:
type: string
example: Professional
interval:
type: string
example: monthly
limits:
type: object
properties:
campaigns:
type: object
properties:
current:
type: integer
example: 3
max:
type: integer
example: 5
percentage:
type: integer
example: 60
leads_storage:
type: object
properties:
current:
type: integer
example: 1250
max:
type: integer
example: 5000
percentage:
type: integer
example: 25
leads_per_sync:
type: object
properties:
max:
type: integer
example: 100
ai_replies_per_month:
type: object
properties:
current:
type: integer
example: 45
max:
type: integer
example: 500
percentage:
type: integer
example: 9
resets_at:
type: string
example: '2025-02-01T00:00:00.000000Z'
manual_syncs_per_month:
type: object
properties:
current:
type: integer
example: 12
max:
type: integer
example: 100
percentage:
type: integer
example: 12
resets_at:
type: string
example: '2025-02-01T00:00:00.000000Z'
keywords_per_campaign:
type: object
properties:
max:
type: integer
example: 20
automated_sync_interval_minutes:
type: object
properties:
value:
type: integer
example: 60
tags:
- Account
/api/v1/auth/validate:
get:
summary: 'Validate API Key'
operationId: validateAPIKey
description: 'Validates if an API key is valid and returns associated user information.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'API key is valid'
data:
user:
id: 1
name: 'John Doe'
email: john@example.com
api_key:
name: 'My API Key'
created_at: '2025-01-01T00:00:00.000000Z'
last_used_at: '2025-01-15T12:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'API key is valid'
data:
type: object
properties:
user:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'John Doe'
email:
type: string
example: john@example.com
api_key:
type: object
properties:
name:
type: string
example: 'My API Key'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
last_used_at:
type: string
example: '2025-01-15T12:30:00.000000Z'
401:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid API key.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid API key.'
tags:
- Authentication
/api/v1/campaigns:
get:
summary: 'List all campaigns'
operationId: listAllCampaigns
description: 'Get a paginated list of all campaigns for the authenticated user.'
parameters:
-
in: query
name: page
description: 'Page number for pagination.'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination.'
example: 1
nullable: false
-
in: query
name: per_page
description: 'Number of items per page (max 100).'
example: 15
required: false
schema:
type: integer
description: 'Number of items per page (max 100).'
example: 15
nullable: false
-
in: query
name: status
description: 'Filter by status (active, paused, completed).'
example: active
required: false
schema:
type: string
description: 'Filter by status (active, paused, completed).'
example: active
nullable: false
-
in: query
name: platform
description: 'Filter by platform (reddit, facebook, etc).'
example: reddit
required: false
schema:
type: string
description: 'Filter by platform (reddit, facebook, etc).'
example: reddit
nullable: false
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
campaigns:
-
id: 1
name: 'Web Development Services'
offering: 'Custom web development'
website_url: 'https://example.com'
platforms:
- reddit
- facebook
status: active
keywords:
- 'web development'
- website
strong_matches_count: 15
partial_matches_count: 8
new_leads_count: 5
last_sync_at: '2025-01-15T10:30:00.000000Z'
next_sync_at: '2025-01-15T11:30:00.000000Z'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
pagination:
current_page: 1
per_page: 15
total: 25
last_page: 2
properties:
success:
type: boolean
example: true
data:
type: object
properties:
campaigns:
type: array
example:
-
id: 1
name: 'Web Development Services'
offering: 'Custom web development'
website_url: 'https://example.com'
platforms:
- reddit
- facebook
status: active
keywords:
- 'web development'
- website
strong_matches_count: 15
partial_matches_count: 8
new_leads_count: 5
last_sync_at: '2025-01-15T10:30:00.000000Z'
next_sync_at: '2025-01-15T11:30:00.000000Z'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Web Development Services'
offering:
type: string
example: 'Custom web development'
website_url:
type: string
example: 'https://example.com'
platforms:
type: array
example:
- reddit
- facebook
items:
type: string
status:
type: string
example: active
keywords:
type: array
example:
- 'web development'
- website
items:
type: string
strong_matches_count:
type: integer
example: 15
partial_matches_count:
type: integer
example: 8
new_leads_count:
type: integer
example: 5
last_sync_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
next_sync_at:
type: string
example: '2025-01-15T11:30:00.000000Z'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
pagination:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 25
last_page:
type: integer
example: 2
tags:
- Campaigns
post:
summary: 'Create a new campaign'
operationId: createANewCampaign
description: 'Create a new campaign. You can only create campaigns for social platforms your account is connected with.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
201:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Campaign created successfully'
data:
id: 1
name: 'Web Development Services'
status: active
created_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Campaign created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Web Development Services'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
platforms:
- 'You are not connected to facebook. Please connect your account first.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
platforms:
type: array
example:
- 'You are not connected to facebook. Please connect your account first.'
items:
type: string
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'The campaign name.'
example: 'Web Development Services'
nullable: false
offering:
type: string
description: "Description of what you're offering."
example: 'Custom web development and design services'
nullable: false
website_url:
type: string
description: 'The website URL.'
example: 'https://example.com'
nullable: true
portfolio_path:
type: string
description: 'Portfolio path.'
example: /portfolio
nullable: true
platforms:
type: array
description: 'Array of platforms (must be connected).'
example:
- reddit
- facebook
items:
type: string
facebook_groups:
type: array
description: 'Facebook groups to monitor (required if facebook in platforms).'
example:
- group1
- group2
items:
type: string
keywords:
type: array
description: 'Keywords to search for.'
example:
- 'web development'
- website
items:
type: string
negative_keywords:
type: array
description: ''
example:
- architecto
items:
type: string
nullable: true
include_keywords:
type: array
description: 'Additional filter keywords.'
example:
- need
- 'looking for'
items:
type: string
nullable: true
ai_settings:
type: object
description: 'AI generation settings.'
example:
tone: professional
length: medium
nullable: true
properties: { }
include_call_to_action:
type: boolean
description: 'Include call to action.'
example: true
nullable: true
status:
type: string
description: 'Campaign status (active, paused).'
example: active
nullable: true
required:
- name
- offering
- platforms
- keywords
'/api/v1/campaigns/{id}':
get:
summary: 'Get a single campaign'
operationId: getASingleCampaign
description: 'Retrieve detailed information about a specific campaign including all settings, matches, and sync history.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
id: 1
name: 'Web Development Services'
offering: 'Custom web development'
website_url: 'https://example.com'
portfolio_path: /portfolio
platforms:
- reddit
- facebook
facebook_groups:
- group1
- group2
keywords:
- 'web development'
- website
include_keywords:
- need
- 'looking for'
ai_settings:
tone: professional
length: medium
include_call_to_action: true
status: active
strong_matches_count: 15
partial_matches_count: 8
new_leads_count: 5
last_sync_at: '2025-01-15T10:30:00.000000Z'
next_sync_at: '2025-01-15T11:30:00.000000Z'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Web Development Services'
offering:
type: string
example: 'Custom web development'
website_url:
type: string
example: 'https://example.com'
portfolio_path:
type: string
example: /portfolio
platforms:
type: array
example:
- reddit
- facebook
items:
type: string
facebook_groups:
type: array
example:
- group1
- group2
items:
type: string
keywords:
type: array
example:
- 'web development'
- website
items:
type: string
include_keywords:
type: array
example:
- need
- 'looking for'
items:
type: string
ai_settings:
type: object
properties:
tone:
type: string
example: professional
length:
type: string
example: medium
include_call_to_action:
type: boolean
example: true
status:
type: string
example: active
strong_matches_count:
type: integer
example: 15
partial_matches_count:
type: integer
example: 8
new_leads_count:
type: integer
example: 5
last_sync_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
next_sync_at:
type: string
example: '2025-01-15T11:30:00.000000Z'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
tags:
- Campaigns
put:
summary: 'Update a campaign'
operationId: updateACampaign
description: 'Update an existing campaign. Same validation rules as creation apply.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Campaign updated successfully'
data:
id: 1
name: 'Updated Campaign Name'
updated_at: '2025-01-15T12:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Campaign updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Updated Campaign Name'
updated_at:
type: string
example: '2025-01-15T12:30:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
tags:
- Campaigns
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'The campaign name.'
example: 'Updated Campaign Name'
nullable: false
offering:
type: string
description: "Description of what you're offering."
example: 'Updated offering description'
nullable: false
website_url:
type: string
description: 'The website URL.'
example: 'https://example.com'
nullable: true
portfolio_path:
type: string
description: 'Portfolio path.'
example: /portfolio
nullable: true
platforms:
type: array
description: 'Array of platforms (must be connected).'
example:
- reddit
items:
type: string
facebook_groups:
type: array
description: 'Facebook groups to monitor.'
example:
- group1
items:
type: string
keywords:
type: array
description: 'Keywords to search for.'
example:
- 'web dev'
- website
items:
type: string
negative_keywords:
type: array
description: ''
example:
- architecto
items:
type: string
nullable: true
include_keywords:
type: array
description: 'Additional filter keywords.'
example:
- need
items:
type: string
nullable: true
ai_settings:
type: object
description: 'AI generation settings.'
example:
tone: casual
nullable: true
properties: { }
include_call_to_action:
type: boolean
description: 'Include call to action.'
example: false
nullable: true
status:
type: string
description: 'Campaign status.'
example: paused
nullable: true
delete:
summary: 'Delete a campaign'
operationId: deleteACampaign
description: 'Soft delete a campaign and all its associated data.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Campaign deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Campaign deleted successfully'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
tags:
- Campaigns
parameters:
-
in: path
name: id
description: 'The campaign ID.'
example: 1
required: true
schema:
type: integer
/api/v1/leads:
get:
summary: 'List all leads'
operationId: listAllLeads
description: 'Get a paginated list of all leads with comprehensive filtering options.'
parameters:
-
in: query
name: page
description: 'Page number for pagination.'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination.'
example: 1
nullable: false
-
in: query
name: per_page
description: 'Number of items per page (max 100).'
example: 15
required: false
schema:
type: integer
description: 'Number of items per page (max 100).'
example: 15
nullable: false
-
in: query
name: campaign_id
description: 'Filter by campaign ID.'
example: 1
required: false
schema:
type: integer
description: 'Filter by campaign ID.'
example: 1
nullable: false
-
in: query
name: status
description: 'Filter by status (new, contacted, closed).'
example: new
required: false
schema:
type: string
description: 'Filter by status (new, contacted, closed).'
example: new
nullable: false
-
in: query
name: match_type
description: 'Filter by match type (strong, partial).'
example: strong
required: false
schema:
type: string
description: 'Filter by match type (strong, partial).'
example: strong
nullable: false
-
in: query
name: platform
description: 'Filter by platform (reddit, facebook, etc).'
example: reddit
required: false
schema:
type: string
description: 'Filter by platform (reddit, facebook, etc).'
example: reddit
nullable: false
-
in: query
name: min_confidence
description: 'Minimum confidence score (0-10).'
example: 7
required: false
schema:
type: integer
description: 'Minimum confidence score (0-10).'
example: 7
nullable: false
-
in: query
name: max_confidence
description: 'Maximum confidence score (0-10).'
example: 10
required: false
schema:
type: integer
description: 'Maximum confidence score (0-10).'
example: 10
nullable: false
-
in: query
name: search
description: 'Search in title and description.'
example: website
required: false
schema:
type: string
description: 'Search in title and description.'
example: website
nullable: false
-
in: query
name: sort_by
description: 'Sort by field (created_at, confidence_score, synced_at).'
example: created_at
required: false
schema:
type: string
description: 'Sort by field (created_at, confidence_score, synced_at).'
example: created_at
nullable: false
-
in: query
name: sort_order
description: 'Sort order (asc, desc).'
example: desc
required: false
schema:
type: string
description: 'Sort order (asc, desc).'
example: desc
nullable: false
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
leads:
-
id: 1
campaign_id: 1
campaign_name: 'Web Development Services'
platform: reddit
platform_id: abc123
title: 'Looking for web developer'
description: 'Need someone to build a website'
url: 'https://reddit.com/r/example/comments/abc123'
author: john_doe
subreddit: webdev
facebook_group: null
comments_count: 5
confidence_score: 8
match_type: strong
status: new
matched_keywords:
- website
- 'web developer'
synced_at: '2025-01-15T10:30:00.000000Z'
contacted_at: null
created_at: '2025-01-15T10:30:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
pagination:
current_page: 1
per_page: 15
total: 150
last_page: 10
properties:
success:
type: boolean
example: true
data:
type: object
properties:
leads:
type: array
example:
-
id: 1
campaign_id: 1
campaign_name: 'Web Development Services'
platform: reddit
platform_id: abc123
title: 'Looking for web developer'
description: 'Need someone to build a website'
url: 'https://reddit.com/r/example/comments/abc123'
author: john_doe
subreddit: webdev
facebook_group: null
comments_count: 5
confidence_score: 8
match_type: strong
status: new
matched_keywords:
- website
- 'web developer'
synced_at: '2025-01-15T10:30:00.000000Z'
contacted_at: null
created_at: '2025-01-15T10:30:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
campaign_id:
type: integer
example: 1
campaign_name:
type: string
example: 'Web Development Services'
platform:
type: string
example: reddit
platform_id:
type: string
example: abc123
title:
type: string
example: 'Looking for web developer'
description:
type: string
example: 'Need someone to build a website'
url:
type: string
example: 'https://reddit.com/r/example/comments/abc123'
author:
type: string
example: john_doe
subreddit:
type: string
example: webdev
facebook_group:
type: string
example: null
comments_count:
type: integer
example: 5
confidence_score:
type: integer
example: 8
match_type:
type: string
example: strong
status:
type: string
example: new
matched_keywords:
type: array
example:
- website
- 'web developer'
items:
type: string
synced_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
contacted_at:
type: string
example: null
created_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
pagination:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 150
last_page:
type: integer
example: 10
tags:
- Leads
'/api/v1/leads/{id}':
get:
summary: 'Get a single lead'
operationId: getASingleLead
description: 'Retrieve detailed information about a specific lead including AI generations and campaign details.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
id: 1
campaign:
id: 1
name: 'Web Development Services'
offering: 'Custom web development'
platform: reddit
platform_id: abc123
title: 'Looking for web developer'
description: 'Need someone to build a website for my startup'
url: 'https://reddit.com/r/example/comments/abc123'
author: john_doe
subreddit: webdev
facebook_group: null
comments_count: 5
confidence_score: 8
match_type: strong
status: new
matched_keywords:
- website
- 'web developer'
ai_generations:
-
id: 1
generated_message: "Hi! I'd love to help with your project..."
created_at: '2025-01-15T10:35:00.000000Z'
synced_at: '2025-01-15T10:30:00.000000Z'
contacted_at: null
created_at: '2025-01-15T10:30:00.000000Z'
updated_at: '2025-01-15T10:30:00.000000Z'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
campaign:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Web Development Services'
offering:
type: string
example: 'Custom web development'
platform:
type: string
example: reddit
platform_id:
type: string
example: abc123
title:
type: string
example: 'Looking for web developer'
description:
type: string
example: 'Need someone to build a website for my startup'
url:
type: string
example: 'https://reddit.com/r/example/comments/abc123'
author:
type: string
example: john_doe
subreddit:
type: string
example: webdev
facebook_group:
type: string
example: null
comments_count:
type: integer
example: 5
confidence_score:
type: integer
example: 8
match_type:
type: string
example: strong
status:
type: string
example: new
matched_keywords:
type: array
example:
- website
- 'web developer'
items:
type: string
ai_generations:
type: array
example:
-
id: 1
generated_message: "Hi! I'd love to help with your project..."
created_at: '2025-01-15T10:35:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
generated_message:
type: string
example: "Hi! I'd love to help with your project..."
created_at:
type: string
example: '2025-01-15T10:35:00.000000Z'
synced_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
contacted_at:
type: string
example: null
created_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:30:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Lead not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Lead not found'
tags:
- Leads
delete:
summary: 'Delete a lead'
operationId: deleteALead
description: 'Permanently delete a lead from your account.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Lead deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Lead deleted successfully'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Lead not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Lead not found'
tags:
- Leads
parameters:
-
in: path
name: id
description: 'The lead ID.'
example: 1
required: true
schema:
type: integer
/api/v1/leads/bulk-delete:
post:
summary: 'Bulk delete leads'
operationId: bulkDeleteLeads
description: 'Delete multiple leads at once by providing an array of lead IDs.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Successfully deleted 3 leads'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Successfully deleted 3 leads'
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
lead_ids:
- 'The lead ids field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
lead_ids:
type: array
example:
- 'The lead ids field is required.'
items:
type: string
tags:
- Leads
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
lead_ids:
type: array
description: 'Array of lead IDs to delete.'
example:
- 1
- 2
- 3
items:
type: string
required:
- lead_ids
'/api/v1/leads/{id}/status':
patch:
summary: 'Update lead status'
operationId: updateLeadStatus
description: 'Update the status of a lead (new, contacted, closed).'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Lead status updated successfully'
data:
id: 1
status: contacted
contacted_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Lead status updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
status:
type: string
example: contacted
contacted_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Lead not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Lead not found'
tags:
- Leads
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: 'The new status.'
example: contacted
nullable: false
required:
- status
parameters:
-
in: path
name: id
description: 'The lead ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/sync/campaign/{id}':
post:
summary: 'Trigger manual sync for a campaign'
operationId: triggerManualSyncForACampaign
description: 'Manually trigger a sync operation for a specific campaign to fetch new leads immediately.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Sync started successfully'
data:
campaign_id: 1
campaign_name: 'Web Development Services'
status: queued
queued_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Sync started successfully'
data:
type: object
properties:
campaign_id:
type: integer
example: 1
campaign_name:
type: string
example: 'Web Development Services'
status:
type: string
example: queued
queued_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
429:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign was synced recently. Please wait before syncing again.'
data:
last_sync_at: '2025-01-15T11:55:00.000000Z'
next_available_sync: '2025-01-15T12:10:00.000000Z'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign was synced recently. Please wait before syncing again.'
data:
type: object
properties:
last_sync_at:
type: string
example: '2025-01-15T11:55:00.000000Z'
next_available_sync:
type: string
example: '2025-01-15T12:10:00.000000Z'
tags:
- Sync
parameters:
-
in: path
name: id
description: 'The campaign ID to sync.'
example: 1
required: true
schema:
type: integer
/api/v1/sync/all:
post:
summary: 'Sync all active campaigns'
operationId: syncAllActiveCampaigns
description: 'Trigger a sync operation for all active campaigns belonging to the authenticated user.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Sync started for 3 campaigns'
data:
total_campaigns: 3
queued_campaigns:
-
id: 1
name: 'Web Development Services'
-
id: 2
name: 'Design Services'
-
id: 3
name: 'SEO Consulting'
queued_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Sync started for 3 campaigns'
data:
type: object
properties:
total_campaigns:
type: integer
example: 3
queued_campaigns:
type: array
example:
-
id: 1
name: 'Web Development Services'
-
id: 2
name: 'Design Services'
-
id: 3
name: 'SEO Consulting'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Web Development Services'
queued_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'No active campaigns found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'No active campaigns found'
tags:
- Sync
'/api/v1/sync/history/{id}':
get:
summary: 'Get sync history for a campaign'
operationId: getSyncHistoryForACampaign
description: 'Retrieve the sync history for a specific campaign with details about each sync operation.'
parameters:
-
in: query
name: page
description: 'Page number for pagination.'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination.'
example: 1
nullable: false
-
in: query
name: per_page
description: 'Number of items per page (max 100).'
example: 15
required: false
schema:
type: integer
description: 'Number of items per page (max 100).'
example: 15
nullable: false
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
campaign_id: 1
campaign_name: 'Web Development Services'
sync_history:
-
id: 1
started_at: '2025-01-15T10:00:00.000000Z'
completed_at: '2025-01-15T10:05:00.000000Z'
status: completed
leads_found: 5
errors: null
duration_seconds: 300
pagination:
current_page: 1
per_page: 15
total: 50
last_page: 4
properties:
success:
type: boolean
example: true
data:
type: object
properties:
campaign_id:
type: integer
example: 1
campaign_name:
type: string
example: 'Web Development Services'
sync_history:
type: array
example:
-
id: 1
started_at: '2025-01-15T10:00:00.000000Z'
completed_at: '2025-01-15T10:05:00.000000Z'
status: completed
leads_found: 5
errors: null
duration_seconds: 300
items:
type: object
properties:
id:
type: integer
example: 1
started_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
completed_at:
type: string
example: '2025-01-15T10:05:00.000000Z'
status:
type: string
example: completed
leads_found:
type: integer
example: 5
errors:
type: string
example: null
duration_seconds:
type: integer
example: 300
pagination:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
tags:
- Sync
parameters:
-
in: path
name: id
description: 'The campaign ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/sync/campaign/{campaignId}/running':
get:
summary: 'Get running sync for a campaign'
operationId: getRunningSyncForACampaign
description: "Retrieve the currently running or queued sync for a specific campaign.\nReturns null if no sync is currently active."
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: ''
type: object
example:
success: true
data:
sync_id: 123
campaign_id: 1
status: running
sync_mode: fast
started_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
sync_id:
type: integer
example: 123
campaign_id:
type: integer
example: 1
status:
type: string
example: running
sync_mode:
type: string
example: fast
started_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
-
description: ''
type: object
example:
success: true
data: null
message: 'No sync currently running for this campaign'
properties:
success:
type: boolean
example: true
data:
type: string
example: null
message:
type: string
example: 'No sync currently running for this campaign'
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Campaign not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Campaign not found'
tags:
- Sync
parameters:
-
in: path
name: campaignId
description: 'The campaign ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/sync/{syncId}':
get:
summary: 'Get sync details by ID'
operationId: getSyncDetailsByID
description: 'Retrieve detailed information about a specific sync operation by its sync history ID.'
parameters:
-
in: header
name: X-API-Key
description: ''
example: your_api_key_here
schema:
type: string
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
sync_id: 123
campaign_id: 1
campaign_name: 'Web Development Services'
status: completed
sync_mode: fast
sync_type: manual
platform: reddit
started_at: '2025-01-15T12:00:00.000000Z'
completed_at: '2025-01-15T12:05:00.000000Z'
posts_found: 25
leads_created: 5
error_message: null
metadata:
keywords_used:
- 'web development help'
- 'need developer'
subreddits_searched:
- webdev
- forhire
properties:
success:
type: boolean
example: true
data:
type: object
properties:
sync_id:
type: integer
example: 123
campaign_id:
type: integer
example: 1
campaign_name:
type: string
example: 'Web Development Services'
status:
type: string
example: completed
sync_mode:
type: string
example: fast
sync_type:
type: string
example: manual
platform:
type: string
example: reddit
started_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
completed_at:
type: string
example: '2025-01-15T12:05:00.000000Z'
posts_found:
type: integer
example: 25
leads_created:
type: integer
example: 5
error_message:
type: string
example: null
metadata:
type: object
properties:
keywords_used:
type: array
example:
- 'web development help'
- 'need developer'
items:
type: string
subreddits_searched:
type: array
example:
- webdev
- forhire
items:
type: string
404:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Sync not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Sync not found'
tags:
- Sync
parameters:
-
in: path
name: syncId
description: 'The sync history ID.'
example: 123
required: true
schema:
type: integer