# Data Surfer API

> Data Surfer is a B2B sales intelligence platform that helps teams research companies, find contacts, and enrich data using AI.

This is the official REST API for Data Surfer. Base URL: https://api.data-surfer.com/v1

## Documentation

- [API Documentation](https://api.data-surfer.com): Full interactive API reference with try-it-out functionality
- [Detailed API Reference (Markdown)](https://api.data-surfer.com/llms.md): Complete endpoint documentation in markdown format

## Authentication

All API requests (except /health) require an API key passed in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

API keys can be generated in Settings > API Keys within the Data Surfer application.

## Endpoints Overview

### Health
- GET /v1/health - Check API status and validate API key

### Companies
- GET /v1/companies - List companies with pagination and filtering
- GET /v1/companies/:id - Get a single company by ID
- GET /v1/companies/fields - List custom field schema
- GET /v1/companies/:id/tags - Get company tags
- POST /v1/companies - Create a new company
- PUT /v1/companies/:id - Update a company
- DELETE /v1/companies/:id - Delete a company

### Contacts
- GET /v1/contacts - List contacts with pagination and filtering
- GET /v1/contacts/:id - Get a single contact by ID
- GET /v1/contacts/fields - List custom field schema for contacts
- GET /v1/contacts/:id/tags - Get contact tags
- POST /v1/contacts - Create a new contact
- PUT /v1/contacts/:id - Update a contact
- DELETE /v1/contacts/:id - Delete a contact

### Company Lookup (Instant)
- POST /v1/companies/lookup - Instant company lookup by domain/name

### Deep Search
- POST /v1/companies/:id/deep-search - Start deep company research
- GET /v1/companies/:id/deep-search/:searchId - Get deep search results

### Contact Search
- POST /v1/contacts/search - Start contact search for a company
- GET /v1/contacts/search/:searchId - Get contact search results
- POST /v1/contacts/search/:searchId/add - Add found contacts to your database

### Research Templates
- GET /v1/research-templates - List available research templates
- GET /v1/research-templates/:id - Get research template details
- POST /v1/research-templates/:id/run - Run research template on companies
- GET /v1/research-templates/runs/:runId - Get research run status and results

### Outreach
- GET /v1/outreach/leads - List cold outreach or warm leads with pagination
- GET /v1/outreach/leads/:id - Get full lead details (monitoring pages, contacts, recommendations, activities)
- POST /v1/outreach/leads - Add companies to outreach pipeline (cold or warm)
- DELETE /v1/outreach/leads - Remove leads from outreach
- PATCH /v1/outreach/leads/:id/status - Change lead status (cold/warm)
- PATCH /v1/outreach/leads/:id/target-score - Update target warming score
- POST /v1/outreach/leads/:id/signal-scan - Start AI signal discovery scan
- GET /v1/outreach/leads/:id/signal-scan - Get signal scan progress
- PATCH /v1/outreach/leads/:id/monitoring-pages/:pageId - Enable/disable monitoring source
- GET /v1/outreach/leads/:id/recommendations - Get AI engagement recommendations
- POST /v1/outreach/leads/:id/recommendations/generate - Trigger recommendation generation
- POST /v1/outreach/leads/:id/recommendations/:recId/complete - Complete a recommendation
- POST /v1/outreach/leads/:id/recommendations/:recId/dismiss - Dismiss a recommendation
- POST /v1/outreach/leads/:id/touchpoints - Log a sales activity (AI auto-detects type)
- GET /v1/outreach/leads/:id/notes - Get lead notes
- POST /v1/outreach/leads/:id/notes - Add a lead note
- PATCH /v1/outreach/leads/:id/contacts/:contactId - Pin/unpin key contact
- PATCH /v1/outreach/leads/:id/deal - Update deal value/currency/won status
- POST /v1/outreach/leads/:id/competitors - Add competitor to monitor
- POST /v1/outreach/leads/:id/competitors/:competitorId/scan - Scan competitor website
- PATCH /v1/outreach/leads/:id/competitors/:competitorId - Pin/unpin competitor

## Rate Limits

API requests are rate limited based on your plan. Rate limit headers are included in responses:
- X-RateLimit-Limit: Maximum requests per window
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Unix timestamp when window resets

## Response Format

All responses are JSON. Successful responses include a `data` field. Paginated responses include a `pagination` object.

Error responses include:
- `success`: false
- `message`: Human-readable error description
- `errors`: Detailed validation errors (if applicable)