{ "openapi": "3.0.3", "info": { "title": "DataMagnet API", "version": "1.0.0", "description": "API for extracting LinkedIn data, ICP Search and monitoring signals. All endpoints require a Bearer API key and consume credits per request." }, "servers": [ { "url": "https://api.datamagnet.co/api/v1", "description": "Production server" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "LinkedIn", "description": "LinkedIn person and company data extraction" }, { "name": "Posts", "description": "LinkedIn post details, reactions, and reposts" }, { "name": "Search", "description": "LinkedIn people and Sales Navigator search" }, { "name": "ICP Search", "description": "LinkedIn DataMagnet ICP Search — find your ideal customer profiles with powerful filters" } ], "paths": { "/person": { "post": { "tags": [ "LinkedIn" ], "summary": "Get LinkedIn person profile", "description": "Extract profile information from a LinkedIn person URL.", "operationId": "Person Profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn profile URL", "example": "https://www.linkedin.com/in/satyanadella/" } } } } } }, "responses": { "200": { "description": "Person profile data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "Person profile fields", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "headline": { "type": "string" }, "summary": { "type": "string" }, "location": { "type": "string" }, "profile_url": { "type": "string" }, "profile_image_url": { "type": "string" }, "current_company": { "type": "string" }, "current_title": { "type": "string" }, "experience": { "type": "array", "items": { "type": "object" } }, "education": { "type": "array", "items": { "type": "object" } }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Only present when skills=yes" } } }, "credit_used": { "type": "integer", "description": "Credits consumed (1–3 depending on options)", "example": 1 }, "status": { "type": "string", "example": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/person/activity": { "post": { "tags": [ "LinkedIn" ], "summary": "Get LinkedIn person activity", "description": "Retrieve activity data (posts, comments, likes, or articles) for a LinkedIn profile.", "operationId": "Person Recent Activity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn profile URL", "example": "https://www.linkedin.com/in/satyanadella/" }, "type": { "type": "string", "description": "Activity type to retrieve", "enum": [ "posts", "comments", "likes" ], "default": "posts" } } } } } }, "responses": { "200": { "description": "Activity data for the profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "Activity items array and metadata" }, "credit_used": { "type": "integer", "example": 5 }, "status": { "type": "string", "example": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/company": { "post": { "tags": [ "LinkedIn" ], "summary": "Get LinkedIn company profile", "description": "Extract company information from a LinkedIn company URL or company website URL. Costs 1 credit.", "operationId": "Company Profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn company URL or company website URL", "example": "https://www.linkedin.com/company/microsoft/" } } } } } }, "responses": { "200": { "description": "Company profile data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "Company profile fields", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "company_size": { "type": "string" }, "headquarters": { "type": "string" }, "founded": { "type": "string" }, "specialities": { "type": "array", "items": { "type": "string" } }, "linkedin_url": { "type": "string" }, "logo_url": { "type": "string" }, "follower_count": { "type": "integer" } } }, "credit_used": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/company/posts": { "post": { "tags": [ "LinkedIn" ], "summary": "Get posts from a LinkedIn company page", "description": "Retrieve posts published by a LinkedIn company page.", "operationId": "Company Recent Posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn company URL", "example": "https://www.linkedin.com/company/microsoft/" } } } } } }, "responses": { "200": { "description": "Company posts data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "Posts array and metadata" }, "credit_used": { "type": "integer", "example": 5 }, "status": { "type": "string", "example": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/post": { "post": { "tags": [ "Posts" ], "summary": "Get LinkedIn post details", "description": "Fetch details of a single LinkedIn post by URL. Costs 1 credit.", "operationId": "Post Details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn post URL", "example": "https://www.linkedin.com/posts/satyanadella_activity-7123456789012345678-abcd/" } } } } } }, "responses": { "200": { "description": "Post detail data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "Post detail fields (snake_case)", "properties": { "text": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "object" }, "num_likes": { "type": "integer" }, "num_comments": { "type": "integer" }, "num_reposts": { "type": "integer" }, "posted_at": { "type": "string" }, "post_url": { "type": "string" }, "media": { "type": "object" } } }, "credit_used": { "type": "integer", "example": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/post/reactions": { "post": { "tags": [ "Posts" ], "summary": "Get reactions for a LinkedIn post", "description": "Fetch paginated reactions for a LinkedIn post.", "operationId": "Post Reactions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn post URL", "example": "https://www.linkedin.com/posts/satyanadella_activity-7123456789012345678-abcd/" }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Paginated list of reactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "reactions": { "type": "array", "items": { "type": "object", "properties": { "reaction_type": { "type": "string" }, "reactor": { "type": "object" } } } }, "total": { "type": "integer", "description": "Total number of reactions" } } }, "cursor": { "type": "integer", "nullable": true, "description": "Next page number, or null if no more pages" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/post/comments": { "post": { "tags": [ "Posts" ], "summary": "Get comments for a LinkedIn post", "description": "Fetch paginated comments for a LinkedIn post.", "operationId": "Post Comments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn post URL", "example": "https://www.linkedin.com/posts/satyanadella_activity-7123456789012345678-abcd/" }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Paginated list of comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "reaction_type": { "type": "string" }, "reactor": { "type": "object" } } } }, "total": { "type": "integer", "description": "Total number of reactions" } } }, "cursor": { "type": "integer", "nullable": true, "description": "Next page number, or null if no more pages" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/post/reposts": { "post": { "tags": [ "Posts" ], "summary": "Get reposts for a LinkedIn post", "description": "Fetch paginated reposts for a LinkedIn post.", "operationId": "Post Reposts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "LinkedIn post URL", "example": "https://www.linkedin.com/posts/satyanadella_activity-7123456789012345678-abcd/" }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Paginated list of reposts", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "reposts": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "description": "Total number of reposts" } } }, "cursor": { "type": "integer", "nullable": true, "description": "Next page number, or null if no more pages" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" } } } }, "/people/search": { "post": { "tags": [ "Search" ], "summary": "Search LinkedIn people", "description": "Search for LinkedIn people using keyword and filter parameters.", "operationId": "Search People", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "description": "General search keyword", "example": "software engineer" }, "page": { "type": "integer", "description": "Page number for pagination. Each page contains up to 50 results.", "default": 1, "minimum": 1 }, "title_free_text": { "type": "string", "description": "Filter by job title", "example": "CTO" }, "company_free_text": { "type": "string", "description": "Filter by company name", "example": "Microsoft" }, "company_linkedin_url": { "type": "string", "description": "Filter by the person's current company using its LinkedIn URL. Resolved to the company's LinkedIn ID automatically; returns 400 if the URL cannot be resolved.", "example": "https://www.linkedin.com/company/google/" }, "first_name": { "type": "string", "description": "Filter by first name", "example": "John" }, "last_name": { "type": "string", "description": "Filter by last name", "example": "Smith" } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "description": "Search results and pagination info", "properties": { "people": { "type": "array", "description": "List of matching people", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "Raphaël Marinier" }, "first_name": { "type": "string", "nullable": true, "example": "Raphaël" }, "last_name": { "type": "string", "nullable": true, "example": "Marinier" }, "headline": { "type": "string", "example": "Software Engineer chez Google" }, "location": { "type": "string", "example": "Greater Paris Metropolitan Region" }, "url": { "type": "string", "example": "https://www.linkedin.com/in/rapha%C3%ABl-marinier-6a14621a0" }, "urn": { "type": "string", "example": "ACoAAC8Np1kB17Ro_b3eo8YZWUZFudbt9lrg1Tw" }, "profile_image_url": { "type": "string" } } } }, "total": { "type": "integer", "description": "Total number of results matching the search", "example": 1000 }, "start": { "type": "integer", "description": "Zero-based offset of the first result on this page", "example": 0 }, "count": { "type": "integer", "description": "Number of results returned on this page (up to 50)", "example": 50 }, "has_more": { "type": "boolean", "description": "Whether more results are available on the next page", "example": true } } }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/salesnavigator/search": { "post": { "tags": [ "Search" ], "summary": "Search LinkedIn Sales Navigator", "description": "Search for leads using a LinkedIn Sales Navigator search URL.", "operationId": "People Search Sales Navigator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "search_url" ], "properties": { "search_url": { "type": "string", "description": "LinkedIn Sales Navigator search URL", "example": "https://www.linkedin.com/sales/search/people?query=..." }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Sales Navigator search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "description": "Search results in snake_case" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/company/search": { "post": { "tags": [ "Search" ], "summary": "Search LinkedIn companies", "description": "Search for LinkedIn companies using keyword and filter parameters.", "operationId": "Search Company", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "description": "General search keyword", "example": "kakiyo" }, "company_sizes": { "type": "array", "items": { "type": "string" }, "description": "Filter by company size. Accepted values: B (1-10), C (11-50), D (51-200), E (201-500), F (501-1000), G (1001-5000), H (5001-10,000), I (10,000+)", "example": [ "C", "D" ] }, "has_jobs": { "type": "boolean", "description": "Filter to companies that are actively hiring", "example": true }, "industries": { "type": "array", "items": { "type": "integer" }, "description": "Filter by industry IDs. Example: 1810 for Professional Services, 96 for IT Services and IT Consulting", "example": [ 1810, 96 ] }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Company search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "description": "Search results" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/post/search": { "post": { "tags": [ "Search" ], "summary": "Search LinkedIn posts", "description": "Search for LinkedIn posts using keyword and filter parameters.", "operationId": "Search Post", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "description": "General search keyword", "example": "microsoft" }, "sort_by": { "type": "string", "description": "Sort order for results", "enum": [ "date_posted", "relevance" ], "example": "date_posted" }, "date_posted": { "type": "string", "description": "Filter by date posted", "enum": [ "past-24h", "past-week", "past-month" ], "example": "past-week" }, "content_type": { "type": "string", "description": "Filter by content type. Accepted values: photos (Images), videos (Videos), jobs (Jobs), liveVideos (LinkedIn Live Videos), documents (Documents)", "enum": [ "photos", "videos", "jobs", "liveVideos", "documents" ], "example": "videos" }, "author_title": { "type": "string", "description": "Filter by the author's job title", "example": "CTO" }, "mentions_organization": { "type": "array", "description": "Return only posts that mention the given LinkedIn companies. Array of LinkedIn company ids. A comma-separated string is also accepted.", "items": { "type": "string" }, "example": [ "1035", "1441" ] }, "page": { "type": "integer", "description": "Page number for pagination", "default": 1, "minimum": 1 } } } } } }, "responses": { "200": { "description": "Post search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "description": "Search results" }, "credit_used": { "type": "integer", "example": 5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/people-search/filters": { "get": { "tags": [ "ICP Search" ], "summary": "Get all filter options", "description": "Returns all valid filter values for the DataMagnet ICP Search endpoints. Use this to populate dropdowns.", "operationId": "All Filters", "responses": { "200": { "description": "All filter options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "filters": { "type": "object", "properties": { "seniority": { "type": "array", "items": { "type": "string" } }, "company_headcount": { "type": "array", "items": { "type": "string" } }, "company_type": { "type": "array", "items": { "type": "string" } }, "followers_count": { "type": "array", "items": { "type": "string" } }, "recent_activities": { "type": "array", "items": { "type": "string" } }, "job_opportunities": { "type": "array", "items": { "type": "string" } }, "years_in_position": { "type": "array", "items": { "type": "string" } }, "function": { "type": "array", "items": { "type": "string" } }, "profile_language": { "type": "array", "items": { "type": "string" } }, "fortune_rank": { "type": "array", "items": { "type": "string" } }, "annual_revenue": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "type": "string" } }, "snap_values_millions": { "type": "array", "items": { "type": "number" } } } }, "industry": { "type": "array", "items": { "type": "string" } }, "dynamic_fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "description": { "type": "string" }, "multi": { "type": "boolean" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/people-search/search": { "post": { "tags": [ "ICP Search" ], "summary": "DataMagnet ICP people search", "description": "Search for people using powerful ICP filters. All filter values are human-readable strings — no IDs required.", "operationId": "ICP People Search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1, "minimum": 1 }, "job_title": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "CTO" }, "company_name": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Stripe" }, "location": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "San Francisco" }, "seniority": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "CXO", "Vice President" ] }, "company_headcount": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "501-1,000", "1,001-5,000" ] }, "industry": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Software Development" }, "company_type": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Public" }, "school": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "MIT" }, "technology": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Salesforce" }, "function": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Engineering" }, "years_in_position": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "1 to 2 years" }, "followers_count": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "51-100" }, "recent_activities": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Funding" }, "job_opportunities": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Hiring" }, "profile_language": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "English" }, "fortune_rank": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Fortune 50" }, "annual_revenue": { "type": "object", "properties": { "min": { "type": "number", "example": 10 }, "max": { "type": "number", "example": 500 }, "currency": { "type": "string", "default": "USD" } } } } }, "example": { "job_title": "CTO", "company_name": "Stripe", "seniority": [ "CXO", "Vice President" ], "location": "San Francisco", "company_headcount": [ "501-1,000", "1,001-5,000" ], "industry": "Software Development", "page": 1 } } } }, "responses": { "200": { "description": "People search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "location": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "tenure_years": { "type": "integer", "nullable": true }, "tenure_months": { "type": "integer", "nullable": true }, "summary": { "type": "string", "nullable": true }, "profile_url": { "type": "string" }, "profile_picture": { "type": "string", "nullable": true }, "open_link": { "type": "boolean" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "total": { "type": "integer" }, "count": { "type": "integer" }, "start": { "type": "integer" } } }, "filters_applied": { "type": "integer" }, "filter_errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "422": { "description": "No valid filters could be built", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Search service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/people-search/search/company": { "post": { "tags": [ "ICP Search" ], "summary": "DataMagnet ICP company search", "description": "Search for companies using powerful ICP filters. All filter values are human-readable strings.", "operationId": "ICP Company Search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 }, "industry": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Software Development" }, "location": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "San Francisco" }, "company_headcount": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "501-1,000", "1,001-5,000" ] }, "company_type": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Public" }, "followers_count": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "51-100" }, "recent_activities": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Funding" }, "job_opportunities": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Hiring" }, "fortune_rank": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Fortune 50" }, "technology": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Salesforce" }, "annual_revenue": { "type": "object", "properties": { "min": { "type": "number", "example": 500 }, "max": { "type": "number", "example": 1000 } } } } }, "example": { "industry": "Software Development", "location": "San Francisco", "company_headcount": [ "501-1,000", "1,001-5,000" ], "annual_revenue": { "min": 500, "max": 1000 }, "page": 1 } } } }, "responses": { "200": { "description": "Company search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string" }, "company_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "employee_count_range": { "type": "string", "nullable": true }, "employee_count": { "type": "integer", "nullable": true }, "company_url": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "revenue_min": { "type": "number", "nullable": true }, "revenue_max": { "type": "number", "nullable": true }, "revenue_currency": { "type": "string", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "total": { "type": "integer" }, "count": { "type": "integer" }, "start": { "type": "integer" } } }, "filters_applied": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "422": { "description": "One or more filters failed to resolve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Search service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Pass your API key as a Bearer token: `Authorization: Bearer `" } }, "schemas": { "SignalObject": { "type": "object", "properties": { "signal_type": { "type": "string", "enum": [ "job_change", "new_post" ] }, "status": { "type": "string", "example": "active" }, "profile_urls": { "type": "array", "items": { "type": "string" } }, "email_recipients": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string", "nullable": true } } }, "ErrorResponse": { "type": "object", "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "credit_used": { "type": "integer", "example": 0 } } } }, "responses": { "BadRequest": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "url parameter is required.", "credit_used": 0 } } } }, "Unauthorized": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Unauthorized" } } } }, "InsufficientCredits": { "description": "Payment required — insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Insufficient credits" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "No signal found for signal_type 'job_change'" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Error in Request please try after some time." } } } } } } }