# ScrapeLinkedIn API

> Send a LinkedIn profile URL. Get back structured profile data (full name, experience, education). $0.01 per successful lookup. You only pay when we find the data.

## Documentation

- [Full API Documentation](https://scrapelinkedin.com/llms-full.txt): Complete API reference with all endpoints, authentication, batch processing, pricing, error codes, and curl examples
- [OpenAPI Specification](https://scrapelinkedin.com/openapi.json): Machine-readable API schema for tool integration and code generation
- [Interactive API Docs](https://api.scrapelinkedin.com/docs): Swagger UI for trying endpoints in-browser

## Quick Start

Base URL: `https://api.scrapelinkedin.com/api/v1`

### 1. Register and get an API key

```bash
# Create account
curl -X POST https://api.scrapelinkedin.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

# Verify email (check inbox for 6-digit code)
curl -X POST https://api.scrapelinkedin.com/api/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'

# Get API key (5 free credits included)
curl -X POST https://api.scrapelinkedin.com/api/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

### 2. Scrape a LinkedIn profile

```bash
curl -X POST https://api.scrapelinkedin.com/api/v1/scrape \
  -H "Content-Type: application/json" \
  -H "X-API-Key: li_live_YOUR_KEY" \
  -d '{"linkedin_url": "https://linkedin.com/in/johndoe"}'
```

### 3. Check result (scraping is async, ~20-30 seconds)

```bash
curl https://api.scrapelinkedin.com/api/v1/scrape/PROFILE_ID \
  -H "X-API-Key: li_live_YOUR_KEY"
```

Response when complete:

```json
{
  "id": "507f1f77bcf86cd799439011",
  "linkedin_url": "https://linkedin.com/in/johndoe",
  "status": "completed",
  "profile_data": {
    "full_name": "John Doe",
    "experience": "Senior Engineer at Google (2020-present), Software Engineer at Meta (2017-2020)",
    "education": "MIT, BS Computer Science (2017)"
  }
}
```

## All Endpoints

### Scraping

| Method | Endpoint | Auth | Cost | Description |
|--------|----------|------|------|-------------|
| POST | `/api/v1/scrape` | X-API-Key | 1 credit | Scrape a single LinkedIn profile |
| POST | `/api/v1/scrape/batch` | X-API-Key | N credits | Scrape up to 1,000 profiles at once |
| GET | `/api/v1/scrape/{id}` | X-API-Key | Free | Check result by profile ID |
| GET | `/api/v1/scrape?linkedin_url=...` | X-API-Key | Free | Check result by LinkedIn URL |
| GET | `/api/v1/scrape/batch/{batch_id}` | X-API-Key | Free | Check batch progress and results |

### Authentication

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/api/v1/auth/register` | None | Create account (sends verification email) |
| POST | `/api/v1/auth/verify` | None | Verify email with 6-digit code |
| POST | `/api/v1/auth/api-key` | None | Generate API key (5 free credits) |

### Account & Credits

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/api/v1/account` | X-API-Key | View balance, usage, recent queries |
| DELETE | `/api/v1/account` | X-API-Key | Delete account |
| GET | `/api/v1/credits/packs` | None | List available credit packs |
| POST | `/api/v1/credits/purchase` | X-API-Key | Buy credits via Stripe Checkout |

### System

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/health` | None | Health check and service status |

## Pricing

- **$0.01 per successful lookup** — no tiers, no bulk discounts
- Failed lookups are free (credit automatically refunded)
- Cached results (within 24 hours) are free
- GET requests are always free
- 5 free credits on signup

### Credit Packs

| Pack | Credits | Price |
|------|---------|-------|
| 100 | 100 lookups | $1.00 |
| 1,000 | 1,000 lookups | $10.00 |
| 10,000 | 10,000 lookups | $100.00 |

## Authentication

All scraping and account endpoints require an API key passed as an HTTP header:

```
X-API-Key: li_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ...
```

Keys are hashed with SHA-256 before storage. If you lose your key, call `/auth/api-key` again to generate a new one (credits transfer automatically).

## Rate Limits

- 10 POST requests per minute per API key
- 5,000 lookups per day per API key
- GET requests are not rate-limited

## Batch Processing

Send up to 1,000 LinkedIn URLs in one request. Optionally provide a `callback_url` to receive results via webhook when the batch completes.

```bash
curl -X POST https://api.scrapelinkedin.com/api/v1/scrape/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: li_live_YOUR_KEY" \
  -d '{
    "linkedin_urls": [
      "https://linkedin.com/in/person1",
      "https://linkedin.com/in/person2"
    ],
    "callback_url": "https://your-server.com/webhook"
  }'
```

## Error Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created (scrape submitted) |
| 400 | Bad request (invalid URL, missing fields) |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits |
| 404 | Profile or batch not found |
| 413 | Request too large (max 1 MB) |
| 422 | Invalid LinkedIn URL format |
| 429 | Rate limit exceeded |