{ "openapi": "3.1.0", "info": { "title": "Clado Search & Enrichment API", "description": "API for searching LinkedIn profiles and enriching contact information", "version": "1.0.0" }, "servers": [ { "url": "https://search.clado.ai", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/search": { "get": { "summary": "Search People", "description": "Search for users with pagination support. Returns a search_id for continuing searches with offset. Costs 5 credits per request (standard) or 1 credit per result (with advanced_filtering). Rate limits vary by tier: 5/min (free), 20/min (Tier 1), 200/min (Tier 2), 400/min (Tier 3).", "operationId": "searchPeople", "tags": [ "Search" ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Natural language search query to find LinkedIn profiles (e.g., 'software engineers at tech companies', 'product managers with MBA'). Required for new searches, optional when using search_id for continuation", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of profiles to return in the response (1-100)", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } }, { "name": "companies", "in": "query", "required": false, "description": "List of company names to filter results by", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "schools", "in": "query", "required": false, "description": "List of school names to filter results by", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "advanced_filtering", "in": "query", "required": false, "description": "Enable AI agent-based filtering to improve result quality. When enabled, an AI agent reviews all results before returning them, which may return fewer results than the requested limit but with higher relevance and quality", "schema": { "type": "boolean", "default": true } }, { "name": "search_id", "in": "query", "required": false, "description": "ID from a previous search to continue pagination. When provided, uses the same search criteria and query from the original search", "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination. Used with search_id to get subsequent pages of results", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "legacy", "in": "query", "required": false, "description": "DEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSearchResponse" } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Limit is invalid" } } } }, "401": { "description": "Unauthorized - invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid or expired API key" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Internal server error: Query execution failed" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Search service temporarily unavailable" } } } } } } }, "/api/search/deep_research": { "post": { "summary": "Initiate Deep Research", "description": "Start deep research job. Each profile costs 1 credit. Rate limits vary by tier: 2/min (free), 5/min (Tier 1), 50/min (Tier 2), 100/min (Tier 3).", "operationId": "initiateDeepResearch", "tags": [ "Deep Research" ], "requestBody": { "required": true, "description": "Deep research parameters including search query and optional settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchRequest" } } } }, "responses": { "200": { "description": "Job initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchJobResponse" } } } } } } }, "/api/search/deep_research/{job_id}/cancel": { "post": { "summary": "Cancel Deep Research Job", "operationId": "cancelDeepResearchJob", "tags": [ "Deep Research" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Unique identifier for the deep research job to cancel", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResponse" } } } } } } }, "/api/search/deep_research/{job_id}": { "get": { "summary": "Get Deep Research Status", "description": "Get the status and results of a deep research job with optional pagination. If page parameter is not provided, returns all results without pagination.", "operationId": "getDeepResearchStatus", "tags": [ "Deep Research" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Unique identifier for the deep research job (returned from POST /api/search/deep_research)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-indexed). If not provided, returns all results without pagination", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page when pagination is used. Only applies when page parameter is provided", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "legacy", "in": "query", "required": false, "description": "DEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Job status and results (paginated if page parameter is provided)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchStatusResponse" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Page number must be >= 1" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Not authorized to access this job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - Job not found in Redis or Supabase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/search/deep_research/{job_id}/more": { "post": { "summary": "Continue Deep Research", "operationId": "continueDeepResearch", "tags": [ "Deep Research" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Unique identifier for the deep research job to continue", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMoreRequest" } } } }, "responses": { "200": { "description": "Continuation initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchJobResponse" } } } } } } }, "/api/enrich/contacts": { "get": { "summary": "Get Contact Information", "description": "Get contact info for a profile by LinkedIn URL, email, or phone. Exactly one of these parameters must be provided. Costs 4 credits for email enrichment, 10 credits for phone enrichment, 14 credits if both are requested and found, or 4 credits for all contact info (default). When both email_enrichment and phone_enrichment are true, the system will attempt to find both but only charge for what's actually found. Rate limits vary by tier: 0/min (free), 5/min (Tier 1), 60/min (Tier 2), 120/min (Tier 3). Note: Free tier cannot access this endpoint.", "operationId": "getContacts", "tags": [ "Enrichment" ], "parameters": [ { "name": "linkedin_url", "in": "query", "required": false, "description": "LinkedIn profile URL to get contact information for (e.g., 'https://www.linkedin.com/in/username')", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Email address to find profile and get contact information (e.g., 'john.doe@example.com')", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "description": "Phone number to find profile and get contact information (e.g., '+1234567890')", "schema": { "type": "string" } }, { "name": "email_enrichment", "in": "query", "required": false, "description": "If true, returns emails (costs 4 credits if email found). Can be combined with phone_enrichment to request both", "schema": { "type": "boolean", "default": false } }, { "name": "phone_enrichment", "in": "query", "required": false, "description": "If true, returns phone numbers (costs 10 credits if phone found). Can be combined with email_enrichment to request both", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Contact info retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "400": { "description": "Bad Request - Must provide exactly one of: LinkedIn URL, email, or phone" }, "401": { "description": "Unauthorized - API key missing or invalid" }, "402": { "description": "Payment Required - Insufficient credits or requires paid plan (paid users only)" }, "500": { "description": "Internal Server Error - Enrichment service error" } } } }, "/api/enrich/scrape": { "get": { "summary": "Scrape LinkedIn Profile", "description": "Scrape profile data. Costs 2 credits. Rate limits vary by tier: 5/min (free), 15/min (Tier 1), 150/min (Tier 2), 300/min (Tier 3).", "operationId": "scrapeLinkedInProfile", "tags": [ "Enrichment" ], "parameters": [ { "name": "linkedin_url", "in": "query", "required": true, "description": "LinkedIn profile URL to scrape for detailed information (e.g., 'https://www.linkedin.com/in/username')", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile scraped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } } } } } }, "/api/enrich/linkedin": { "get": { "summary": "Get LinkedIn Profile from Database", "description": "Get profile from database. Costs 1 credit. Rate limits vary by tier: 5/min (free), 20/min (Tier 1), 100/min (Tier 2), 200/min (Tier 3).", "operationId": "getLinkedInProfile", "tags": [ "Enrichment" ], "parameters": [ { "name": "linkedin_url", "in": "query", "required": true, "description": "LinkedIn profile URL to retrieve from database (e.g., 'https://www.linkedin.com/in/username')", "schema": { "type": "string" } }, { "name": "legacy", "in": "query", "required": false, "description": "DEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Profile retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedInProfileResponse" } } } } } } }, "/api/enrich/post-reactions": { "get": { "summary": "Get LinkedIn Post Reactions", "description": "Get post reactions. Costs 1 credit. Rate limits vary by tier: 5/min (free), 15/min (Tier 1), 150/min (Tier 2), 300/min (Tier 3).", "operationId": "getPostReactions", "tags": [ "Enrichment" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "LinkedIn post URL to analyze reactions for (e.g., 'https://www.linkedin.com/posts/username_activity-123456789')", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination of reaction results (default: 1)", "schema": { "type": "integer", "default": 1 } }, { "name": "reaction_type", "in": "query", "required": false, "description": "Filter reactions by type (like, love, celebrate, support, insightful, funny)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reactions retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostReactionsResponse" } } } } } } }, "/api/enrich/bulk-contacts": { "post": { "summary": "Bulk Contact Enrichment", "description": "Start bulk contact enrichment job for multiple LinkedIn profiles. Costs 4 credits per successful email found, 10 credits per successful phone found. When both email_enrichment and phone_enrichment are true, the system will attempt to find both but only charge for what's actually found. Max 5000 URLs per request. Rate limits vary by tier: 0/min (free), 2/min (Tier 1), 20/min (Tier 2), 40/min (Tier 3). Note: Free tier cannot access this endpoint.", "operationId": "bulkEnrichContacts", "tags": [ "Enrichment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEnrichRequest" } } } }, "responses": { "200": { "description": "Job initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEnrichJobResponse" } } } }, "400": { "description": "Bad Request - Invalid parameters or too many URLs" }, "401": { "description": "Unauthorized - API key missing or invalid" }, "402": { "description": "Payment Required - Contact enrichment requires paid account" } } } }, "/api/enrich/bulk-contacts/{job_id}": { "get": { "summary": "Get Bulk Enrichment Status", "description": "Get the status and results of a bulk enrichment job. This endpoint is free to call.", "operationId": "getBulkEnrichmentStatus", "tags": [ "Enrichment" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Unique identifier for the bulk enrichment job", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status and results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEnrichStatusResponse" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "404": { "description": "Not Found - Job not found or expired" } } } }, "/api/credits": { "get": { "summary": "Get Credits", "description": "Check remaining credits for your API key. This endpoint is free and returns your current credit balance.", "operationId": "getCredits", "tags": [ "Platform" ], "responses": { "200": { "description": "Credits information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "404": { "description": "Not Found - Unable to retrieve credit information" }, "500": { "description": "Internal Server Error - Credit service error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication. Keys start with 'lk_'." } }, "schemas": { "UserSearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserResult" }, "description": "Array of user profiles matching the search query" }, "total": { "type": "integer", "description": "Total number of profiles found" }, "query": { "type": "string", "description": "The search query that was executed" }, "search_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this search. Use this with offset parameter to paginate through results" } }, "example": { "results": [ { "profile": { "id": "3917303", "name": "Alex Johnson", "location": "San Francisco, California, United States", "location_country": "United States", "location_regions": [ "Americas", "Northern America", "AMER" ], "headline": "Senior Software Engineer at TechCorp Inc", "description": "Experienced software engineer specializing in machine learning and distributed systems", "linkedin_url": "https://www.linkedin.com/in/alexjohnson", "picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2", "connections_count": 500, "followers_count": 1200, "is_working": true, "is_decision_maker": false, "total_experience_duration_months": 48, "projected_total_salary": 150000.0, "post_count": 15, "posts": "Excited to share our latest ML research on distributed training optimization", "liked_posts": "Great insights on PyTorch optimization techniques", "recommendations": "Alex is an exceptional engineer with deep ML expertise", "recommendations_count": 8, "skills": [ "Python", "Machine Learning", "Software Engineering", "Data Science" ] }, "experience": [ { "title": "Senior Software Engineer", "company_name": "TechCorp Inc", "start_date": "2021-01-01T00:00:00", "end_date": "1970-01-01T00:00:00", "description": "Working on machine learning infrastructure and scalable systems", "location": "San Francisco, CA" } ], "education": [ { "degree": "Master of Science", "field_of_study": "Computer Science", "school_name": "State University", "start_date": "2017-09-01T00:00:00", "end_date": "2019-06-01T00:00:00" } ], "posts": [ { "text": "Excited to share our latest ML research on distributed training optimization", "totalReactionCount": 45, "likeCount": 38, "appreciationCount": 2, "empathyCount": 1, "InterestCount": 1, "praiseCount": 3, "commentsCount": 8, "repostsCount": 2, "postUrl": "https://www.linkedin.com/feed/update/urn:li:activity:7276799769082007552/", "postedAt": "2w", "postedDate": "2024-01-15 10:30:00.000 +0000 UTC", "postedDateTimestamp": 1705315800000, "reposted": false, "urn": "7276799769082007552", "author": { "firstName": "Alex", "lastName": "Johnson", "username": "alexjohnson", "url": "https://www.linkedin.com/in/alexjohnson" }, "image": [], "mentions": [], "companyMentions": [ { "id": 12345, "name": "TechCorp Inc", "publicIdentifier": "techcorp-inc", "url": "https://www.linkedin.com/company/techcorp-inc/" } ], "isBrandPartnership": false } ] } ], "total": 1, "query": "software engineers at tech companies", "search_id": "550e8400-e29b-41d4-a716-446655440000" } }, "UserResult": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/UserProfile" }, "experience": { "type": "array", "items": { "$ref": "#/components/schemas/Experience" }, "description": "Work experience history" }, "education": { "type": "array", "items": { "$ref": "#/components/schemas/Education" }, "description": "Educational background" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "Recent LinkedIn posts and activity" }, "awards": { "type": "array", "items": { "$ref": "#/components/schemas/Award" }, "description": "Awards and honors received" }, "certifications": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" }, "description": "Professional certifications" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "description": "Organizations and associations" }, "patents": { "type": "array", "items": { "$ref": "#/components/schemas/Patent" }, "description": "Patents filed or granted" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Professional projects" }, "publications": { "type": "array", "items": { "$ref": "#/components/schemas/Publication" }, "description": "Published works and articles" }, "github_repos": { "type": "array", "items": { "$ref": "#/components/schemas/GitHubRepo" }, "description": "GitHub repositories" } } }, "UserProfile": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the profile" }, "name": { "type": "string", "description": "Full name of the person" }, "location": { "type": "string", "description": "Geographic location" }, "location_country": { "type": "string", "description": "Country of location" }, "location_regions": { "type": "array", "items": { "type": "string" }, "description": "Geographic regions (e.g., Americas, Northern America, AMER)" }, "headline": { "type": "string", "description": "Professional headline or current position" }, "description": { "type": "string", "description": "About section or professional summary" }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL" }, "picture_permalink": { "type": "string", "description": "Profile picture URL" }, "connections_count": { "type": "integer", "description": "Number of LinkedIn connections" }, "followers_count": { "type": "integer", "description": "Number of LinkedIn followers" }, "is_working": { "type": "boolean", "description": "Whether the person is currently working" }, "is_decision_maker": { "type": "boolean", "description": "Whether the person is identified as a decision maker" }, "total_experience_duration_months": { "type": "integer", "description": "Total work experience in months" }, "projected_total_salary": { "type": "number", "description": "Estimated total salary" }, "post_count": { "type": "integer", "description": "Number of LinkedIn posts" }, "posts": { "type": "string", "description": "Recent posts content" }, "liked_posts": { "type": "string", "description": "Content of posts the user has liked" }, "recommendations": { "type": "string", "description": "LinkedIn recommendations" }, "recommendations_count": { "type": "integer", "description": "Number of recommendations" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Professional skills" } } }, "DeepResearchRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "Natural language search query for deep research (required if criteria and opensearch_query are not provided)" }, "limit": { "type": "integer", "default": 30, "description": "Maximum number of profiles to research" } } }, "DeepResearchJobResponse": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } }, "DeepResearchStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique job identifier" }, "status": { "type": "string", "description": "Job status (pending, searching, processing, completed, error, cancelled)" }, "message": { "type": "string", "description": "Status message" }, "created_at": { "type": "number", "description": "Unix timestamp of when the job was created" }, "opensearch_results": { "type": "integer", "description": "Number of results found in OpenSearch" }, "final_results_count": { "type": "integer", "description": "Total number of validated profiles across all pages" }, "total_filtered": { "type": "integer", "description": "Number of filtered results" }, "search_chunk_done": { "type": "integer", "description": "Number of search chunks processed" }, "search_chunk_total": { "type": "integer", "description": "Total number of search chunks" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserResult" }, "description": "Array of user profiles (paginated if page parameter is provided)" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo", "description": "Pagination information (only present when page parameter is provided)" }, "error": { "type": "string", "description": "Error details (only present when status is 'error')" } }, "example": { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "message": "Deep research completed successfully", "total_results": 47, "results": [ { "profile": { "id": "103901716", "name": "Alex Johnson", "location": "San Francisco, California, United States", "location_country": "United States", "location_regions": [ "Americas", "Northern America", "AMER" ], "headline": "Principal Engineer at TechCorp Inc", "description": "Machine Learning Engineer at TechCorp. Previously at StartupCo and InnovateTech. Expert in distributed systems and AI infrastructure.", "linkedin_url": "https://www.linkedin.com/in/alexjohnson", "picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2", "connections_count": 500, "followers_count": 9497, "is_working": true, "is_decision_maker": false, "total_experience_duration_months": 234, "projected_total_salary": 285000.0, "post_count": 12, "posts": "Excited to share our latest ML research on distributed training optimization. Working on next-gen AI infrastructure at TechCorp.", "liked_posts": "Three ways to create efficient ML pipelines. Here's a potential breakthrough in self-training AI systems. Excited about the future of distributed computing.", "recommendations": "Alex is an exceptional engineer with deep expertise in machine learning infrastructure. His work on distributed systems has been instrumental to our team's success.", "recommendations_count": 8, "skills": [ "Machine Learning", "Python", "Distributed Systems", "PyTorch", "Kubernetes", "AI Infrastructure" ] }, "experience": [ { "title": "Principal Engineer", "company_name": "TechCorp Inc", "start_date": "2022-03-01T00:00:00", "end_date": "1970-01-01T00:00:00", "description": "Leading ML infrastructure team, developing scalable AI systems for production deployment", "location": "San Francisco, CA" } ], "education": [ { "degree": "Master of Science", "field_of_study": "Computer Science", "school_name": "State University", "start_date": "2017-09-01T00:00:00", "end_date": "2019-06-01T00:00:00" } ], "posts": [ { "text": "Excited to share our latest ML research on distributed training optimization", "totalReactionCount": 156, "likeCount": 89, "appreciationCount": 23, "empathyCount": 18, "InterestCount": 12, "praiseCount": 10, "commentsCount": 24, "repostsCount": 8, "postUrl": "https://www.linkedin.com/posts/alexjohnson_ml-research-activity-7150123456789", "postedAt": "2 days ago", "postedDate": "2024-01-26T10:30:00Z", "postedDateTimestamp": 1706266200, "reposted": false, "urn": "urn:li:activity:7150123456789", "author": { "firstName": "Alex", "lastName": "Johnson", "username": "alexjohnson", "url": "https://www.linkedin.com/in/alexjohnson" }, "mentions": [], "companyMentions": [ { "id": 12345, "name": "TechCorp Inc", "publicIdentifier": "techcorp-inc", "url": "https://www.linkedin.com/company/techcorp-inc" } ], "isBrandPartnership": false } ] } ] } }, "CancelJobResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "SearchMoreRequest": { "type": "object", "properties": { "additional_limit": { "type": "integer", "default": 30, "description": "Additional number of profiles to find beyond current results" } } }, "EnrichResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactInfo" }, "description": "Array of contact information found" } }, "example": { "data": [ { "error": false, "contacts": [ { "type": "email", "value": "alex.johnson@techcorp.com", "rating": 100, "subType": "work" }, { "type": "phone", "value": "+1-555-123-4567", "rating": 90, "subType": "mobile" } ], "social": [ { "link": "https://www.linkedin.com/in/alexjohnson", "type": "li", "rating": 100 } ] } ] } }, "ScrapeResponse": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Full name" }, "headline": { "type": "string", "description": "Professional headline" }, "summary": { "type": "string", "description": "Profile summary" }, "location": { "type": "string", "description": "Location" }, "title": { "type": "string", "description": "Current title" }, "linkedin_profile_url": { "type": "string", "description": "LinkedIn profile URL" }, "linkedin_flagship_url": { "type": "string", "description": "LinkedIn flagship URL" }, "profile_picture_url": { "type": "string", "description": "Profile picture URL" }, "num_of_connections": { "type": "integer", "description": "Number of connections" }, "last_updated": { "type": "string", "description": "Last updated timestamp" }, "linkedin_url": { "type": "string", "description": "LinkedIn URL" }, "twitter_handle": { "type": "string", "description": "Twitter handle" }, "websites": { "type": "array", "items": { "type": "string" }, "description": "Associated websites" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses" }, "criteria": { "type": "object", "description": "Criteria object" } } }, "experience": { "type": "array", "items": { "type": "object", "properties": { "employee_position_id": { "type": "integer", "description": "Position ID" }, "employee_title": { "type": "string", "description": "Job title" }, "employer_name": { "type": "string", "description": "Company name" }, "employee_description": { "type": "string", "description": "Job description" }, "employer_linkedin_description": { "type": "string", "description": "Company description" }, "employer_linkedin_id": { "type": "string", "description": "Company LinkedIn ID" }, "employer_linkedin_url": { "type": "string", "description": "Company LinkedIn URL" }, "employer_logo_url": { "type": "string", "description": "Company logo URL" }, "start_date": { "type": "string", "description": "Start date" }, "end_date": { "type": "string", "description": "End date" }, "employee_location": { "type": "string", "description": "Work location" }, "employer_company_ids": { "type": "array", "items": { "type": "string" }, "description": "Company IDs" }, "employer_company_website_domains": { "type": "array", "items": { "type": "string" }, "description": "Company domains" }, "location": { "type": "string", "description": "Location" }, "is_current": { "type": "boolean", "description": "Whether this is current position" } } } }, "education": { "type": "array", "items": { "type": "object", "properties": { "institute_name": { "type": "string", "description": "Institution name" }, "degree_name": { "type": "string", "description": "Degree name" }, "field_of_study": { "type": "string", "description": "Field of study" }, "institute_linkedin_id": { "type": "string", "description": "Institution LinkedIn ID" }, "institute_linkedin_url": { "type": "string", "description": "Institution LinkedIn URL" }, "institute_logo_url": { "type": "string", "description": "Institution logo URL" }, "start_date": { "type": "string", "description": "Start date" }, "end_date": { "type": "string", "description": "End date" }, "description": { "type": "string", "description": "Education description" } } } }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Skills list" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages" }, "location": { "type": "string", "description": "Current location" }, "certifications": { "type": "array", "items": { "type": "object" }, "description": "Certifications" }, "honors": { "type": "array", "items": { "type": "object" }, "description": "Honors and awards" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "post_url": { "type": "string", "description": "Post URL" }, "title": { "type": "string", "description": "Post title/content" }, "action": { "type": "string", "description": "Action type (Liked by, Shared by)" }, "order_in_profile": { "type": "integer", "description": "Order in profile" } } }, "description": "Recent posts and activity" } }, "example": { "profile": { "id": "647479454", "name": "Alex Johnson", "headline": "Co-Founder @ TechCorp Inc (YC X25) | Z-Fellow | prev. State University M&T", "summary": "Working with great people is one of the best parts of life.", "location": "San Francisco, California, United States", "title": "Co-founder", "linkedin_profile_url": "https://www.linkedin.com/in/alexjohnson", "linkedin_flagship_url": "https://www.linkedin.com/in/alexjohnson", "profile_picture_url": "https://media.licdn.com/dms/image/v2/D4E03AQGqQzDcBXRVhw/profile-displayphoto-scale_200_200/example.jpg", "num_of_connections": 500, "last_updated": "", "linkedin_url": "https://www.linkedin.com/in/alexjohnson", "twitter_handle": "", "websites": [], "emails": [], "criteria": {} }, "experience": [ { "employee_position_id": 1, "employee_title": "Co-founder", "employer_name": "TechCorp Inc (YC X25)", "employee_description": "Building people search, used to be called StartupCo techcorp.ai", "employer_linkedin_description": "Software Development", "employer_linkedin_id": "97975821.0", "employer_linkedin_url": "https://www.linkedin.com/company/techcorp-inc", "employer_logo_url": "https://awss3legacy.blob.core.windows.net/company-logo-permalinks-new/images/example.jpg", "start_date": "2025-02", "end_date": "", "employee_location": "San Francisco Bay Area", "employer_company_ids": [], "employer_company_website_domains": [], "location": "San Francisco Bay Area", "is_current": true } ], "education": [ { "institute_name": "State University", "degree_name": "Bachelor of Science - BS, Computer Science", "field_of_study": "", "institute_linkedin_id": "", "institute_linkedin_url": "https://www.linkedin.com/school/state-university", "institute_logo_url": "https://awss3legacy.blob.core.windows.net/company-logo-permalinks-new/images/example.jpg", "start_date": "", "end_date": "", "description": null } ], "skills": [ "management", "technology", "science", "program management", "computer science" ], "languages": [], "location": "San Francisco, California, United States", "certifications": [], "honors": [], "posts": [ { "post_url": "https://www.linkedin.com/posts/alexjohnson_we-did-it-last-week-i-graduated-with-activity-7343065850410582018-bDZE", "title": "We did it 🎓\n\nLast week I graduated with honors from the State University Computer Science department. I'm incredibly grateful for these past two years. Along the way…", "action": "Liked by", "order_in_profile": 1 } ] } }, "LinkedInProfileResponse": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Full name" }, "headline": { "type": "string", "description": "Professional headline" }, "summary": { "type": "string", "description": "Profile summary" }, "location": { "type": "string", "description": "Location" }, "title": { "type": "string", "description": "Current title" }, "linkedin_profile_url": { "type": "string", "description": "LinkedIn profile URL" }, "linkedin_flagship_url": { "type": "string", "description": "LinkedIn flagship URL" }, "profile_picture_url": { "type": "string", "description": "Profile picture URL" }, "num_of_connections": { "type": "integer", "description": "Number of connections" }, "last_updated": { "type": "string", "description": "Last updated timestamp" }, "linkedin_url": { "type": "string", "description": "LinkedIn URL" }, "twitter_handle": { "type": "string", "description": "Twitter handle" }, "websites": { "type": "array", "items": { "type": "string" }, "description": "Associated websites" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses" }, "criteria": { "type": "object", "description": "Criteria object" } } }, "experience": { "type": "array", "items": { "type": "object", "properties": { "employee_position_id": { "type": "integer", "description": "Position ID" }, "employee_title": { "type": "string", "description": "Job title" }, "employer_name": { "type": "string", "description": "Company name" }, "employee_description": { "type": "string", "description": "Job description" }, "employer_linkedin_description": { "type": "string", "description": "Company description" }, "employer_linkedin_id": { "type": "string", "description": "Company LinkedIn ID" }, "employer_linkedin_url": { "type": "string", "description": "Company LinkedIn URL" }, "employer_logo_url": { "type": "string", "description": "Company logo URL" }, "start_date": { "type": "string", "description": "Start date" }, "end_date": { "type": "string", "description": "End date" }, "employee_location": { "type": "string", "description": "Work location" }, "employer_company_ids": { "type": "array", "items": { "type": "string" }, "description": "Company IDs" }, "employer_company_website_domains": { "type": "array", "items": { "type": "string" }, "description": "Company domains" }, "location": { "type": "string", "description": "Location" }, "is_current": { "type": "boolean", "description": "Whether this is current position" } } } }, "education": { "type": "array", "items": { "type": "object", "properties": { "institute_name": { "type": "string", "description": "Institution name" }, "degree_name": { "type": "string", "description": "Degree name" }, "field_of_study": { "type": "string", "description": "Field of study" }, "institute_linkedin_id": { "type": "string", "description": "Institution LinkedIn ID" }, "institute_linkedin_url": { "type": "string", "description": "Institution LinkedIn URL" }, "institute_logo_url": { "type": "string", "description": "Institution logo URL" }, "start_date": { "type": "string", "description": "Start date" }, "end_date": { "type": "string", "description": "End date" }, "description": { "type": "string", "description": "Education description" } } } }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Skills list" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages" }, "location": { "type": "string", "description": "Current location" }, "certifications": { "type": "array", "items": { "type": "object" }, "description": "Certifications" }, "honors": { "type": "array", "items": { "type": "object" }, "description": "Honors and awards" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "post_url": { "type": "string", "description": "Post URL" }, "title": { "type": "string", "description": "Post title/content" }, "action": { "type": "string", "description": "Action type (Liked by, Shared by)" }, "order_in_profile": { "type": "integer", "description": "Order in profile" } } }, "description": "Recent posts and activity" } }, "example": { "profile": { "id": "647479454", "name": "Sarah Wilson", "headline": "Senior Data Scientist @ InnovateTech | Z-Fellow | prev. Research University PhD", "summary": "Data science leader with expertise in machine learning and analytics.", "location": "New York, New York, United States", "title": "Senior Data Scientist", "linkedin_profile_url": "https://www.linkedin.com/in/sarahwilson", "linkedin_flagship_url": "https://www.linkedin.com/in/sarahwilson", "profile_picture_url": "https://media.licdn.com/dms/image/v2/D4E03AQGqQzDcBXRVhw/profile-displayphoto-scale_200_200/example.jpg", "num_of_connections": 750, "last_updated": "", "linkedin_url": "https://www.linkedin.com/in/sarahwilson", "twitter_handle": "", "websites": [], "emails": [], "criteria": {} }, "experience": [ { "employee_position_id": 1, "employee_title": "Senior Data Scientist", "employer_name": "InnovateTech", "employee_description": "Leading data science initiatives and ML model development", "employer_linkedin_description": "Technology", "employer_linkedin_id": "12345678.0", "employer_linkedin_url": "https://www.linkedin.com/company/innovatetech", "employer_logo_url": "https://awss3legacy.blob.core.windows.net/company-logo-permalinks-new/images/example.jpg", "start_date": "2021-01", "end_date": "", "employee_location": "New York, NY", "employer_company_ids": [], "employer_company_website_domains": [], "location": "New York, NY", "is_current": true } ], "education": [ { "institute_name": "Research University", "degree_name": "PhD", "field_of_study": "Statistics", "institute_linkedin_id": "", "institute_linkedin_url": "https://www.linkedin.com/school/research-university", "institute_logo_url": "https://awss3legacy.blob.core.windows.net/company-logo-permalinks-new/images/example.jpg", "start_date": "2015-09", "end_date": "2019-12", "description": null } ], "skills": [ "Data Science", "Machine Learning", "Python", "R", "Statistics", "AI Ethics" ], "languages": [], "location": "New York, New York, United States", "certifications": [], "honors": [], "posts": [ { "post_url": "https://www.linkedin.com/posts/sarahwilson_data-science-ethics-activity-7343065850410582018-bDZE", "title": "Excited to share insights on responsible AI deployment and ethical considerations in machine learning systems...", "action": "Shared by", "order_in_profile": 1 } ] } }, "PostReactionsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post_url": { "type": "string" }, "total_reactions": { "type": "integer" }, "reaction_breakdown": { "$ref": "#/components/schemas/ReactionBreakdown" }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/Reaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "example": { "data": { "post_url": "https://www.linkedin.com/posts/alexjohnson_activity-123456789", "total_reactions": 245, "reaction_breakdown": { "like": 180, "love": 35, "celebrate": 20, "support": 8, "insightful": 2 }, "reactions": [ { "profile": { "name": "Sarah Wilson", "headline": "Product Manager at StartupCo", "linkedin_url": "https://www.linkedin.com/in/sarahwilson" }, "reaction_type": "like", "timestamp": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "total_pages": 5, "has_next": true } } } }, "ErrorResponse": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message" } }, "required": [ "detail" ] }, "Experience": { "type": "object", "properties": { "title": { "type": "string", "description": "Job title" }, "company_name": { "type": "string", "description": "Company name" }, "start_date": { "type": "string", "description": "Start date in ISO format" }, "end_date": { "type": "string", "description": "End date in ISO format (1970-01-01T00:00:00 for current)" }, "description": { "type": "string", "description": "Job description" }, "location": { "type": "string", "description": "Work location" } } }, "Education": { "type": "object", "properties": { "degree": { "type": "string", "description": "Degree type" }, "field_of_study": { "type": "string", "description": "Field of study" }, "school_name": { "type": "string", "description": "School or university name" }, "start_date": { "type": "string", "description": "Start date in ISO format" }, "end_date": { "type": "string", "description": "End date in ISO format" } } }, "Award": { "type": "object", "properties": { "title": { "type": "string", "description": "Award title" }, "issuer": { "type": "string", "description": "Organization that issued the award" }, "description": { "type": "string", "description": "Award description" }, "date_year": { "type": "integer", "description": "Year the award was received" }, "date_month": { "type": "integer", "description": "Month the award was received" }, "order_in_profile": { "type": "integer", "description": "Display order in profile" } } }, "Certification": { "type": "object", "properties": { "title": { "type": "string", "description": "Certification title" }, "issuer": { "type": "string", "description": "Issuing organization" }, "date_from_year": { "type": "integer", "description": "Year certification was obtained" }, "date_from_month": { "type": "integer", "description": "Month certification was obtained" }, "date_to_year": { "type": "integer", "description": "Year certification expires" }, "date_to_month": { "type": "integer", "description": "Month certification expires" } } }, "Organization": { "type": "object", "properties": { "organization_name": { "type": "string", "description": "Name of the organization" }, "position": { "type": "string", "description": "Position held in the organization" }, "description": { "type": "string", "description": "Description of role or involvement" }, "date_from_year": { "type": "integer", "description": "Start year" }, "date_from_month": { "type": "integer", "description": "Start month" }, "date_to_year": { "type": "integer", "description": "End year" }, "date_to_month": { "type": "integer", "description": "End month" } } }, "Patent": { "type": "object", "properties": { "title": { "type": "string", "description": "Patent title" }, "description": { "type": "string", "description": "Patent description" }, "status": { "type": "string", "description": "Patent status (pending, granted, etc.)" }, "date_year": { "type": "integer", "description": "Year of patent filing/grant" }, "date_month": { "type": "integer", "description": "Month of patent filing/grant" } } }, "Project": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "date_from_year": { "type": "integer", "description": "Project start year" }, "date_from_month": { "type": "integer", "description": "Project start month" }, "date_to_year": { "type": "integer", "description": "Project end year" }, "date_to_month": { "type": "integer", "description": "Project end month" } } }, "Publication": { "type": "object", "properties": { "title": { "type": "string", "description": "Publication title" }, "description": { "type": "string", "description": "Publication description or abstract" }, "publisher_names": { "type": "string", "description": "Publisher or journal name" }, "date_year": { "type": "integer", "description": "Publication year" }, "date_month": { "type": "integer", "description": "Publication month" } } }, "GitHubRepo": { "type": "object", "properties": { "name": { "type": "string", "description": "Repository name" }, "summary": { "type": "string", "description": "Repository description" }, "stars": { "type": "integer", "description": "Number of stars" }, "contributions_count": { "type": "integer", "description": "Number of contributions" } } }, "ContactInfo": { "type": "object", "properties": { "error": { "type": "boolean", "description": "Whether an error occurred" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Array of contact information (emails and phone numbers)" }, "social": { "type": "array", "items": { "$ref": "#/components/schemas/Social" }, "description": "Array of social media profiles" } } }, "Contact": { "type": "object", "properties": { "type": { "type": "string", "enum": ["email", "phone"], "description": "Contact type" }, "value": { "type": "string", "description": "Contact value (email address or phone number)" }, "rating": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Confidence rating (0-100)" }, "subType": { "type": "string", "description": "Contact subtype (personal, work, verified, mobile, work_phone)" } }, "required": ["type", "value", "rating"] }, "Social": { "type": "object", "properties": { "link": { "type": "string", "description": "Social media profile URL" }, "type": { "type": "string", "description": "Social media platform type (li for LinkedIn)" }, "rating": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Confidence rating (0-100)" } }, "required": ["link", "type", "rating"] }, "DetailedProfile": { "type": "object", "properties": { "name": { "type": "string" }, "headline": { "type": "string" }, "location": { "type": "string" }, "about": { "type": "string" }, "connections_count": { "type": "integer" }, "followers_count": { "type": "integer" } } }, "DetailedExperience": { "type": "object", "properties": { "title": { "type": "string" }, "company": { "type": "string" }, "duration": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" } } }, "DetailedEducation": { "type": "object", "properties": { "school": { "type": "string" }, "degree": { "type": "string" }, "field": { "type": "string" }, "duration": { "type": "string" } } }, "Post": { "type": "object", "properties": { "text": { "type": "string", "description": "Post content text" }, "totalReactionCount": { "type": "integer", "description": "Total number of reactions" }, "likeCount": { "type": "integer", "description": "Number of like reactions" }, "appreciationCount": { "type": "integer", "description": "Number of appreciation reactions" }, "empathyCount": { "type": "integer", "description": "Number of empathy reactions" }, "InterestCount": { "type": "integer", "description": "Number of interest reactions" }, "praiseCount": { "type": "integer", "description": "Number of praise reactions" }, "commentsCount": { "type": "integer", "description": "Number of comments" }, "repostsCount": { "type": "integer", "description": "Number of reposts" }, "postUrl": { "type": "string", "description": "URL to the LinkedIn post" }, "postedAt": { "type": "string", "description": "Human-readable time since posted" }, "postedDate": { "type": "string", "description": "ISO timestamp of when posted" }, "postedDateTimestamp": { "type": "integer", "description": "Unix timestamp of when posted" }, "reposted": { "type": "boolean", "description": "Whether this is a repost" }, "urn": { "type": "string", "description": "LinkedIn URN identifier" }, "author": { "$ref": "#/components/schemas/PostAuthor" }, "image": { "type": "array", "items": { "$ref": "#/components/schemas/PostImage" }, "description": "Post images" }, "video": { "type": "array", "items": { "$ref": "#/components/schemas/PostVideo" }, "description": "Post videos" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/PostMention" }, "description": "People mentioned in the post" }, "companyMentions": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMention" }, "description": "Companies mentioned in the post" }, "isBrandPartnership": { "type": "boolean", "description": "Whether this is a brand partnership post" } } }, "ReactionBreakdown": { "type": "object", "properties": { "like": { "type": "integer" }, "love": { "type": "integer" }, "celebrate": { "type": "integer" }, "support": { "type": "integer" }, "insightful": { "type": "integer" }, "funny": { "type": "integer" } } }, "Reaction": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/ReactionProfile" }, "reaction_type": { "type": "string" }, "timestamp": { "type": "string" } } }, "ReactionProfile": { "type": "object", "properties": { "name": { "type": "string" }, "headline": { "type": "string" }, "linkedin_url": { "type": "string" } } }, "PostAuthor": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Author's first name" }, "lastName": { "type": "string", "description": "Author's last name" }, "username": { "type": "string", "description": "LinkedIn username" }, "url": { "type": "string", "description": "LinkedIn profile URL" } } }, "PostImage": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL" }, "width": { "type": "integer", "description": "Image width in pixels" }, "height": { "type": "integer", "description": "Image height in pixels" } } }, "PostVideo": { "type": "object", "properties": { "url": { "type": "string", "description": "Video URL" }, "width": { "type": "integer", "description": "Video width in pixels" }, "height": { "type": "integer", "description": "Video height in pixels" } } }, "PostMention": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Mentioned person's first name" }, "lastName": { "type": "string", "description": "Mentioned person's last name" }, "urn": { "type": "string", "description": "LinkedIn URN" }, "publicIdentifier": { "type": "string", "description": "LinkedIn public identifier" } } }, "CompanyMention": { "type": "object", "properties": { "id": { "type": "integer", "description": "Company ID" }, "name": { "type": "string", "description": "Company name" }, "publicIdentifier": { "type": "string", "description": "Company LinkedIn identifier" }, "url": { "type": "string", "description": "Company LinkedIn URL" } } }, "Pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" } } }, "PaginationInfo": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "total_pages": { "type": "integer", "description": "Total number of pages" }, "total_results": { "type": "integer", "description": "Total number of results across all pages" }, "has_next": { "type": "boolean", "description": "Whether there is a next page" }, "has_previous": { "type": "boolean", "description": "Whether there is a previous page" } }, "required": ["page", "page_size", "total_pages", "total_results", "has_next", "has_previous"] }, "BulkEnrichRequest": { "type": "object", "properties": { "linkedin_urls": { "type": "array", "items": { "type": "string" }, "description": "List of LinkedIn profile URLs to enrich (max 5000)" }, "people_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional list of people IDs corresponding to each LinkedIn URL" }, "email_enrichment": { "type": "boolean", "default": false, "description": "If true, returns emails (costs 4 credits per email found). Can be combined with phone_enrichment" }, "phone_enrichment": { "type": "boolean", "default": false, "description": "If true, returns phone numbers (costs 10 credits per phone found). Can be combined with email_enrichment" }, "search_id": { "type": "string", "description": "Optional search ID for tracking purposes" } }, "required": ["linkedin_urls"] }, "BulkEnrichJobResponse": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the bulk enrichment job" }, "status": { "type": "string", "description": "Job status (processing)" }, "message": { "type": "string", "description": "Status message" } } }, "BulkEnrichResult": { "type": "object", "properties": { "linkedin_url": { "type": "string", "description": "LinkedIn URL that was processed" }, "people_id": { "type": "string", "description": "Associated people ID if provided" }, "success": { "type": "boolean", "description": "Whether enrichment was successful" }, "data": { "type": "object", "description": "Contact information if successful" }, "error": { "type": "string", "description": "Error message if failed" } } }, "BulkEnrichStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the bulk enrichment job" }, "status": { "type": "string", "description": "Job status (processing, completed, error)" }, "total_urls": { "type": "integer", "description": "Total number of URLs to process" }, "processed": { "type": "integer", "description": "Number of URLs processed so far" }, "successful": { "type": "integer", "description": "Number of successful enrichments" }, "failed": { "type": "integer", "description": "Number of failed enrichments" }, "credits_used": { "type": "integer", "description": "Total credits consumed" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkEnrichResult" }, "description": "Array of enrichment results" }, "created_at": { "type": "number", "description": "Unix timestamp when job was created" }, "completed_at": { "type": "number", "description": "Unix timestamp when job was completed" } } }, "CreditsResponse": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Number of credits remaining in your account" }, "last_topup_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of your last credit purchase/top-up" } }, "required": [ "credits" ], "example": { "credits": 247, "last_topup_at": "2024-01-15T10:30:00Z" } } } } }