Data Surfer API

Programmatic access to company and contact intelligence. Build powerful integrations with our REST API.

Base URL https://api.data-surfer.com/v1

API Key (for testing endpoints)

Enter your API key to test endpoints directly from this page

Authentication

The Data Surfer API uses API keys for authentication. Include your API key in the Authorization header of all requests.

              Authorization Header
            
              Authorization: Bearer ds_live_your_api_key_here

API keys can be created and managed from your Admin Dashboard. Keep your API keys secure and never expose them in client-side code.

Health Check

Verify the API is operational and check the current version. If an API key is provided, it also validates whether the key is valid.

GET /v1/health

This endpoint does not require authentication, but will validate an API key if one is provided.

Query Parameters

No query parameters required.

Response

application/json

                  {
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "1.0.0",
  "authenticated": true
}
                

application/json

                  {
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "1.0.0"
}
                

Response Fields

Field	Type	Description
`status`	string	API status ("ok")
`timestamp`	string	Current server time in ISO 8601 format
`version`	string	API version number
`authenticated`	boolean	Whether a valid API key was provided (only present if Authorization header sent)

List Companies

Returns a paginated list of companies for your organization. Supports filtering by search query and tags.

GET /v1/companies

Query Parameters

Parameter	Type	Default	Description
`q`	string	-	Search query. Searches company name and website.
`tag_ids`	string	-	Comma-separated tag IDs to filter by (e.g., `1,2,3`)
`sort`	string	`created_at`	Sort field: `company_name`, `website`, `created_at`, `updated_at`
`order`	string	`desc`	Sort direction: `asc` or `desc`
`limit`	integer	`20`	Items per page (1-100)
`page`	integer	`1`	Page number

Response

