Back to App

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
email•stringrequired
User email address
password•stringrequired
User password
Response
Success:
{
  "token": "string",
  "user": "object"
}
Error:
{
  "message": "string"
}
POST/api/auth/register

User registration

Parameters
email•stringrequired
User email address
password•stringrequired
User password
full_name•stringrequired
User full name
company•string
Company name
Response
Success:
{
  "token": "string",
  "user": "object"
}
Error:
{
  "message": "string"
}
POST/api/auth/refresh

Refresh authentication token

Parameters
refresh_token•stringrequired
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
page•number
Page number (default: 1)
limit•number
Items per page (default: 20)
status•string
Filter by status
industry•string
Filter by industry
Response
Success:
{
  "leads": "array",
  "total": "number",
  "page": "number"
}
Error:
{
  "message": "string"
}
POST/api/leads

Create a new lead

Parameters
full_name•stringrequired
Lead full name
email•stringrequired
Lead email address
company•string
Company name
job_title•string
Job title
industry•string
Industry
Response
Success:
{
  "lead": "object"
}
Error:
{
  "message": "string"
}
PUT/api/leads/{id}

Update lead information

Parameters
id•stringrequired
Lead ID
full_name•string
Lead full name
email•string
Lead email address
company•string
Company name
status•string
Lead status
Response
Success:
{
  "lead": "object"
}
Error:
{
  "message": "string"
}

Campaigns

Campaign creation, management, and analytics endpoints

GET/api/campaigns

Get user campaigns

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

Create a new campaign

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

Assign leads to a campaign

Parameters
id•stringrequired
Campaign ID
lead_ids•arrayrequired
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_ids•arrayrequired
Array of lead IDs to rank
criteria•object
Ranking criteria
Response
Success:
{
  "rankings": "array",
  "summary": "object"
}
Error:
{
  "message": "string"
}
POST/api/ai/generate-email

Generate AI-powered personalized email

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

Get campaign performance analytics

Parameters
campaign_id•stringrequired
Campaign ID
timeframe•string
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_id•stringrequired
Campaign ID
lead_id•stringrequired
Lead ID
subject•stringrequired
Email subject
content•stringrequired
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
email•stringrequired
Email address
provider•stringrequired
Provider (gmail, outlook)
oauth_token•stringrequired
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

System ArchitectureDatabase SchemaAI System