Outsoci API Documentation

Programmatic access to Outsoci's email scraping capabilities. Use our REST API to integrate lead generation into your workflow.

API key authenticationRate limits based on your subscription planWebhook support for async notificationsCredit-based usage modelJSON responses with consistent error format

Rate Limits

Rate limits are applied per API key and reset every minute. Limits vary by subscription plan.

Plan	Requests / minute
TRIAL	30 requests/minute
FREE	30 requests/minute
STARTER_MONTHLY	100 requests/minute
STARTER_YEARLY	100 requests/minute
PRO_MONTHLY	500 requests/minute
PRO_YEARLY	500 requests/minute
BUSINESS_MONTHLY	2000 requests/minute
BUSINESS_YEARLY	2000 requests/minute
ENTERPRISE	10000 requests/minute

Authentication

All API requests require an API key. Include your key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

You can generate API keys in your Dashboard →

Error Responses

Errors are returned with appropriate HTTP status codes and a JSON body containing an error field.

401 Unauthorized

{ "error": "Invalid API key" }

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Try again in X minutes."
}

402 Payment Required

{
  "error": "Insufficient credits",
  "required": 150,
  "available": 75
}

500 Internal Server Error

{ "error": "Internal server error" }

OpenAPI Specification

We maintain a machine-readable OpenAPI 3.0 specification for the Outsoci API. You can use it with API clients, documentation generators, or testing tools.

Download openapi.json

Webhooks

Configure a webhook URL to receive real-time notifications when your scraping jobs complete. Set your webhook via the /api/v1/webhooks endpoint.

You can choose between two formats:

Batch: One notification when the job finishes, with a download URL to retrieve all results.
Per-result: A separate notification for each lead as it is scraped, containing the result data directly.

Batch Payload (completion)

{
  "event": "scrape.completed",
  "scrape_id": 12345,
  "user_id": "usr_abc123",
  "platform": "instagram",
  "keyword": "fitness coaches",
  "results_count": 94,
  "requested_results": 100,
  "completed_at": "2026-03-06T20:32:15.000Z",
  "download_url": "https://outsoci.com/api/download-scrape-results",
  "formats": ["csv", "xls"]
}

Per-Result Payload (real-time)

{
  "event": "scrape.result",
  "scrape_id": 12345,
  "user_id": "usr_abc123",
  "platform": "instagram",
  "keyword": "fitness coaches",
  "completed_at": "2026-03-06T20:32:15.000Z",
  "result": {
    "title": "John Doe - Fitness Coach",
    "email": "john@example.com",
    "link": "https://instagram.com/johndoe",
    "platform": "instagram",
    "keyword": "fitness coaches"
  }
}

Testing Your Webhook

You can test your webhook by using a service like webhook.site or RequestBin. Set the webhook URL to your test endpoint, trigger a scrape, and inspect the incoming payloads.

API Reference

Authentication & Account

GET/api/v1/account

Retrieve your account information including credits and subscription plan.

Required Fields

None

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" https://outsoci.com/api/v1/account

Example Response

{
  "success": true,
  "account": {
    "email": "user@example.com",
    "credits": 5432,
    "plan": "PRO_MONTHLY",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Auth requiredRate limited

Scraping

POST/api/v1/scrape

Start a new scraping job. The job is processed asynchronously via RabbitMQ.

Required Fields

keyword (string), platform (string), results (number)

Optional Fields

country, location, validateEmails (boolean), includeSynonyms (boolean), avoidDuplicates (boolean), tbs (string)

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "fitness coaches",
    "platform": "instagram",
    "results": 100,
    "validateEmails": true,
    "location": "United States"
  }' https://outsoci.com/api/v1/scrape

Example Response

{
  "success": true,
  "message": "Scrape request created",
  "scrapeId": 12345,
  "credits": 9876,
  "estimatedMaxCost": 150
}

Auth requiredRate limited

GET/api/v1/scrape/:id

Get the status and results count of a scraping job.

Required Fields

None

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" https://outsoci.com/api/v1/scrape/12345

Example Response

{
  "success": true,
  "scrape": {
    "id": 12345,
    "keyword": "fitness coaches",
    "platform": "instagram",
    "status": "DONE",
    "resultsCount": 94,
    "progress": 100,
    "requestedAt": "2026-03-06T20:30:00.000Z",
    "updatedAt": "2026-03-06T20:32:15.000Z",
    "downloadUrl": "https://outsoci.com/api/download-scrape-results"
  }
}

Auth requiredRate limited

POST/api/download-scrape-results

Download the results of a completed scrape in CSV or Excel format. Requires id_scraping and format parameters.

Required Fields

id_scraping (number), format (string: "csv" or "xls")

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id_scraping": 12345,
    "format": "csv"
  }' https://outsoci.com/api/download-scrape-results

Example Response

File attachment (binary) with Content-Disposition header.

Auth requiredRate limited

Keyword Generation

POST/api/v1/keywords

Generate targeted keywords for scraping using AI (Gemini).

Required Fields

description (string)

Optional Fields

platform (string) - one of: instagram, facebook, linkedin, twitter, youtube, tiktok, maps.google.com, multi

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "B2B SaaS founders in Europe with 10-50 employees",
    "platform": "linkedin"
  }' https://outsoci.com/api/v1/keywords

Example Response

{
  "success": true,
  "keywords": "CEO, founder, managing director, CTO, startup founder, entrepreneur, business owner, SaaS founder"
}

Auth requiredRate limited

Webhooks

GET/api/v1/webhooks

Retrieve your current webhook configuration (URL and format).

Required Fields

None

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" https://outsoci.com/api/v1/webhooks

Example Response

{
  "success": true,
  "webhook": {
    "url": "https://your-server.com/webhooks/outsoci",
    "format": "batch"
  }
}

Auth requiredRate limited

POST/api/v1/webhooks

Configure your webhook URL and format. If you don't provide a format, it defaults to "batch".

Required Fields

url (HTTPS URL)

Optional Fields

format (string: "batch" or "per_result")

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/outsoci",
    "format": "batch"
  }' https://outsoci.com/api/v1/webhooks

Example Response

{
  "success": true,
  "webhook": {
    "url": "https://your-server.com/webhooks/outsoci",
    "format": "batch"
  }
}

Auth requiredRate limited

DELETE/api/v1/webhooks

Clear your webhook configuration (both URL and format).

Required Fields

None

Example Request

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" https://outsoci.com/api/v1/webhooks

Example Response

{
  "success": true,
  "message": "Webhook configuration cleared"
}

Auth requiredRate limited