How to Use the AutoReach API: A Developer's Guide to Lead Generation

What Is the AutoReach API?

The AutoReach API is a RESTful interface that gives developers programmatic access to AutoReach's lead generation capabilities. You can create workflows, manage leads, trigger research and qualification, send outreach, and retrieve results — all through standard HTTP requests. The API uses JSON for request and response bodies, API key authentication, and follows REST conventions for resource naming and HTTP methods.

If you want to integrate AutoReach into your existing tech stack, build custom dashboards, or automate workflows beyond what the UI offers, the API is the way to do it.

Authentication

API Key Generation

1. Log into AutoReach and navigate to Settings > API Keys
2. Click "Generate New API Key"
3. Give the key a descriptive name (e.g., "Production Integration" or "Development Testing")
4. Copy the key immediately — it will not be displayed again
5. Store the key securely (environment variables, secrets manager)

Using Your API Key

Include the API key in the Authorization header of every request:

`` Authorization: Bearer your-api-key-here Content-Type: application/json `

API Key Security

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys every 90 days
• Use separate keys for development and production
• Revoke compromised keys immediately from the Settings page

"Treat your API key like a password. Anyone with your API key can access your AutoReach account programmatically, including your lead data and SMTP credentials." — AutoReach Team

Core API Endpoints

Workflows

Method	Endpoint	Description
GET	/api/workflows	List all workflows
POST	/api/workflows	Create a new workflow
GET	/api/workflows/:id	Get workflow details
PUT	/api/workflows/:id	Update a workflow
DELETE	/api/workflows/:id	Delete a workflow
POST	/api/workflows/:id/run	Start a workflow run
POST	/api/workflows/:id/pause	Pause a running workflow

Leads

Method	Endpoint	Description
GET	/api/leads	List leads (with filtering)
POST	/api/leads	Create a new lead
GET	/api/leads/:id	Get lead details
PUT	/api/leads/:id	Update a lead
DELETE	/api/leads/:id	Delete a lead
POST	/api/leads/:id/qualify	Trigger qualification
GET	/api/leads/:id/research	Get research data

Campaigns

Method	Endpoint	Description
GET	/api/campaigns	List campaigns
POST	/api/campaigns	Create a campaign
GET	/api/campaigns/:id/stats	Get campaign statistics

Account

Method	Endpoint	Description
GET	/api/account	Get account details
GET	/api/account/credits	Get credit balance
GET	/api/account/usage	Get usage statistics

Code Examples

JavaScript (Node.js): Create a Workflow and Add Leads

`javascript const API_BASE = 'https://api.autoreach.work'; const API_KEY = process.env.AUTOREACH_API_KEY;

const headers = { 'Authorization': \Bearer \${API_KEY}\, 'Content-Type': 'application/json' };

// Create a workflow async function createWorkflow() { const response = await fetch(\\${API_BASE}/api/workflows\, { method: 'POST', headers, body: JSON.stringify({ name: 'Q1 SaaS Outreach', stages: ['research', 'qualify', 'contact'], settings: { autoReview: false, dailyLimit: 50 } }) }); return response.json(); }

// Add leads to a workflow async function addLeads(workflowId, leads) { const response = await fetch( \\${API_BASE}/api/workflows/\${workflowId}/leads\, { method: 'POST', headers, body: JSON.stringify({ leads }) } ); return response.json(); } `

Python: Retrieve and Filter Leads

`python import requests import os

API_BASE = 'https://api.autoreach.work' API_KEY = os.environ['AUTOREACH_API_KEY']

headers = { 'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json' }

# Get qualified leads with score above 70 def get_qualified_leads(workflow_id, min_score=70): response = requests.get( f'{API_BASE}/api/leads', headers=headers, params={ 'workflowId': workflow_id, 'status': 'qualified', 'minScore': min_score, 'limit': 100 } ) return response.json()

# Get research data for a specific lead def get_lead_research(lead_id): response = requests.get( f'{API_BASE}/api/leads/{lead_id}/research', headers=headers ) return response.json() `

Rate Limits

The API enforces rate limits to ensure fair usage:

Plan	Requests per Minute	Requests per Day
Starter	60	5,000
Professional	120	20,000
Enterprise	300	100,000

When you hit a rate limit, the API returns a 429 status code with a Retry-After header indicating how long to wait.

Handling Rate Limits

Implement exponential backoff in your integration:

1. If you receive a 429, wait the Retry-After duration
2. Retry the request
3. If you get another 429, double the wait time
4. Maximum retry count: 3 attempts

Pagination

List endpoints support cursor-based pagination:

` GET /api/leads?limit=50&cursor=eyJpZCI6MTAwfQ `

The response includes a nextCursor field. Pass it as the cursor parameter in the next request to get the next page.

Webhooks

AutoReach can send webhook notifications when events occur:

Event	Description
lead.qualified	A lead has been qualified
lead.contacted	An email has been sent to a lead
lead.replied	A lead replied to an outreach email
workflow.completed	A workflow run has finished
workflow.error	A workflow encountered an error

Setting Up Webhooks

Register a webhook URL in Settings > Webhooks or via the API:

` POST /api/webhooks { "url": "https://your-server.com/webhooks/autoreach", "events": ["lead.qualified", "lead.replied"], "secret": "your-webhook-secret" } `

Webhook payloads are signed with HMAC-SHA256 using your webhook secret. Always verify signatures before processing webhook data.

Error Handling

The API uses standard HTTP status codes:

Code	Meaning	Action
200	Success	Process the response
201	Created	Resource was created successfully
400	Bad Request	Check your request body and parameters
401	Unauthorized	Verify your API key
403	Forbidden	You do not have permission for this action
404	Not Found	Check the resource ID
429	Rate Limited	Wait and retry with backoff
500	Server Error	Retry after a brief wait; contact support if persistent

Error responses include a message field with details:

`json { "error": "validation_error", "message": "Workflow name is required", "details": { "field": "name" } } ``

FAQ

Is the API free to use?

API access is included in all paid plans. API calls consume the same credits as UI actions — there is no additional API surcharge.

Can I use the API to build a custom UI?

Yes. The API provides all the data and actions needed to build a custom interface on top of AutoReach. Several customers have built internal tools, Slack integrations, and custom dashboards using the API.

How do I test the API without consuming credits?

Use a development API key with sandbox mode enabled. Sandbox requests return realistic mock data without consuming credits or sending real emails.

Is the API versioned?

Yes. The current version is v1. All endpoints are prefixed with /api/v1/ (though /api/ currently aliases to v1). We will announce any breaking changes with at least 90 days notice.

Can I automate everything through the API?

Almost everything you can do in the AutoReach UI is available through the API. A few account management functions (billing, team invitations) are UI-only for security reasons.

Getting Started

1. Generate an API key in Settings > API Keys
2. Make a test request to GET /api/account to verify authentication
3. Explore the endpoints in our interactive API documentation
4. Build your integration starting with read-only endpoints
5. Add write operations once you are comfortable with the data model

The AutoReach API is designed to be developer-friendly. If you run into issues, the error messages are descriptive, the rate limits are generous, and our documentation covers every endpoint in detail.