API Reference
Complete API documentation for the Neptie platform, including authentication, endpoints, request/response formats, and usage examples.
API Overview
High-level overview of the Neptie API architecture
Base URL
https://api.neptie.com/v1
Content Type
application/json
API Features
- RESTful design principles
- JWT-based authentication
- Rate limiting and throttling
- Comprehensive error handling
Authentication
How to authenticate with the Neptie API
Authentication
All API endpoints require authentication using JWT tokens
Authentication Methods
Bearer Token
Include the JWT token in the Authorization header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
API Key
For service-to-service communication
X-API-Key: your-api-key-here
API Scopes
- read:leads - Read access to leads
- write:leads - Create and update leads
- read:campaigns - Read access to campaigns
- write:campaigns - Create and update campaigns
- read:analytics - Access to analytics data
- admin:all - Full administrative access
API Endpoints
Complete list of available API endpoints organized by category
Authentication
User authentication and authorization endpoints
/api/auth/login
User login with email and password
Parameters
Response
{
"token": "string",
"user": "object"
}
{
"message": "string"
}
/api/auth/register
User registration
Parameters
Response
{
"token": "string",
"user": "object"
}
{
"message": "string"
}
/api/auth/refresh
Refresh authentication token
Parameters
Response
{
"token": "string"
}
{
"message": "string"
}
Leads Management
Lead creation, retrieval, and management endpoints
/api/leads
Get user leads with filtering and pagination
Parameters
Response
{
"leads": "array",
"total": "number",
"page": "number"
}
{
"message": "string"
}
/api/leads
Create a new lead
Parameters
Response
{
"lead": "object"
}
{
"message": "string"
}
/api/leads/{id}
Update lead information
Parameters
Response
{
"lead": "object"
}
{
"message": "string"
}
Campaigns
Campaign creation, management, and analytics endpoints
/api/campaigns
Get user campaigns
Parameters
Response
{
"campaigns": "array"
}
{
"message": "string"
}
/api/campaigns
Create a new campaign
Parameters
Response
{
"campaign": "object"
}
{
"message": "string"
}
/api/campaigns/{id}/assign-leads
Assign leads to a campaign
Parameters
Response
{
"assigned_count": "number"
}
{
"message": "string"
}
AI & Analytics
AI-powered features and analytics endpoints
/api/ai/rank-leads
AI-powered lead ranking and scoring
Parameters
Response
{
"rankings": "array",
"summary": "object"
}
{
"message": "string"
}
/api/ai/generate-email
Generate AI-powered personalized email
Parameters
Response
{
"email": "object",
"confidence": "number"
}
{
"message": "string"
}
/api/analytics/campaign-performance
Get campaign performance analytics
Parameters
Response
{
"metrics": "object",
"trends": "array"
}
{
"message": "string"
}
Email System
Email sending, tracking, and management endpoints
/api/email/send
Send email to lead
Parameters
Response
{
"email_id": "string",
"status": "string"
}
{
"message": "string"
}
/api/email/accounts
Get user email accounts
Parameters
Response
{
"accounts": "array"
}
{
"message": "string"
}
/api/email/accounts
Add email account
Parameters
Response
{
"account": "object"
}
{
"message": "string"
}
Error Codes
Common HTTP status codes and their meanings
Bad Request
Invalid request parameters or body
Examples:
- • Missing required fields
- • Invalid data format
- • Validation errors
Unauthorized
Authentication required or invalid credentials
Examples:
- • Missing authentication token
- • Invalid token
- • Expired token
Forbidden
Insufficient permissions for the requested resource
Examples:
- • User lacks required permissions
- • Resource access denied
- • Rate limit exceeded
Not Found
Requested resource not found
Examples:
- • Lead not found
- • Campaign not found
- • Invalid endpoint
Too Many Requests
Rate limit exceeded
Examples:
- • Too many API calls
- • Rate limit exceeded
- • Throttling applied
Internal Server Error
Server-side error occurred
Examples:
- • Database error
- • Service unavailable
- • Unexpected error
Rate Limits
API rate limits and throttling information
General API
Standard rate limit for most endpoints
AI Generation
Rate limit for AI-powered features
Email Sending
Rate limit for email sending operations
Lead Import
Rate limit for bulk lead import operations
Code Examples
Practical examples of API usage in different programming languages
JavaScript/Node.js
// Get user leads const response = await fetch('https://api.neptie.com/v1/leads', { headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN', 'Content-Type': 'application/json' } }); const leads = await response.json(); // Create a new lead const newLead = await fetch('https://api.neptie.com/v1/leads', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ full_name: 'John Doe', email: 'john@example.com', company: 'Example Corp', job_title: 'CEO' }) });
Python
import requests # Get user leads headers = { 'Authorization': 'Bearer YOUR_JWT_TOKEN', 'Content-Type': 'application/json' } response = requests.get('https://api.neptie.com/v1/leads', headers=headers) leads = response.json() # Create a new lead lead_data = { 'full_name': 'John Doe', 'email': 'john@example.com', 'company': 'Example Corp', 'job_title': 'CEO' } response = requests.post('https://api.neptie.com/v1/leads', headers=headers, json=lead_data) new_lead = response.json()
cURL
# Get user leads curl -X GET https://api.neptie.com/v1/leads \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" # Create a new lead curl -X POST https://api.neptie.com/v1/leads \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "full_name": "John Doe", "email": "john@example.com", "company": "Example Corp", "job_title": "CEO" }'
Explore More
Learn more about the technical aspects of the Neptie platform