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

POST/api/auth/login

User login with email and password

Parameters
emailstringrequired
User email address
passwordstringrequired
User password
Response
Success:
{
  "token": "string",
  "user": "object"
}
Error:
{
  "message": "string"
}
POST/api/auth/register

User registration

Parameters
emailstringrequired
User email address
passwordstringrequired
User password
full_namestringrequired
User full name
companystring
Company name
Response
Success:
{
  "token": "string",
  "user": "object"
}
Error:
{
  "message": "string"
}
POST/api/auth/refresh

Refresh authentication token

Parameters
refresh_tokenstringrequired
Refresh token
Response
Success:
{
  "token": "string"
}
Error:
{
  "message": "string"
}

Leads Management

Lead creation, retrieval, and management endpoints

GET/api/leads

Get user leads with filtering and pagination

Parameters
pagenumber
Page number (default: 1)
limitnumber
Items per page (default: 20)
statusstring
Filter by status
industrystring
Filter by industry
Response
Success:
{
  "leads": "array",
  "total": "number",
  "page": "number"
}
Error:
{
  "message": "string"
}
POST/api/leads

Create a new lead

Parameters
full_namestringrequired
Lead full name
emailstringrequired
Lead email address
companystring
Company name
job_titlestring
Job title
industrystring
Industry
Response
Success:
{
  "lead": "object"
}
Error:
{
  "message": "string"
}
PUT/api/leads/{id}

Update lead information

Parameters
idstringrequired
Lead ID
full_namestring
Lead full name
emailstring
Lead email address
companystring
Company name
statusstring
Lead status
Response
Success:
{
  "lead": "object"
}
Error:
{
  "message": "string"
}

Campaigns

Campaign creation, management, and analytics endpoints

GET/api/campaigns

Get user campaigns

Parameters
statusstring
Filter by status
typestring
Filter by type
Response
Success:
{
  "campaigns": "array"
}
Error:
{
  "message": "string"
}
POST/api/campaigns

Create a new campaign

Parameters
namestringrequired
Campaign name
descriptionstring
Campaign description
typestringrequired
Campaign type (email, voice, mixed)
target_audienceobject
Target audience criteria
Response
Success:
{
  "campaign": "object"
}
Error:
{
  "message": "string"
}
POST/api/campaigns/{id}/assign-leads

Assign leads to a campaign

Parameters
idstringrequired
Campaign ID
lead_idsarrayrequired
Array of lead IDs
Response
Success:
{
  "assigned_count": "number"
}
Error:
{
  "message": "string"
}

AI & Analytics

AI-powered features and analytics endpoints

POST/api/ai/rank-leads

AI-powered lead ranking and scoring

Parameters
lead_idsarrayrequired
Array of lead IDs to rank
criteriaobject
Ranking criteria
Response
Success:
{
  "rankings": "array",
  "summary": "object"
}
Error:
{
  "message": "string"
}
POST/api/ai/generate-email

Generate AI-powered personalized email

Parameters
lead_idstringrequired
Lead ID
campaign_idstringrequired
Campaign ID
tonestring
Email tone (professional, casual)
Response
Success:
{
  "email": "object",
  "confidence": "number"
}
Error:
{
  "message": "string"
}
GET/api/analytics/campaign-performance

Get campaign performance analytics

Parameters
campaign_idstringrequired
Campaign ID
timeframestring
Timeframe (7d, 30d, 90d)
Response
Success:
{
  "metrics": "object",
  "trends": "array"
}
Error:
{
  "message": "string"
}

Email System

Email sending, tracking, and management endpoints

POST/api/email/send

Send email to lead

Parameters
campaign_idstringrequired
Campaign ID
lead_idstringrequired
Lead ID
subjectstringrequired
Email subject
contentstringrequired
Email content
Response
Success:
{
  "email_id": "string",
  "status": "string"
}
Error:
{
  "message": "string"
}
GET/api/email/accounts

Get user email accounts

Parameters
Response
Success:
{
  "accounts": "array"
}
Error:
{
  "message": "string"
}
POST/api/email/accounts

Add email account

Parameters
emailstringrequired
Email address
providerstringrequired
Provider (gmail, outlook)
oauth_tokenstringrequired
OAuth token
Response
Success:
{
  "account": "object"
}
Error:
{
  "message": "string"
}

Error Codes

Common HTTP status codes and their meanings

400

Bad Request

Invalid request parameters or body

Examples:

  • Missing required fields
  • Invalid data format
  • Validation errors
401

Unauthorized

Authentication required or invalid credentials

Examples:

  • Missing authentication token
  • Invalid token
  • Expired token
403

Forbidden

Insufficient permissions for the requested resource

Examples:

  • User lacks required permissions
  • Resource access denied
  • Rate limit exceeded
404

Not Found

Requested resource not found

Examples:

  • Lead not found
  • Campaign not found
  • Invalid endpoint
429

Too Many Requests

Rate limit exceeded

Examples:

  • Too many API calls
  • Rate limit exceeded
  • Throttling applied
500

Internal Server Error

Server-side error occurred

Examples:

  • Database error
  • Service unavailable
  • Unexpected error

Rate Limits

API rate limits and throttling information

General API

1000 requests/hour

Standard rate limit for most endpoints

AI Generation

100 requests/hour

Rate limit for AI-powered features

Email Sending

500 emails/hour

Rate limit for email sending operations

Lead Import

1000 leads/hour

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