application/json

                  {
  "data": [
    {
      "id": 1,
      "company_name": "Acme Corporation",
      "website": "https://acme.com",
      "tags": [
        { "id": 1, "name": "Enterprise", "color": "#3b82f6" }
      ],
      "custom_fields": {
        "industry": "Technology",
        "employees": "500-1000"
      },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-18T14:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}
                

application/json

                  {
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "total_pages": 0
  }
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique company identifier
`company_name`	string	Company name
`website`	string \| null	Company website URL
`tags`	array	Array of tag objects with `id`, `name`, and `color`
`custom_fields`	object	Key-value pairs of custom field data
`created_at`	string	ISO 8601 timestamp when company was created
`updated_at`	string	ISO 8601 timestamp when company was last updated

Get Company

Returns a single company by ID.

GET /v1/companies/:id

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The company ID

Response Fields

Field	Type	Description
`id`	integer	Unique company identifier
`company_name`	string	Company name
`website`	string \| null	Company website URL
`tags`	array	Array of tag objects with `id`, `name`, and `color`
`custom_fields`	object	Simple key-value pairs of custom field data
`fields`	array	Detailed field array with `key`, `name`, `value`, and `ai_analysis`
`fields[].ai_analysis`	object \| null	AI analysis with `score` (confidence 1-5), `explanation`, and `sources` (URLs)
`created_at`	string	ISO 8601 timestamp when company was created
`updated_at`	string	ISO 8601 timestamp when company was last updated

Response

application/json

                  {
  "data": {
    "id": 1,
    "company_name": "Acme Corporation",
    "website": "https://acme.com",
    "tags": [{ "id": 1, "name": "Enterprise", "color": "#3b82f6" }],
    "custom_fields": { "industry": "Technology", "fit_score": "85" },
    "fields": [
      { "key": "industry", "name": "Industry", "value": "Technology", "ai_analysis": null },
      {
        "key": "fit_score", "name": "Fit Score", "value": "85",
        "ai_analysis": {
          "score": 5,
          "explanation": "Strong match based on company size and tech stack",
          "sources": ["https://acme.com", "https://linkedin.com/company/acme"]
        }
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-18T14:20:00.000Z"
  }
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

application/json

                  {
  "error": "Company not found"
}
                

Company ID *

Create Company

Creates a new company in your organization.

POST /v1/companies

Request Body

Field	Type	Required	Description
`company_name`	string	Yes	The company name
`website`	string \| null	No	The company website URL

Response

application/json

                  {
  "data": {
    "id": 42,
    "company_name": "New Company",
    "website": "https://newcompany.com",
    "created_at": "2024-01-20T10:30:00.000Z",
    "updated_at": "2024-01-20T10:30:00.000Z"
  }
}
                

application/json

                  {
  "error": "company_name is required"
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

application/json

                  {
  "error": "You've reached your plan limit for companies. Please upgrade your plan to add more companies."
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique company identifier
`company_name`	string	Company name
`website`	string \| null	Company website URL
`created_at`	string	ISO 8601 timestamp when company was created
`updated_at`	string	ISO 8601 timestamp when company was last updated

Update Company

Updates an existing company. At least one field must be provided.

PUT /v1/companies/:id

Path Parameters

Parameter	Type	Description
`id`	integer	The company ID to update

Request Body

Field	Type	Required	Description
`company_name`	string	No	The new company name
`website`	string \| null	No	The new company website URL (set to null to clear)

Response

application/json

                  {
  "data": {
    "id": 42,
    "company_name": "Updated Company Name",
    "website": "https://updated-website.com",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
                

application/json

                  {
  "error": "At least one field (company_name or website) must be provided"
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

application/json

                  {
  "error": "Company not found"
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique company identifier
`company_name`	string	Company name
`website`	string \| null	Company website URL
`created_at`	string	ISO 8601 timestamp when company was created
`updated_at`	string	ISO 8601 timestamp when company was last updated

Delete Company

Deletes a company (soft delete). The company will no longer appear in listings but may be recoverable by support.

DELETE /v1/companies/:id

Path Parameters

Parameter	Type	Description
`id`	integer	The company ID to delete

Response

application/json

                  {
  "success": true,
  "message": "Company deleted successfully"
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

application/json

                  {
  "error": "Company not found"
}
                

Response Fields

Field	Type	Description
`success`	boolean	Whether the deletion was successful
`message`	string	Success message

List Fields

Returns the custom field schema for your organization. Use this to understand what fields are available on companies.

GET /v1/companies/fields

Response Fields

Field	Type	Description
`id`	integer	Unique field identifier
`key`	string	Field key used in API responses (e.g., `industry`, `fit_score`)
`name`	string	Human-readable field name
`order`	integer	Display order of the field
`created_at`	string	ISO 8601 timestamp when field was created
`updated_at`	string	ISO 8601 timestamp when field was last updated

Response

application/json

                  {
  "data": [
    { "id": 1, "key": "industry", "name": "Industry", "order": 1, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" },
    { "id": 2, "key": "fit_score", "name": "Fit Score", "order": 2, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" },
    { "id": 3, "key": "is_hiring_engineers", "name": "Is Hiring Engineers", "order": 3, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }
  ],
  "total": 3
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

List Tags

Returns all tags for your organization with the number of companies in each tag.

GET /v1/companies/tags

Query Parameters

No query parameters required.

Response

application/json

                  {
  "data": [
    {
      "id": 1,
      "name": "Enterprise",
      "color": "#3b82f6",
      "company_count": 45,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "name": "Hot Lead",
      "color": "#ef4444",
      "company_count": 12,
      "created_at": "2024-01-16T14:20:00.000Z",
      "updated_at": "2024-01-18T09:15:00.000Z"
    },
    {
      "id": 3,
      "name": "Partner",
      "color": "#22c55e",
      "company_count": 8,
      "created_at": "2024-01-17T11:45:00.000Z",
      "updated_at": "2024-01-17T11:45:00.000Z"
    }
  ],
  "total": 3
}
                

application/json

                  {
  "data": [],
  "total": 0
}
                

application/json

                  {
  "error": "Invalid or missing API key"
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique tag identifier
`name`	string	Tag name
`color`	string	Hex color code for the tag (e.g., `#3b82f6`)
`company_count`	integer	Number of companies with this tag
`created_at`	string	ISO 8601 timestamp when tag was created
`updated_at`	string	ISO 8601 timestamp when tag was last updated

Contacts

List Contacts

Returns a paginated list of contacts for your organization. Supports filtering by search query, company, and tags.

GET /v1/contacts

Query Parameters

Parameter	Type	Default	Description
`q`	string	-	Search query. Searches first name, last name, email, and company name.
`company_id`	integer	-	Filter contacts by company ID
`tag_ids`	string	-	Comma-separated contact tag IDs to filter by
`sort`	string	`created_at`	Sort field: `first_name`, `last_name`, `email`, `created_at`, `updated_at`
`order`	string	`desc`	Sort direction: `asc` or `desc`
`limit`	integer	`20`	Items per page (1-100)
`page`	integer	`1`	Page number

Response

application/json

                  {
  "data": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@acme.com",
      "role": "decision-maker",
      "company_id": 1,
      "company_name": "Acme Corporation",
      "tags": [{ "id": 1, "name": "VIP", "color": "#ef4444" }],
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-18T14:20:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
}
                

application/json

                  { "error": "Invalid or missing API key" }

Response Fields

Field	Type	Description
`id`	integer	Unique contact identifier
`first_name`	string \| null	Contact first name
`last_name`	string \| null	Contact last name
`email`	string \| null	Contact email address
`role`	string \| null	Contact role: `decision-maker`, `champion`, or `influencer`
`company_id`	integer \| null	ID of the associated company
`company_name`	string \| null	Name of the associated company
`tags`	array	Array of tag objects

Get Contact

Returns a single contact by ID with detailed field data including AI analysis.

GET /v1/contacts/:id

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The contact ID

Response

application/json

                  {
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@acme.com",
    "role": "decision-maker",
    "company_id": 1,
    "company_name": "Acme Corporation",
    "tags": [{ "id": 1, "name": "VIP", "color": "#ef4444" }],
    "fields": [
      { "key": "linkedin_url", "name": "LinkedIn URL", "value": "https://linkedin.com/in/johnsmith", "ai_analysis": null }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-18T14:20:00.000Z"
  }
}
                

application/json

                  { "error": "Contact not found" }

Create Contact

Creates a new contact in your organization. At least one of first_name, last_name, or email must be provided.

POST /v1/contacts

Request Body

Field	Type	Required	Description
`first_name`	string \| null	No*	Contact first name
`last_name`	string \| null	No*	Contact last name
`email`	string \| null	No*	Contact email address (must be valid email format)
`company_id`	integer \| null	No	ID of the company to associate this contact with
`role`	string \| null	No	Contact role: `decision-maker`, `champion`, or `influencer`

* At least one of first_name, last_name, or email must be provided.

Response

application/json

                  {
  "data": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "role": "champion",
    "company_id": 1,
    "created_at": "2024-01-20T10:30:00.000Z",
    "updated_at": "2024-01-20T10:30:00.000Z"
  }
}
                

application/json

                  { "error": "At least one of first_name, last_name, or email must be provided" }

Update Contact

Updates an existing contact. At least one field must be provided.

PUT /v1/contacts/:id

Path Parameters

Parameter	Type	Description
`id`	integer	The contact ID to update

Request Body

Field	Type	Required	Description
`first_name`	string	No	New first name
`last_name`	string	No	New last name
`email`	string	No	New email address
`company_id`	integer \| null	No	New company ID (set to null to remove association)
`role`	string \| null	No	New role (set to null to clear)

Response

application/json

                  {
  "data": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "role": "decision-maker",
    "company_id": 2,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
                

application/json

                  { "error": "Contact not found" }

Delete Contact

Deletes a contact (soft delete). The contact will no longer appear in listings but may be recoverable by support.

DELETE /v1/contacts/:id

Path Parameters

Parameter	Type	Description
`id`	integer	The contact ID to delete

Response

application/json

                  { "success": true, "message": "Contact deleted successfully" }

application/json

                  { "error": "Contact not found" }

List Contact Fields

Returns the custom field schema for contacts in your organization.

GET /v1/contacts/fields

Response

application/json

                  {
  "data": [
    { "id": 1, "key": "linkedin_url", "name": "LinkedIn URL", "order": 0, "meta": { "type": "link" }, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }
  ],
  "total": 1
}
                

List Contact Tags

Returns all contact tags for your organization with the number of contacts in each tag.

GET /v1/contacts/tags

Response

application/json

                  {
  "data": [
    { "id": 1, "name": "VIP", "color": "#ef4444", "contact_count": 25, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }
  ],
  "total": 1
}
                

Lookup Companies

Instant lookup of companies from a database of millions of records using keyword filters or semantic search. Keywords are automatically matched - no need to look up IDs first. Consumes 1 instant lookup from your plan limits.

POST /v1/companies/lookup

Request Body

Field	Type	Required	Description
`query`	string	No	Semantic search query (e.g., "B2B SaaS for developers"). Min 3 chars.
`broaden_search`	boolean	No	Include less similar matches in semantic search (default false)
`industries`	array	No	Industry keywords (e.g., ["software", "fintech"])
`countries`	array	No	Country names (e.g., ["united states", "canada"])
`regions`	array	No	Region/state names (e.g., ["california", "new york"])
`cities`	array	No	City names (e.g., ["san francisco", "austin"])
`size_ids`	array	No	Company size IDs (1=1-10, 2=11-50, 3=51-200, 4=201-500, 5=501-1000, 6=1001-5000, 7=5001-10000, 8=10001+)
`company_types`	array	No	"Privately Held", "Public Company", "Nonprofit", "Partnership", "Government Agency", "Educational"
`founded_year_min`	integer	No	Minimum founding year
`founded_year_max`	integer	No	Maximum founding year
`max_results`	integer	No	Max results (default 20). Plan limits: Basic=50, Starter=200, Pro=1000
`save`	boolean	No	Auto-save found companies (default false)

Examples

Search by industry and location

              {
  "industries": ["software", "fintech"],
  "countries": ["united states"],
  "regions": ["california"],
  "max_results": 25
}
            

Semantic search with filters

              {
  "query": "B2B SaaS companies for developers",
  "countries": ["united states", "canada"],
  "size_ids": [3, 4, 5],
  "max_results": 25,
  "save": true
}
            

Simple city-based search

              {
  "cities": ["san francisco", "austin", "seattle"],
  "industries": ["technology"]
}
            

Response

application/json

                  {
  "data": [
    {
      "name": "Stripe",
      "website": "https://stripe.com",
      "industry": "Financial Services",
      "size": "1001-5000 employees",
      "type": "Privately Held",
      "founded": 2010,
      "employee_count": 4500,
      "linkedin_url": "https://www.linkedin.com/company/stripe",
      "tagline": "Financial infrastructure for the internet",
      "similarity": 0.85
    }
  ],
  "total": 1
}
                

application/json

                  {
  "data": [
    {
      "name": "Stripe",
      "website": "https://stripe.com",
      "industry": "Financial Services",
      "size": "1001-5000 employees",
      "type": "Privately Held",
      "founded": 2010,
      "employee_count": 4500,
      "linkedin_url": "https://www.linkedin.com/company/stripe",
      "tagline": "Financial infrastructure for the internet"
    }
  ],
  "total": 1,
  "saved_count": 1
}
                

application/json

                  { "error": "Instant lookup limit reached. Please upgrade your plan." }

Response Fields

Field	Type	Description
`data`	array	Array of company objects
`data[].name`	string	Company name
`data[].website`	string \| null	Company website
`data[].industry`	string \| null	Industry name
`data[].size`	string \| null	Company size range
`data[].type`	string \| null	Company type
`data[].founded`	integer \| null	Year founded
`data[].employee_count`	integer \| null	Employee count
`data[].linkedin_url`	string \| null	LinkedIn URL
`data[].tagline`	string \| null	Company tagline
`data[].similarity`	number	Semantic similarity score (0-1, only present for semantic searches)
`total`	integer	Number of results returned
`saved_count`	integer	Companies saved (only if save=true)
`quota_limited`	integer	Companies not saved due to plan limits

Start Company Deep Search

Start an AI-powered web search to find companies matching a semantic query. Uses multi-tier search including Google Places, web search, and internal database. Companies are automatically saved with an AI-generated tag. Consumes 1 deep search from your plan limits.

POST /v1/companies/deep-search

Request Body

Field	Type	Required	Description
`query`	string	Yes	Semantic search query (e.g., "AI startups in healthcare"). Min 3 chars, max 1000.
`max_results`	integer	No	Target number of companies (default 20, max 100)

Response

application/json

                  {
  "job_id": 456,
  "status": "pending",
  "query": "AI startups in healthcare",
  "target_count": 20,
  "created_at": "2024-01-15T10:30:00.000Z",
  "message": "Company deep search started. Poll GET /v1/companies/deep-search/:job_id for status."
}
                

application/json

                  { "error": "Deep search limit reached. Please upgrade your plan." }

Response Fields

Field	Type	Description
`job_id`	integer	Job ID for polling status
`status`	string	Job status: pending, running, completed, failed
`query`	string	The search query
`target_count`	integer	Target number of companies
`created_at`	string	ISO 8601 timestamp
`message`	string	Instructions for polling

Get Company Deep Search Status

Poll the status of a company deep search job. When status is "completed", companies are automatically saved to your list with an AI-generated tag. Poll every 5-10 seconds until complete.

GET /v1/companies/deep-search/:job_id

Path Parameters

Parameter	Type	Required	Description
`job_id`	integer	Yes	Job ID from POST /v1/companies/deep-search

Response

application/json

                  {
  "job_id": 456,
  "status": "running",
  "query": "AI startups in healthcare",
  "target_count": 20,
  "created_at": "2024-01-15T10:30:00.000Z",
  "started_at": "2024-01-15T10:30:05.000Z",
  "completed_at": null,
  "tag_id": null,
  "tag_name": null,
  "companies_found": 0,
  "companies_saved": 0,
  "error_message": null
}
                

application/json

                  {
  "job_id": 456,
  "status": "completed",
  "query": "AI startups in healthcare",
  "target_count": 20,
  "created_at": "2024-01-15T10:30:00.000Z",
  "started_at": "2024-01-15T10:30:05.000Z",
  "completed_at": "2024-01-15T10:32:45.000Z",
  "tag_id": 123,
  "tag_name": "AI Healthcare Startups",
  "companies_found": 25,
  "companies_saved": 20,
  "error_message": null
}
                

application/json

                  { "error": "Company deep search job not found" }

Response Fields

Field	Type	Description
`job_id`	integer	Job ID
`status`	string	pending \| running \| completed \| failed
`query`	string	The search query
`target_count`	integer	Target number of companies
`created_at`	string	Job creation timestamp
`started_at`	string \| null	Job start timestamp
`completed_at`	string \| null	Job completion timestamp
`tag_id`	integer \| null	ID of auto-created tag (when completed)
`tag_name`	string \| null	Name of auto-created tag (when completed)
`companies_found`	integer	Total companies found (when completed)
`companies_saved`	integer	Companies saved to your list (when completed)
`error_message`	string \| null	Error details (when failed)

Start Contact Search

Start a contact search job for a company. Uses web research to find decision-makers, champions, and influencers at the target company. Returns a job_id for polling status. Consumes 1 deep search from your plan limits.

POST /v1/contacts/search

Request Body

Field	Type	Required	Description
`company_id`	integer	Yes	ID of the company to search contacts for
`roles`	array	No	Target job titles/roles (e.g., ["CEO", "CTO", "VP Sales"])
`max_results`	integer	No	Maximum contacts to find (default 20, max 50)

Examples

Search for specific roles

                  {
  "company_id": 456,
  "roles": ["CEO", "CTO", "VP Sales", "Head of Engineering"],
  "max_results": 20
}
                

Find any contacts at company

                  {
  "company_id": 456
}
                

Limit to top 5 contacts

                  {
  "company_id": 456,
  "roles": ["CEO", "CFO"],
  "max_results": 5
}
                

Response

application/json

                  {
  "job_id": 123,
  "status": "pending",
  "company_id": 456,
  "created_at": "2024-01-15T10:30:00.000Z",
  "message": "Contact search started. Poll GET /v1/contacts/search/:job_id for status."
}
                

application/json

                  { "error": "Company website is required for contact search" }

application/json

                  { "error": "Contact search limit reached. Please upgrade your plan." }

Response Fields

Field	Type	Description
`job_id`	integer	Job ID for polling status
`status`	string	Job status: pending, searching, completed, failed
`company_id`	integer	Target company ID
`created_at`	string	ISO 8601 timestamp
`message`	string	Instructions for polling

Get Contact Search Status

Poll the status of a contact search job. When status is "completed", the contacts array contains the found contacts. Poll every 5-10 seconds until complete.

GET /v1/contacts/search/:job_id

Path Parameters

Parameter	Type	Description
`job_id`	integer	Job ID from POST /v1/contacts/search

Response

application/json

                  {
  "job_id": 123,
  "status": "searching",
  "company_id": 456,
  "company_name": "Acme Corp",
  "created_at": "2024-01-15T10:30:00.000Z",
  "completed_at": null,
  "summary": null,
  "contacts": []
}
                

application/json

                  {
  "job_id": 123,
  "status": "completed",
  "company_id": 456,
  "company_name": "Acme Corp",
  "created_at": "2024-01-15T10:30:00.000Z",
  "completed_at": "2024-01-15T10:31:45.000Z",
  "summary": { "totalFound": 3 },
  "contacts": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Smith",
      "job_title": "CEO",
      "role": "decision-maker",
      "confidence": "high",
      "source_url": "https://acme.com/about"
    },
    {
      "id": 2,
      "first_name": "Jane",
      "last_name": "Doe",
      "job_title": "VP Engineering",
      "role": "champion",
      "confidence": "high",
      "source_url": "https://linkedin.com/in/jane"
    }
  ]
}
                

application/json

                  { "error": "Contact search job not found" }

Response Fields

Field	Type	Description
`job_id`	integer	Job ID
`status`	string	pending \| searching \| completed \| failed \| cancelled
`company_id`	integer	Target company ID
`company_name`	string \| null	Target company name
`created_at`	string	Job creation timestamp
`completed_at`	string \| null	Job completion timestamp
`summary`	object \| null	Results summary (when completed)
`contacts`	array	Found contacts (empty until completed)
`contacts[].id`	integer	Contact ID (for adding)
`contacts[].first_name`	string \| null	First name
`contacts[].last_name`	string \| null	Last name
`contacts[].job_title`	string \| null	Job title
`contacts[].role`	string \| null	Role: decision-maker, champion, influencer
`contacts[].confidence`	string \| null	Confidence: high, medium, low
`contacts[].source_url`	string \| null	Source URL where contact was found

Add Contacts from Search

Add selected contacts from a completed search job to your permanent contacts list. Only works for completed jobs. Consumes contact capacity from your plan limits.

POST /v1/contacts/search/:job_id/add

Path Parameters

Parameter	Type	Description
`job_id`	integer	Job ID of completed search

Request Body

Field	Type	Required	Description
`contact_ids`	array	Yes	Array of contact IDs to add (from search results)

Examples

Add all decision-makers from search

                  {
  "contact_ids": [1, 2, 3, 5, 8]
}
                

Add just the CEO

                  {
  "contact_ids": [1]
}
                

Response

application/json

                  {
  "success": true,
  "added": 2,
  "skipped": 1
}
                

application/json

                  { "error": "Job must be completed before adding contacts" }

application/json

                  { "error": "Job not found" }

Response Fields

Field	Type	Description
`success`	boolean	Whether operation succeeded
`added`	integer	Number of contacts added
`skipped`	integer	Number skipped (duplicates or limit reached)

List Research Templates

Returns all research templates for your organization. Research templates define what data points to extract when researching companies.

GET /v1/research/templates

Response Fields

Field	Type	Description
`id`	string	Unique template identifier (UUID)
`name`	string	Template name
`description`	string \| null	Template description
`fields`	array	Array of data point definitions with `key`, `name`, and `type`
`run_count`	integer	Number of times this template has been run
`last_run_at`	string \| null	ISO 8601 timestamp of last run
`created_at`	string	ISO 8601 timestamp when template was created
`updated_at`	string	ISO 8601 timestamp when template was last updated

application/json

{
  "data": [
    {
      "id": "b43936aa-80d4-426f-bf17-71f0d480831a",
      "name": "General Researcher",
      "description": "Research template for company analysis",
      "fields": [
        { "key": "tech_stack", "name": "Tech Stack", "type": "text" },
        { "key": "is_hiring", "name": "Is Hiring", "type": "boolean" },
        { "key": "fit_score", "name": "Fit Score", "type": "number" }
      ],
      "run_count": 5,
      "last_run_at": "2024-01-15T10:30:00.000Z",
      "created_at": "2024-01-10T09:00:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}
                

application/json

{
  "data": [],
  "total": 0
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

Get Research Template

Returns a single research template by ID with full details including settings.

GET /v1/research/templates/:id

Path Parameters

Parameter	Type	Description
`id`	string	The template ID (UUID)

Response Fields

Field	Type	Description
`id`	string	Unique template identifier (UUID)
`name`	string	Template name
`description`	string \| null	Template description
`fields`	array	Array of data point definitions
`settings`	object	Template settings including `max_pages` and `web_search_enabled`
`run_count`	integer	Number of times this template has been run
`last_run_at`	string \| null	ISO 8601 timestamp of last run
`created_at`	string	ISO 8601 timestamp when template was created
`updated_at`	string	ISO 8601 timestamp when template was last updated

application/json

{
  "data": {
    "id": "b43936aa-80d4-426f-bf17-71f0d480831a",
    "name": "General Researcher",
    "description": "Research template for company analysis",
    "fields": [
      { "key": "tech_stack", "name": "Tech Stack", "type": "text" },
      { "key": "is_hiring", "name": "Is Hiring", "type": "boolean" },
      { "key": "fit_score", "name": "Fit Score", "type": "number" }
    ],
    "settings": {
      "max_pages": 5,
      "web_search_enabled": false
    },
    "run_count": 5,
    "last_run_at": "2024-01-15T10:30:00.000Z",
    "created_at": "2024-01-10T09:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
                

application/json

{
  "success": false,
  "message": "Research template not found",
  "errors": null
}
                

Start Research Run

Start a research job to analyze companies using a template. Specify the template by ID or name. Returns a run_id for polling. Consumes 1 company enrichment per company from your plan limits.

POST /v1/research/run

Request Body

Parameter	Type	Required	Description
`template_id`	string	No*	Template ID (UUID). Either template_id or template_name is required.
`template_name`	string	No*	Template name (case-insensitive). Either template_id or template_name is required.
`company_ids`	array	Yes	Array of company IDs to research (1-100 companies per request)

Start research by template name

curl -X POST https://api.data-surfer.com/v1/research/run \
  -H "Authorization: Bearer ds_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "General Researcher",
    "company_ids": [1, 2, 3, 4, 5]
  }'
                

Start research by template ID

curl -X POST https://api.data-surfer.com/v1/research/run \
  -H "Authorization: Bearer ds_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "b43936aa-80d4-426f-bf17-71f0d480831a",
    "company_ids": [1, 2, 3]
  }'
                

Response Fields

Field	Type	Description
`run_id`	string	Run ID (UUID) for polling status
`template_id`	string	Template ID used
`template_name`	string	Template name
`status`	string	Run status: running
`companies_total`	integer	Number of companies being researched
`created_at`	string	ISO 8601 timestamp
`message`	string	Instructions for polling

application/json

{
  "run_id": "a472488f-c02b-45d3-b9eb-d60d59839495",
  "template_id": "b43936aa-80d4-426f-bf17-71f0d480831a",
  "template_name": "General Researcher",
  "status": "running",
  "companies_total": 5,
  "created_at": "2024-01-15T10:30:00.000Z",
  "message": "Research started. Poll GET /v1/research/run/:run_id for status."
}
                

application/json

{
  "success": false,
  "message": "Either template_id or template_name is required",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Company enrichment limit reached. Please upgrade your plan.",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Research template not found",
  "errors": null
}
                

Get Research Run Status

Poll the status of a research run. When status is "completed", the research results are saved to each company's custom fields. Poll every 5-10 seconds until complete.

GET /v1/research/run/:run_id

Path Parameters

Parameter	Type	Description
`run_id`	string	Run ID (UUID) from POST /v1/research/run

Response Fields

Field	Type	Description
`run_id`	string	Run ID (UUID)
`template_id`	string	Template ID used
`template_name`	string	Template name
`status`	string	running \| completed \| failed
`companies_total`	integer	Total companies in the run
`companies_processed`	integer	Companies successfully processed
`companies_failed`	integer	Companies that failed to process
`started_at`	string	Run start timestamp
`finished_at`	string \| null	Run completion timestamp (null if still running)

application/json

{
  "run_id": "a472488f-c02b-45d3-b9eb-d60d59839495",
  "template_id": "b43936aa-80d4-426f-bf17-71f0d480831a",
  "template_name": "General Researcher",
  "status": "running",
  "companies_total": 5,
  "companies_processed": 2,
  "companies_failed": 0,
  "started_at": "2024-01-15T10:30:00.000Z",
  "finished_at": null
}
                

application/json

{
  "run_id": "a472488f-c02b-45d3-b9eb-d60d59839495",
  "template_id": "b43936aa-80d4-426f-bf17-71f0d480831a",
  "template_name": "General Researcher",
  "status": "completed",
  "companies_total": 5,
  "companies_processed": 5,
  "companies_failed": 0,
  "started_at": "2024-01-15T10:30:00.000Z",
  "finished_at": "2024-01-15T10:35:00.000Z"
}
                

application/json

{
  "success": false,
  "message": "Research run not found",
  "errors": null
}
                

List Outreach Leads

Returns a paginated list of outreach leads for your organization. Filter by lead status (cold or warm).

GET /v1/outreach/leads

Query Parameters

Parameter	Type	Default	Description
`status`	string	`cold`	Lead status filter: `cold` or `warm`
`limit`	integer	`20`	Items per page (1-100)
`page`	integer	`1`	Page number

Response

application/json

                  {
  "data": [
    {
      "id": 1,
      "company_id": 42,
      "company_name": "Acme Corporation",
      "website": "https://acme.com",
      "lead_status": "cold",
      "warming_score": 35,
      "target_score": 70,
      "activity_count": 8,
      "recommendation_count": 3,
      "monitoring_active": true,
      "last_activity_at": "2024-01-18T14:20:00.000Z",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique lead identifier
`company_id`	integer	Associated company ID
`company_name`	string	Company name
`lead_status`	string	Lead status: `cold` or `warm`
`warming_score`	integer	Current warming score (0-100)
`activity_count`	integer	Total number of logged activities
`recommendation_count`	integer	Number of active recommendations
`monitoring_active`	boolean	Whether signal monitoring is enabled
`last_activity_at`	string \| null	ISO 8601 timestamp of last activity

Get Outreach Lead

Returns full details for an outreach lead including company info, warming score, monitoring pages, contacts, competitors, touchpoints, and recommendations.

GET /v1/outreach/leads/:id

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "id": 1,
  "company_id": 42,
  "company_name": "Acme Corporation",
  "website": "https://acme.com",
  "lead_status": "cold",
  "warming_score": 35,
  "target_score": 70,
  "deal_value": null,
  "deal_currency": "USD",
  "deal_won": false,
  "monitoring_pages": [
    { "id": 1, "page_type": "company", "page_url": "https://acme.com/blog", "label": "Company Blog", "monitoring_score": 9, "is_selected": true }
  ],
  "contacts": [
    { "id": 10, "first_name": "Jane", "last_name": "Doe", "title": "VP of Sales", "is_pinned": true }
  ],
  "competitors": [],
  "touchpoints": [
    { "id": 1, "description": "Commented on their blog post about AI", "detected_type": "comment", "created_at": "2024-01-18T14:20:00.000Z" }
  ],
  "recommendations": [
    { "id": 1, "action_type": "comment", "target_url": "https://acme.com/blog/ai-trends", "suggested_comment": "Great insights...", "priority": "high" }
  ],
  "last_activity_at": "2024-01-18T14:20:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z"
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Response Fields

Field	Type	Description
`id`	integer	Unique lead identifier
`lead_status`	string	Lead status: `cold` or `warm`
`warming_score`	integer	Current warming score (0-100)
`monitoring_pages`	array	Discovered monitoring sources with scores and selection status
`contacts`	array	Key contacts associated with this lead
`competitors`	array	Competitors being tracked
`touchpoints`	array	Recent activity log entries
`recommendations`	array	Active engagement recommendations
`deal_value`	number \| null	Deal value (warm leads)
`deal_won`	boolean	Whether the deal has been won

Add to Outreach

Add one or more saved companies to the outreach pipeline. Companies can be added as cold leads (for social warming) or warm leads (for active nurturing).

POST /v1/outreach/leads

Request Body

Field	Type	Required	Description
`company_ids`	integer[]	Yes	Array of company IDs to add (1-100)
`lead_status`	string	No	Lead status: `cold` (default) or `warm`

Response

application/json

                  {
  "success": true,
  "created": 2,
  "restored": 0,
  "moved": 0,
  "skipped": 1,
  "total": 3
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

Response Fields

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`created`	integer	Number of new leads created
`restored`	integer	Number of previously deleted leads restored
`moved`	integer	Number of leads moved between cold/warm
`skipped`	integer	Number already in requested status
`total`	integer	Total leads processed

Remove from Outreach

Remove one or more leads from the outreach pipeline. This soft-deletes the leads and frees any associated site signal slots.

DELETE /v1/outreach/leads

Request Body

Field	Type	Required	Description
`lead_ids`	integer[]	Yes	Array of lead IDs to remove (1-100)

Response

application/json

                  {
  "success": true,
  "deleted": 2
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

Change Lead Status

Move a lead between cold and warm status. When moving to warm, contacts with monitoring pages are automatically pinned as key contacts.

PATCH /v1/outreach/leads/:id/status

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`lead_status`	string	Yes	New status: `cold` or `warm`

Response

application/json

                  {
  "success": true,
  "id": 1,
  "lead_status": "warm"
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Update Target Score

Update the target warming score for a lead. When the warming score reaches the target, the lead is considered ready for direct outreach.

PATCH /v1/outreach/leads/:id/target-score

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`target_score`	integer	Yes	Target warming score (1-100)

Response

application/json

                  {
  "success": true,
  "id": 1,
  "target_score": 80
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Start Signal Scan

Start an AI-powered signal scan for an outreach lead. Discovers company web pages (blog, careers, press), social profiles, and key contacts' social accounts. Each source is scored 1-10 for monitoring value. Occupies 1 site signal slot (capacity-based -- slot is freed when lead is removed).

POST /v1/outreach/leads/:id/signal-scan

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "success": true,
  "job_id": "scan_abc123",
  "max_pages": 20,
  "estimated_time_minutes": 2
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "You've reached your plan limit for site signals.",
  "errors": null
}
                

Get Signal Scan Status

Check the progress of a signal scan. Returns the scan status, progress percentage, and discovered pages once complete.

GET /v1/outreach/leads/:id/signal-scan

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "status": "completed",
  "progress": 100,
  "pages_found": 12,
  "message": "Signal scan completed successfully"
}
                

application/json

{
  "status": "none",
  "message": "No signal scan has been started for this lead"
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

Toggle Monitoring Page

Enable or disable a specific monitoring source discovered by a signal scan. Enabled sources are monitored for new content and used to generate engagement recommendations.

PATCH /v1/outreach/leads/:id/monitoring-pages/:pageId

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`pageId`	integer	The monitoring page ID

Request Body

Field	Type	Required	Description
`is_selected`	boolean	Yes	Whether to enable (`true`) or disable (`false`) monitoring

Response

application/json

                  {
  "success": true,
  "id": 5,
  "is_selected": true
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Monitoring page not found",
  "errors": null
}
                

Get Recommendations

Get AI-generated engagement recommendations for a lead. For cold leads: social warming actions (comment on posts, follow, like). For warm leads: nurturing actions (share content, check in, congratulate). Each includes a target URL, suggested comment, priority, and engagement reason.

GET /v1/outreach/leads/:id/recommendations

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "recommendations": [
    {
      "id": 1,
      "action_type": "comment",
      "target_url": "https://acme.com/blog/ai-trends",
      "suggested_comment": "Great insights on AI adoption...",
      "priority": "high",
      "engagement_reason": "Recent blog post relevant to your offering",
      "source_page_label": "Company Blog",
      "created_at": "2024-01-18T10:00:00.000Z"
    }
  ],
  "count": 1,
  "progress": { "completed": 3, "dismissed": 1, "total": 5 }
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Generate Recommendations

Trigger AI generation of new engagement recommendations based on the lead's enabled monitoring sources. Recommendations are generated asynchronously -- poll with Get Recommendations to see results.

POST /v1/outreach/leads/:id/recommendations/generate

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "started": true
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Complete Recommendation

Mark a recommendation as completed. Completing a recommendation awards warming score points and auto-dismisses other recommendations targeting the same post.

POST /v1/outreach/leads/:id/recommendations/:recId/complete

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`recId`	integer	The recommendation ID

Response

application/json

                  {
  "success": true,
  "dismissedIds": [4, 5]
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Recommendation not found or already completed",
  "errors": null
}
                

Dismiss Recommendation

Dismiss a recommendation you don't want to act on. Dismissed recommendations are hidden from the active list.

POST /v1/outreach/leads/:id/recommendations/:recId/dismiss

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`recId`	integer	The recommendation ID

Response

application/json

                  {
  "success": true
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Recommendation not found or already dismissed",
  "errors": null
}
                

Log Activity

Log a sales or engagement activity. Describe what happened in natural language -- the AI automatically detects the activity type (email, call, meeting, LinkedIn message, comment, like, follow, etc.) and any dates mentioned. Activities contribute to the warming score with context-aware bonus points.

POST /v1/outreach/leads/:id/touchpoints

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`description`	string	Yes	Natural language description of the activity (1-5000 chars)
`contact_id`	integer \| null	No	Optional contact ID this activity is about

Response

application/json

                  {
  "success": true,
  "touchpoint": {
    "id": 15,
    "description": "Commented on their LinkedIn post about AI trends",
    "detected_type": "comment",
    "contact_id": null,
    "bonus_points": 3,
    "created_at": "2024-01-18T14:20:00.000Z"
  },
  "detected_type": "comment",
  "bonus_info": {
    "base_points": 2,
    "multiplier": 1.5,
    "total": 3,
    "reason": "First engagement with this company"
  }
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Get Lead Notes

Get all notes for an outreach lead, ordered by creation date (newest first).

GET /v1/outreach/leads/:id/notes

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Response

application/json

                  {
  "data": [
    {
      "id": 1,
      "content": "CEO mentioned they're evaluating new solutions in Q2",
      "created_at": "2024-01-18T14:20:00.000Z"
    }
  ],
  "total": 1
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Add Lead Note

Add a note to an outreach lead. Notes are free-form text for recording observations, strategy, or context about the lead.

POST /v1/outreach/leads/:id/notes

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`content`	string	Yes	Note content (1-10000 chars)

Response

application/json

                  {
  "success": true,
  "note": {
    "id": 5,
    "content": "CEO mentioned they're evaluating new solutions in Q2",
    "created_at": "2024-01-18T14:20:00.000Z"
  }
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Toggle Key Contact

Pin or unpin a contact as a key contact for this lead. Key contacts appear in the lead dashboard and their social profiles can be monitored for engagement opportunities.

PATCH /v1/outreach/leads/:id/contacts/:contactId

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`contactId`	integer	The contact ID

Request Body

Field	Type	Required	Description
`is_selected`	boolean	Yes	Whether to pin (`true`) or unpin (`false`) the contact

Response

application/json

                  {
  "success": true,
  "id": 12,
  "is_selected": true
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Update Deal

Update deal tracking information for a warm lead. Set the deal value, currency, and mark deals as won. All fields are optional -- only provided fields are updated.

PATCH /v1/outreach/leads/:id/deal

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`deal_value`	number \| null	No	Deal value (set to null to clear)
`deal_currency`	string	No	Currency code, e.g., `USD`, `EUR`, `GBP` (1-3 chars)
`deal_won`	boolean	No	Whether the deal has been won

Response

application/json

                  {
  "success": true,
  "id": 1,
  "deal_value": 50000,
  "deal_currency": "USD",
  "deal_won": false
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Add Competitor

Add a competitor to monitor for an outreach lead. Competitors can be scanned to discover their web pages and content for competitive intelligence.

POST /v1/outreach/leads/:id/competitors

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID

Request Body

Field	Type	Required	Description
`name`	string	Yes	Competitor company name (1-255 chars)
`website`	string	Yes	Competitor website URL (1-255 chars)

Response

application/json

                  {
  "success": true,
  "competitor": {
    "id": 3,
    "name": "Competitor Inc",
    "website": "competitor.com",
    "is_pinned": false,
    "scan_status": "none"
  }
}
                

application/json

{
  "success": false,
  "error": "A competitor with this website already exists: Competitor Inc"
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Outreach lead not found",
  "errors": null
}
                

Scan Competitor

Start an AI scan of a competitor's website to discover their pages, content, and positioning. Scan results are stored on the competitor record.

POST /v1/outreach/leads/:id/competitors/:competitorId/scan

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`competitorId`	integer	The competitor ID

Response

application/json

                  {
  "success": true,
  "competitor_id": 3,
  "estimated_time_minutes": 1
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Competitor not found",
  "errors": null
}
                

Toggle Competitor Pin

Pin or unpin a competitor. Pinned competitors are highlighted in the lead dashboard for quick access.

PATCH /v1/outreach/leads/:id/competitors/:competitorId

Path Parameters

Parameter	Type	Description
`id`	integer	The lead ID
`competitorId`	integer	The competitor ID

Request Body

Field	Type	Required	Description
`is_pinned`	boolean	Yes	Whether to pin (`true`) or unpin (`false`) the competitor

Response

application/json

                  {
  "success": true,
  "id": 3,
  "is_pinned": true
}
                

application/json

{
  "success": false,
  "message": "Invalid or missing API key",
  "errors": null
}
                

application/json

{
  "success": false,
  "message": "Competitor not found",
  "errors": null
}
                

Rate Limits

API access is available on Starter and Pro plans. All API requests are subject to rate limiting to ensure fair usage and service stability.

Limits

Requests are limited to 100 requests per minute per API key. If you exceed this limit, requests will return a 429 Too Many Requests response.

Response Headers

Rate limit information is included in all API responses:

Response Headers

              X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1705320000
            

Errors

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - API access not available on your plan
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

application/json

              {
  "error": "Invalid or missing API key"
}
            