{"openapi": "3.0.0", "info": {"title": "LinkedIn Data API", "version": "1.0.0", "description": "Credit-metered LinkedIn data API served from our dataset (read-only, no live scraping in v1).\n\n**Authentication:** `Authorization: Bearer <api key>` \u2014 create keys under Account Settings \u2192 API Keys (`/account/settings/api-keys/`). The full key is shown exactly once at creation.\n\n**Billing:** every response (including errors) carries `credits_used` and `credits_remaining`. `person/search` and `company/employees` bill per profile returned; `company/enrich` bills per matched company (a miss is a free 404); `person/count` and `account` are free. Errors are never charged. The standard rate is 1 credit per result, but pricing is per plan \u2014 your exact per-endpoint costs are in `GET /v1/account` under `costs`.\n\n**Rate limits are plan-based** (per-minute and per-day, read them from the `X-RateLimit-*` response headers). Exceeding them returns 429 with `Retry-After`."}, "servers": [{"url": "/", "description": "This site (test: test.webautomation.io)"}], "tags": [{"name": "LinkedIn Data API (v1)", "description": "Credit-metered LinkedIn data API served from our dataset (read-only, no live scraping in v1).\n\n**Authentication:** `Authorization: Bearer <api key>` \u2014 create keys under Account Settings \u2192 API Keys (`/account/settings/api-keys/`). The full key is shown exactly once at creation.\n\n**Billing:** every response (including errors) carries `credits_used` and `credits_remaining`. `person/search` and `company/employees` bill per profile returned; `company/enrich` bills per matched company (a miss is a free 404); `person/count` and `account` are free. Errors are never charged. The standard rate is 1 credit per result, but pricing is per plan \u2014 your exact per-endpoint costs are in `GET /v1/account` under `costs`.\n\n**Rate limits are plan-based** (per-minute and per-day, read them from the `X-RateLimit-*` response headers). Exceeding them returns 429 with `Retry-After`."}], "paths": {"/v1/account": {"get": {"tags": ["LinkedIn Data API (v1)"], "summary": "Account \u2014 balance, plan, usage, limits (free)", "description": "Free. Returns plan, credits remaining, today's usage, your plan's rate limits, and the calling key's metadata. Exercises the whole auth/billing chain \u2014 good first call.", "operationId": "v1_account", "responses": {"200": {"description": "Account snapshot.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": true, "detail": [], "result": {"plan": "Starter", "credits_remaining": 4880, "usage_today": {"requests": 12, "credits": 6}, "rate_limits": {"per_minute": 10, "per_day": 1000}, "key": {"prefix": "wa_test_AbCdEfGh", "created": "2026-08-17"}, "costs": {"person_search": 1, "company_employees": 1, "company_enrich": 1}}, "credits_used": 0, "credits_remaining": 4880}}}}, "401": {"description": "Missing or invalid API key (revoked keys fail within ~5 minutes).", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Invalid or missing API key"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "429": {"description": "Rate limit exceeded for your plan. Retry after the window resets.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}, "Retry-After": {"description": "Seconds until the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Rate limit exceeded"], "result": null, "credits_used": 0, "credits_remaining": 118}}}}}, "security": [{"V1BearerAuth": []}]}}, "/v1/person/count": {"post": {"tags": ["LinkedIn Data API (v1)"], "summary": "Person count \u2014 segment size (free)", "description": "Free. Returns the total matching profiles for a filter set. Results cached ~5 minutes (cold queries can take 1\u20133s).", "operationId": "v1_person_count", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1PersonCountRequest"}, "example": {"filters": {"country": "united states", "department": "Sales"}}}}}, "responses": {"200": {"description": "Count.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": true, "detail": [], "result": {"total": 12686047}, "credits_used": 0, "credits_remaining": 4880}}}}, "401": {"description": "Missing or invalid API key (revoked keys fail within ~5 minutes).", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Invalid or missing API key"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "422": {"description": "Unknown filter key \u2014 lists all valid filters.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Unknown filter(s): countryy. Valid filters: city, company_linkedin_url, ..."], "result": null, "credits_used": 0, "credits_remaining": 4880}}}}, "429": {"description": "Rate limit exceeded for your plan. Retry after the window resets.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}, "Retry-After": {"description": "Seconds until the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Rate limit exceeded"], "result": null, "credits_used": 0, "credits_remaining": 118}}}}}, "security": [{"V1BearerAuth": []}]}}, "/v1/person/search": {"post": {"tags": ["LinkedIn Data API (v1)"], "summary": "Person search \u2014 billed per profile returned", "description": "Filterable segment search over the people dataset. Billed per profile actually returned (pre-authorised at `per_page`, difference refunded). Profiles include name/title/location, decoded experience & education, departments.", "operationId": "v1_person_search", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1PersonSearchRequest"}, "example": {"filters": {"country": "united states", "department": "Sales", "title_prefix": "director"}, "page": 1, "per_page": 3}}}}, "responses": {"200": {"description": "Profiles page; credits_used equals profiles returned.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": true, "detail": [], "result": {"total": 481022, "page": 1, "per_page": 3, "profiles": [{"name": "Jane Doe", "title": "Director of Sales", "location": "Austin, Texas, United States", "departments": ["Sales"], "experience": ["..."], "education": ["..."]}]}, "credits_used": 3, "credits_remaining": 4877}}}}, "401": {"description": "Missing or invalid API key (revoked keys fail within ~5 minutes).", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Invalid or missing API key"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "402": {"description": "Insufficient credits \u2014 rejected before any work runs; nothing is charged.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Insufficient credits"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "422": {"description": "Unknown filter key \u2014 lists all valid filters.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Unknown filter(s): dept. Valid filters: city, company_linkedin_url, department, ..."], "result": null, "credits_used": 0, "credits_remaining": 4877}}}}, "429": {"description": "Rate limit exceeded for your plan. Retry after the window resets.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}, "Retry-After": {"description": "Seconds until the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Rate limit exceeded"], "result": null, "credits_used": 0, "credits_remaining": 118}}}}}, "security": [{"V1BearerAuth": []}]}}, "/v1/company/enrich": {"get": {"tags": ["LinkedIn Data API (v1)"], "summary": "Company enrich \u2014 billed per match (a miss is free)", "description": "Company profile by LinkedIn URL, website domain, or name (provide at least one; URL beats domain beats name). Match ladder returns `match_confidence`: `exact_url`, `exact_domain`, or `name_match`. A miss is a free 404.", "operationId": "v1_company_enrich", "parameters": [{"name": "linkedin_url", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company LinkedIn URL or slug, e.g. https://www.linkedin.com/company/stripe or just `stripe`"}, {"name": "domain", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company website domain, e.g. stripe.com"}, {"name": "name", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company name (ranked best-match when URL/domain not given)"}], "responses": {"200": {"description": "Matched company profile.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": true, "detail": [], "result": {"match_confidence": "exact_domain", "company": {"name": "Stripe", "linkedin_url": "https://www.linkedin.com/company/stripe", "domain": "stripe.com", "industry": "Financial Services", "estimated_num_employees": 8000, "founded_year": 2010, "hq": "San Francisco, CA"}}, "credits_used": 1, "credits_remaining": 4876}}}}, "401": {"description": "Missing or invalid API key (revoked keys fail within ~5 minutes).", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Invalid or missing API key"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "402": {"description": "Insufficient credits \u2014 rejected before any work runs; nothing is charged.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Insufficient credits"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "404": {"description": "No match \u2014 free, nothing charged.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["No matching company found"], "result": null, "credits_used": 0, "credits_remaining": 4876}}}}, "429": {"description": "Rate limit exceeded for your plan. Retry after the window resets.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}, "Retry-After": {"description": "Seconds until the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Rate limit exceeded"], "result": null, "credits_used": 0, "credits_remaining": 118}}}}}, "security": [{"V1BearerAuth": []}]}}, "/v1/company/employees": {"get": {"tags": ["LinkedIn Data API (v1)"], "summary": "Company employees \u2014 billed per profile returned", "description": "Paginated employee list for a company (resolve the company the same way as enrich). Optional `title` narrows results. Billed per profile returned.", "operationId": "v1_company_employees", "parameters": [{"name": "linkedin_url", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company LinkedIn URL or slug, e.g. https://www.linkedin.com/company/stripe or just `stripe`"}, {"name": "domain", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company website domain, e.g. stripe.com"}, {"name": "name", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Company name (ranked best-match when URL/domain not given)"}, {"name": "title", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter employees by title"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "default": 1}}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "default": 25}}], "responses": {"200": {"description": "Employee page; credits_used equals profiles returned.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": true, "detail": [], "result": {"company": "https://www.linkedin.com/company/google", "total": 269517, "page": 1, "per_page": 3, "profiles": [{"name": "John Smith", "title": "Software Engineer"}]}, "credits_used": 3, "credits_remaining": 4873}}}}, "401": {"description": "Missing or invalid API key (revoked keys fail within ~5 minutes).", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Invalid or missing API key"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "402": {"description": "Insufficient credits \u2014 rejected before any work runs; nothing is charged.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Insufficient credits"], "result": null, "credits_used": 0, "credits_remaining": 0}}}}, "404": {"description": "Company not found \u2014 free.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["No matching company found"], "result": null, "credits_used": 0, "credits_remaining": 4873}}}}, "429": {"description": "Rate limit exceeded for your plan. Retry after the window resets.", "headers": {"X-RateLimit-Limit": {"description": "Your plan's per-minute request limit", "schema": {"type": "integer"}}, "X-RateLimit-Remaining": {"description": "Requests remaining in the current window", "schema": {"type": "integer"}}, "X-RateLimit-Reset": {"description": "Unix timestamp when the window resets", "schema": {"type": "integer"}}, "Retry-After": {"description": "Seconds until the window resets", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1Envelope"}, "example": {"status": false, "detail": ["Rate limit exceeded"], "result": null, "credits_used": 0, "credits_remaining": 118}}}}}, "security": [{"V1BearerAuth": []}]}}}, "components": {"securitySchemes": {"V1BearerAuth": {"type": "http", "scheme": "bearer", "description": "API key from Account Settings \u2192 API Keys. Keys are prefixed wa_test_/wa_live_; the full key is shown once at creation."}}, "schemas": {"V1Envelope": {"type": "object", "required": ["status", "detail"], "properties": {"status": {"type": "boolean", "description": "true on success"}, "detail": {"type": "array", "items": {}, "description": "Human-readable messages (errors or notes)"}, "result": {"description": "Endpoint-specific payload; null on errors"}, "credits_used": {"type": "integer", "description": "Credits charged by this call"}, "credits_remaining": {"type": "integer", "description": "Credits left on the account after this call"}}}, "V1PersonSearchRequest": {"type": "object", "properties": {"filters": {"type": "object", "description": "Filter object. Valid keys \u2014 exact match: `country`, `state`, `city`, `location`, `title`, `seniority`, `seniority_level`, `functional_area`, `industry`, `first_name`, `last_name`, `name`, `linkedin_url`. Prefix match: `title_prefix`, `headline_prefix`, `location_prefix`, `name_prefix`, `industry_prefix`. Numeric ranges: `connections_min`, `connections_max`, `followers_min`, `followers_max`. Special: `company_linkedin_url` (company URL/slug), `department` (case-insensitive, one of: Administrative, C-Suite, Consulting, Customer Service, Design, Education, Engineering and Technical, Finance & Accounting, Human Resources, Legal, Marketing, Medical, Operations, Other, Product, Project Management, Real Estate, Research, Sales, Trades). Values may be a string or an array of strings (OR semantics). An unknown key returns 422 listing the valid filters. Matching is exact or prefix only \u2014 no substring search in v1.", "default": {}}, "page": {"type": "integer", "default": 1, "minimum": 1}, "per_page": {"type": "integer", "default": 25, "description": "Profiles per page \u2014 you are billed per profile returned"}, "sort": {"type": "string", "default": "recent", "description": "`recent` (default) or `relevance`.", "enum": ["recent", "relevance"]}}}, "V1PersonCountRequest": {"type": "object", "properties": {"filters": {"type": "object", "description": "Filter object. Valid keys \u2014 exact match: `country`, `state`, `city`, `location`, `title`, `seniority`, `seniority_level`, `functional_area`, `industry`, `first_name`, `last_name`, `name`, `linkedin_url`. Prefix match: `title_prefix`, `headline_prefix`, `location_prefix`, `name_prefix`, `industry_prefix`. Numeric ranges: `connections_min`, `connections_max`, `followers_min`, `followers_max`. Special: `company_linkedin_url` (company URL/slug), `department` (case-insensitive, one of: Administrative, C-Suite, Consulting, Customer Service, Design, Education, Engineering and Technical, Finance & Accounting, Human Resources, Legal, Marketing, Medical, Operations, Other, Product, Project Management, Real Estate, Research, Sales, Trades). Values may be a string or an array of strings (OR semantics). An unknown key returns 422 listing the valid filters. Matching is exact or prefix only \u2014 no substring search in v1.", "default": {}}}}}}}