### Example Python Client Usage for Search Source: https://apidocs.pearch.ai/reference/post_v2-search Demonstrates how to use the Pearch.ai Python client to perform a search query. This example shows initializing the client and calling the search function with a query string. Ensure you have the pearch-client library installed. ```python from pearch_client import PearchClient client = PearchClient(api_key="YOUR_API_KEY") query = "software engineer from Ohio" results = client.search.query(query=query) for profile in results.profiles: print(f"Name: {profile.name}, Score: {profile.score}") ``` -------------------------------- ### Profile Filtering Example Source: https://apidocs.pearch.ai/reference/post_threads_thread_id_runs An example demonstrating how to combine various filtering parameters to search for profiles. This includes industries, locations, job titles, minimum experience, and a flag for studying at top universities. ```json { "industries": [ "health", "pharma" ], "locations": [ "San Francisco", "New York" ], "titles": [ "software engineer", "data scientist" ], "min_total_experience_years": 5, "studied_at_top_universities": true } ``` -------------------------------- ### Company Information Schema Example Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs This JSON schema defines the structure for company information. It includes fields for name, locations, type, description, and industries, with examples provided for each. ```json { "name": { "type": "string", "description": "Name of the company", "example": "Dayton, OH" }, "locations": { "type": "array", "description": "List of company locations", "items": { "type": "string" }, "example": [ "Dayton, Ohio", "San Francisco, CA" ] }, "type": { "type": "string", "description": "Type of company", "example": "Private" }, "description": { "type": "string", "description": "A brief description of the company's business", "example": "Targeting Complex Aerospace Issues with Precision Test Tools" }, "industries": { "type": "array", "description": "The industries the company operates in", "items": { "type": "string", "enum": [ "Archiving Service", "Call Center", "Collection Agency", "College Recruiting", "Courier Service", "Debt Collections", "Delivery", "Document Preparation", "Employee Benefits", "Extermination Service", "Facilities Support Services", "Housekeeping Service", "Human Resources", "Knowledge Management", "Office Administration", "Packaging Services", "Physical Security", "Project Management", "Staffing Agency", "Trade Shows", "Virtual Workforce", "Ad Exchange", "Ad Network", "Ad Retargeting", "Ad Server", "Ad Targeting", "Advertising", "Advertising Platforms", "Affiliate Marketing", "Local Advertising", "Mobile Advertising", "Native Advertising", "Outdoor Advertising", "SEM", "Social Media Advertising", "Video Advertising", "Agriculture", "AgTech", "Animal Feed", "Aquaculture", "Equestrian", "Farming", "Forestry", "Horticulture", "Hydroponics", "Livestock", "App Discovery", "Apps", "Consumer Applications", "Enterprise Applications", "Mobile Apps", "Reading Apps", "Web Apps", "Artificial Intelligence (AI)", "Generative AI", "Intelligent Systems", "Machine Learning", "Natural Language Processing", "Predictive Analytics", "Robotic Process Automation (RPA)", "Bioinformatics", "Biometrics", "Biopharma", "Biotechnology", "Genetics", "Life Science", "Neuroscience", "Quantified Self", "Bitcoin", "Blockchain", "Cryptocurrency", "Decentralized Finance (DeFi)", "Ethereum", "Non-Fungible Token (NFT)", "Smart Contracts", "Web3", "Apparel", "Fashion", "Laundry and Dry-cleaning", "Lingerie", "Shoes", "Auctions", "Classifieds", "Collectibles", "Consumer Reviews", "Coupons", "E-Commerce", "E-Commerce Platforms", "Flash Sale", "Gift", "Gift Card", "Gift Exchange", "Gift Registry", "Group Buying", "Local Shopping", "Made to Order", "Marketplace", "Office Supplies", "Online Auctions", "Personalization", "Point of Sale", "Price Comparison", "Rental", "Retail", "Retail Technology", "Secondhand Goods", "Shopping", "Shopping Mall", "Social Shopping", "Sporting Goods", "Vending and Concessions", "Virtual Goods", "Wholesale", "Adult", "Baby", "Cannabis", "Children", "Communities", "Dating", "Elderly", "Family", "Funerals", "Humanitarian", "Leisure", "LGBT", "Lifestyle", "Men's", "Online Forums", "Parenting", "Pet", "Private Social Networking", "Professional Networking", "Q&A", "Religion", "Retirement", "Sex Industry", "Sex Tech", "Social", "Social Entrepreneurship", "Teenagers", "Virtual World", "Wedding", "Women's", "Young Adults", "Computer", "Consumer Electronics", "Drones", "Electronics", "Google Glass", "Mobile Devices", "Nintendo", "Playstation", "Roku", "Smart Home", "Wearables", "Windows Phone", "Xbox", "Beauty", "Card and Board Games", "Cleaning Products", "Comics", "Consumer Goods", "Cosmetics", "DIY", "Eyewear", "Fast-Moving Consumer Goods", "Flowers", "Furniture", "Green Consumer Goods", "Handmade", "Home Appliances", "Jewelry", "Personal Care and Hygiene", "Tobacco", "Toys", "Blogging Platforms", "Books", "Content Delivery Network", "Content Discovery", "Content Syndication", "Copywriting", "Creative Agency", "DRM", "EBooks", "Journalism", "News", "Photo Editing", "Photo Sharing", "Photography", "Printing", "Publishing", "Social Bookmarking", "Video Editing", "Video Streaming", "A/B Testing", "Analytics", "Application Performance Management", "Big Data", "Business Intelligence", "Consumer Research", "Data Collection and Labeling", "Data Governance", "Data Integration", "Data Management", "Data Mining", "Data Visualization", "Database", "Facial Recognition", "Geospatial", "Image Recognition", "Location Based Services", "Market Research", "Product Research", "Speech Recognition", "Test and Measurement", "Text Analytics", "Usability Testing", "CAD", "Graphic Design", "Human Computer Interaction", "Industrial Design", "Interior Design", "Mechanical Design", "Product Design", "UX Design", "Web Design", "Alumni", "Charter Schools", "Continuing Education", "Corporate Training", "E-Learning", "EdTech", "Education", "Edutainment", "Higher Education", "Language Learning", "MOOC", "Music Education", "Personal Development", "Primary Education", "Secondary Education", "Skill Assessment", "Special Education", "STEM Education", "Textbook", "Training", "Tutoring", "Vocational Education", "Battery", "Biofuel", "Biomass Energy", "Clean Energy", "Electrical Distribution", "Energy", "Energy Efficiency", "Energy Management", "Energy Storage", "Fossil Fuels", "Fuel", "Fuel Cell", "Geothermal Energy", "Hydroelectric", "Oil and Gas", "Power Grid", "Renewable Energy", "Solar", "Wind Energy", "Concerts", "Event Management", "Event Promotion", "Events", "Nightclubs", "Nightlife", "Reservations", "Ticketing", "Accounting", "Angel Investment", "Asset Management", "Auto Insurance", "Banking" ] }, "example": [ "Archiving Service", "Call Center", "Collection Agency" ] } } ``` -------------------------------- ### Stream Thread Execution with LangGraph SDK Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Demonstrates how to initiate a new run within a thread and stream the output using the LangGraph SDK. The example uses Python to configure the client, define input messages, and asynchronously iterate through stream chunks. ```python from langgraph_sdk import get_client import uuid headers = {"Authorization": f"Bearer {API_KEY}"} client = get_client(url=base_url, headers=headers) thread_id = str(uuid.uuid4()) input_data = { "messages": [ { "type": "human", "content": "ml engineers in seattle" } ], } chunks_received = [] stream_mode = ["updates", "values", "custom"] print(f"Starting stream. {thread_id=} {input_data=}") async for chunk in client.runs.stream( thread_id=thread_id, assistant_id="agent", input=input_data, config={}, stream_mode=stream_mode, ): chunks_received.append(chunk) print(chunk) ``` -------------------------------- ### Perform Company and Lead Search via JSON Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Examples of JSON request payloads for the /v2/search endpoint. These demonstrate how to query for companies only, companies with leads, and companies with leads plus personalized outreach instructions. ```json { "company_query": "manufacturers of aviation parts" } ``` ```json { "company_query": "manufacturers of aviation parts", "lead_query": "CTOs and engineering managers" } ``` ```json { "company_query": "manufacturers of aviation parts", "lead_query": "CTOs and engineering managers", "outreach_message_instruction": "Suggest buying my (Rob) SaaS recruitment product <300 characters, email style, casual, personal touch" } ``` -------------------------------- ### GET /v1/user Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves account information for the authenticated user. ```APIDOC ## GET /v1/user ### Description Returns details regarding the current authenticated account. ### Method GET ### Endpoint /v1/user ### Response #### Success Response (200) - **account** (object) - Account details. ``` -------------------------------- ### GET /v1/profile Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Enriches a user profile with additional data. ```APIDOC ## GET /v1/profile ### Description Fetches enriched information for a specific user profile. ### Method GET ### Endpoint /v1/profile ### Query Parameters - **user_id** (string) - Required - The ID of the profile to enrich. ### Response #### Success Response (200) - **profile** (object) - The enriched profile data. ``` -------------------------------- ### Configure Pearch.ai Search Parameters Source: https://apidocs.pearch.ai/reference/post_v2-search JSON configuration examples for different search performance tiers. These objects are passed to the search endpoint to control search quality, insights, and profile scoring. ```json { "query": "", "type": "pro", "insights": true, "profile_scoring": true } ``` ```json { "query": "", "type": "fast", "insights": true, "profile_scoring": true } ``` -------------------------------- ### GET /v1/list-jobs Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves a list of all jobs associated with the account. ```APIDOC ## GET /v1/list-jobs ### Description Fetches all jobs currently stored or tracked in the system. ### Method GET ### Endpoint /v1/list-jobs ### Response #### Success Response (200) - **jobs** (array) - A list of job objects. ``` -------------------------------- ### Implement Pagination with Thread ID Source: https://apidocs.pearch.ai/llms.txt Demonstrates how to implement pagination for search results by passing the `thread_id` from a previous request. The `limit` parameter should be increased in subsequent requests to retrieve more results. This is essential for handling large result sets and ensuring all relevant profiles are fetched. ```json { "query": "", "thread_id": "", "limit": 50 } ``` -------------------------------- ### GET /company/info Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Retrieves detailed information about a specific company. ```APIDOC ## GET /company/info ### Description Retrieves comprehensive company information and metadata. ### Method GET ### Endpoint /company/info ### Parameters #### Query Parameters - **name** (string) - Required - The name of the company to search for. ### Request Example ```json { "example": "GET /company/info?name=Dragoonitcn" } ``` ### Response #### Success Response (200) - **name** (string) - The name of the company. - **domain** (string) - Company's primary domain. - **website** (string) - The official website of the company. - **linkedin_url** (string) - The LinkedIn URL of the company. - **linkedin_slug** (string) - LinkedIn slug identifier. - **crunchbase_url** (string) - The Crunchbase URL of the company. - **social_urls** (array of strings) - List of social media URLs. - **emails** (array of strings) - List of company email addresses. - **phone_number** (string) - Company phone number. - **phone_numbers** (array of strings) - List of company phone numbers. - **short_address** (string) - Brief address information. - **locations** (array of strings) - List of company locations. - **type** (string) - Type of company. - **description** (string) - A brief description of the company's business. - **industries** (array of strings) - The industries the company operates in. #### Response Example ```json { "example": { "name": "Dragoonitcn", "domain": "dragoonitcn.com", "website": "http://www.dragoonitcn.com", "linkedin_url": "https://linkedin.com/company/dragoon-itcn", "linkedin_slug": "dragoon-itcn", "crunchbase_url": "https://www.crunchbase.com/organization/dragoonitcn", "social_urls": [ "https://twitter.com/dragoonitcn", "https://facebook.com/pages/Dragoonitcn/125328487521849" ], "emails": [ "contact@dragoonitcn.com", "sales@dragoonitcn.com" ], "phone_number": "+1-555-123-4567", "phone_numbers": [ "+1-555-123-4567", "+1-555-987-6543" ], "short_address": "Dayton, OH", "locations": [ "Dayton, Ohio", "San Francisco, CA" ], "type": "Private", "description": "Targeting Complex Aerospace Issues with Precision Test Tools", "industries": [ "Aerospace", "Technology" ] } } ``` ``` -------------------------------- ### POST /profiles/search Source: https://apidocs.pearch.ai/reference/post_threads_thread_id_runs Search and filter professional profiles using various criteria including specialization categories, industries, and experience levels. ```APIDOC ## POST /profiles/search ### Description Filters professional profiles based on specific academic specializations, industries, locations, and experience requirements. ### Method POST ### Endpoint /profiles/search ### Parameters #### Request Body - **specialization_categories** (array) - Optional - Filter by specialization categories (e.g., Computer Science & IT, Engineering). - **not_specialization_categories** (array) - Optional - Exclude profiles by specialization category. - **industries** (array) - Optional - List of industries to filter by. - **locations** (array) - Optional - List of geographic locations. - **titles** (array) - Optional - Job titles to filter by. - **min_total_experience_years** (integer) - Optional - Minimum years of professional experience. - **studied_at_top_universities** (boolean) - Optional - Filter for candidates from top universities. ### Request Example { "industries": ["health", "pharma"], "locations": ["San Francisco", "New York"], "titles": ["software engineer", "data scientist"], "min_total_experience_years": 5, "studied_at_top_universities": true } ### Response #### Success Response (200) - **profiles** (array) - List of matching professional profiles. #### Response Example { "profiles": [] } ``` -------------------------------- ### POST /candidates/search Source: https://apidocs.pearch.ai/reference/post_threads_thread_id_runs Searches and filters candidate profiles based on a variety of professional and demographic criteria. ```APIDOC ## POST /candidates/search ### Description Filters and retrieves candidate profiles based on provided criteria such as experience, education, and specific keywords. ### Method POST ### Endpoint /candidates/search ### Parameters #### Request Body - **keywords** (array) - Optional - Filter by keywords in full profile description - **keywords_blacklist** (array) - Optional - Exclude profiles containing these keywords - **min_linkedin_followers** (integer) - Optional - Minimum number of LinkedIn followers - **max_linkedin_followers** (integer) - Optional - Maximum number of LinkedIn followers - **min_total_experience_years** (number) - Optional - Minimum total years of professional experience - **max_total_experience_years** (number) - Optional - Maximum total years of professional experience - **min_estimated_age** (number) - Optional - Minimum estimated age - **max_estimated_age** (number) - Optional - Maximum estimated age - **studied_at_top_universities** (boolean) - Optional - Filter for candidates who attended top-tier universities - **first_name** (string) - Optional - Filter by first name - **last_name** (string) - Optional - Filter by last name - **gender** (string) - Optional - Filter by gender (male, female) - **has_startup_experience** (boolean) - Optional - Filter for candidates with startup experience - **degrees** (array) - Optional - Filter by degree types (bachelor, master, MBA, doctor, postdoc) ### Request Example { "keywords": ["machine learning", "python"], "min_total_experience_years": 5, "studied_at_top_universities": true } ### Response #### Success Response (200) - **results** (array) - List of matching candidate profiles #### Response Example { "results": [ { "id": "123", "name": "John Smith" } ] } ``` -------------------------------- ### GET /v1/list_jobs Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Retrieves a list of all jobs currently indexed for the authenticated user. ```APIDOC ## GET /v1/list_jobs ### Description Retrieve a list of all jobs currently indexed for the authenticated user. Results are ordered by creation date. ### Method GET ### Endpoint /v1/list_jobs ### Parameters #### Query Parameters - **limit** (integer) - Optional - Maximum number of jobs to return (1-1000). ### Request Example GET /v1/list_jobs?limit=50 ### Response #### Success Response (200) - **status** (string) - Status of the operation. - **jobs** (array) - List of job objects. #### Response Example { "status": "success", "jobs": [ { "job_id": "engineer-001", "job_description": "Senior Software Engineer for AI startup", "created_at": "2023-10-27T10:00:00Z" } ] } ``` -------------------------------- ### GET /threads/{thread_id}/state Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves the current state of a specific search thread. ```APIDOC ## GET /threads/{thread_id}/state ### Description Returns the status and current state of an ongoing search thread. ### Method GET ### Endpoint /threads/{thread_id}/state ### Parameters #### Path Parameters - **thread_id** (string) - Required - The unique identifier for the thread. ### Response #### Success Response (200) - **state** (object) - The current state information. ``` -------------------------------- ### Enable High Freshness for Real-time Updates Source: https://apidocs.pearch.ai/reference/post_v2-search Enables real-time profile updates by downloading the most recent copies from source websites. This ensures fresher data but costs 2 credits per candidate and may increase search time. ```json { "high_freshness": true } ``` -------------------------------- ### GET /v2/search/status/{task_id} Source: https://apidocs.pearch.ai/reference/post_v2-search Retrieves the status and results of a previously submitted search task. ```APIDOC ## GET /v2/search/status/{task_id} ### Description Polls the status of an asynchronous search task. Returns the current state (pending, completed, or failed) and results if finished. ### Method GET ### Endpoint /v2/search/status/{task_id} ### Parameters #### Path Parameters - **task_id** (string) - Required - The ID returned from the submission endpoint. ### Response #### Success Response (200) - **status** (string) - The current state of the task. #### Response Example { "status": "completed" } ``` -------------------------------- ### Bearer Token Authentication Example (Bash) Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Demonstrates how to use Bearer token authentication with a cURL command. This method is suitable for accessing resources protected by a token, commonly used in OAuth 2.0 flows. The token is sent in the 'Authorization' header. ```bash curl --request POST \ --url https://httpbin.org/anything/bearer --header 'Authorization: Bearer BEARER_TOKEN' ``` -------------------------------- ### POST /run Source: https://apidocs.pearch.ai/reference/post_threads_thread_id_runs Initiates a run and streams Server-Sent Events (SSE) containing updates about the graph execution, current values, and custom events. The stream continues until a null event is received. ```APIDOC ## POST /run ### Description Initiates a run and streams Server-Sent Events (SSE) containing updates about the graph execution, current values, and custom events. The stream continues until a null event is received. ### Method POST ### Endpoint /run ### Parameters #### Query Parameters - **messages** (array[object]) - Required - A list of messages to process. Each message should have a `role` (e.g., "user", "assistant") and `content`. - **stream_mode** (array[string]) - Optional - List of streaming modes to enable. Can include "updates", "values", and "custom". Defaults to ["values"] if not specified. - **stream_resumable** (boolean) - Optional - Whether the stream is resumable. Defaults to false. - **assistant_id** (string) - Optional - Identifier for the assistant to use. Defaults to "agent". - **on_disconnect** (string) - Optional - Behavior when client disconnects. Can be "continue" to keep processing or "stop" to abort. - **recursion_limit** (integer) - Optional - The maximum recursion depth for the graph execution. Defaults to 100. - **custom_filters** (object) - Optional - Custom filters in JSON format for advanced filtering. Leave empty to use default filtering logic. #### Request Body This endpoint does not use a request body. All parameters are passed as query parameters. ### Request Example ```json { "messages": [ { "role": "user", "content": "Find profiles for software engineers in San Francisco." } ], "stream_mode": ["updates", "values"], "custom_filters": { "locations": ["San Francisco"], "titles": ["Software Engineer"] } } ``` ### Response #### Success Response (200) - **text/event-stream** (string) - Server-Sent Events stream. Each event has the format: ``` event: data: ``` Where `` is one of "updates", "values", "custom", or "heartbeat", and `` is the JSON-encoded data for that event. #### Response Example ``` event: values data: {"linkedin_slugs": ["profile1", "profile2"]} event: updates data: {"node_name": {"key": "value"}} event: heartbeat ``` #### Error Responses - **400**: Bad request (e.g., missing messages, invalid JSON, empty query content). - **401**: Invalid API key. - **500**: Internal server error. ``` -------------------------------- ### GET /company/{domain} Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves comprehensive company information and metadata for a specific organization. ```APIDOC ## GET /company/{domain} ### Description Fetches detailed metadata about a company, including contact info, social links, and industry classifications. ### Method GET ### Endpoint /company/{domain} ### Parameters #### Path Parameters - **domain** (string) - Required - The primary domain of the company ### Response #### Success Response (200) - **name** (string) - Company name - **domain** (string) - Primary domain - **website** (string) - Official website - **linkedin_url** (string) - LinkedIn profile URL - **emails** (array) - List of contact emails #### Response Example { "name": "Dragoonitcn", "domain": "dragoonitcn.com", "website": "http://www.dragoonitcn.com", "emails": ["contact@dragoonitcn.com"] } ``` -------------------------------- ### POST /assistant/stream Source: https://apidocs.pearch.ai/reference/post_v2-search Initiates a streaming session with an assistant, allowing for real-time updates and interaction handling. ```APIDOC ## POST /assistant/stream ### Description Starts a streaming session for an assistant, supporting various stream modes and disconnect behaviors. ### Method POST ### Endpoint /assistant/stream ### Parameters #### Request Body - **assistant_id** (string) - Optional - Identifier for the assistant (default: "agent") - **stream_mode** (array) - Optional - List of modes: "updates", "values", "custom" - **stream_resumable** (boolean) - Optional - Whether the stream is resumable - **on_disconnect** (string) - Optional - Behavior on disconnect: "continue" or "stop" ### Request Example { "assistant_id": "agent", "stream_mode": ["updates", "values"], "on_disconnect": "continue" } ### Response #### Success Response (200) - **stream** (text/event-stream) - Server-Sent Events stream containing run updates #### Response Example { "event": "update", "data": "processing_started" } ``` -------------------------------- ### GET /candidate/profile Source: https://apidocs.pearch.ai/reference/post_v2-search Retrieves a comprehensive candidate profile including professional history, education, and certifications. ```APIDOC ## GET /candidate/profile ### Description Retrieves a detailed profile for a candidate, including their educational background, professional certifications, patents, and publications. ### Method GET ### Endpoint /candidate/profile ### Parameters #### Query Parameters - **candidate_id** (string) - Required - The unique identifier for the candidate. ### Request Example { "candidate_id": "12345" } ### Response #### Success Response (200) - **educations** (array) - List of educational experiences. - **certifications** (array) - List of professional certifications. - **patents** (array) - List of patents held by the candidate. - **updated_date** (string) - Date when the profile was last updated. #### Response Example { "educations": [{"university_linkedin_url": "https://linkedin.com/school/ucb", "major": "Computer Science"}], "certifications": [{"title": "AWS Certified Solutions Architect"}], "updated_date": "2024-01-15" } ``` -------------------------------- ### Search and Stream Output using LangGraph SDK (Python) Source: https://apidocs.pearch.ai/reference/post_threads_thread_id_runs This Python code snippet demonstrates how to initiate a search and stream output from a thread using the LangGraph SDK. It requires an API key for authentication and specifies the thread ID, assistant ID, input messages, and desired stream modes. The output is received as an asynchronous stream of chunks. ```python from langgraph_sdk import get_client import uuid API_KEY = "YOUR_API_KEY" base_url = "https://api.pearch.ai/" headers = {"Authorization": f"Bearer {API_KEY}"} client = get_client(url=base_url, headers=headers) thread_id = str(uuid.uuid4()) input_data = { "messages": [ { "type": "human", "content": "ml engineers in seattle" } ], } chunks_received = [] stream_mode = ["updates", "values", "custom"] print(f"Starting stream. {thread_id=} {input_data=}") async for chunk in client.runs.stream( thread_id=thread_id, assistant_id="agent", input=input_data, config={}, stream_mode=stream_mode, ): chunks_received.append(chunk) print(chunk) ``` -------------------------------- ### GET /profiles/{docid} Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves a detailed candidate profile based on the unique document ID. ```APIDOC ## GET /profiles/{docid} ### Description Retrieves a comprehensive structured profile of a candidate using their unique document identifier. ### Method GET ### Endpoint /profiles/{docid} ### Parameters #### Path Parameters - **docid** (string) - Required - The unique document ID of the candidate profile (e.g., "jason-tysl"). ### Request Example GET /profiles/jason-tysl ### Response #### Success Response (200) - **docid** (string) - Unique document ID. - **first_name** (string) - Candidate's first name. - **last_name** (string) - Candidate's last name. - **title** (string) - Current job title. - **emails** (array) - List of associated email addresses. - **expertise** (array) - List of skills and areas of expertise. #### Response Example { "docid": "jason-tysl", "first_name": "Jason", "last_name": "Tysl", "title": "Software Engineer II", "emails": ["jtysl@agileblue.com", "jason.tysl@gmail.com"], "expertise": ["Python", "Machine Learning", "Software Engineering"] } ``` -------------------------------- ### Search People Profiles (POST /v2/search) Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs This endpoint allows for searching people profiles using natural language queries. It supports various query types, including simple searches, complex criteria, and full job descriptions. Parameters can be adjusted to balance speed and quality, and results are ordered by relevance. Cost is calculated based on the number of profiles and selected features. ```shell curl -X POST https://api.pearch.ai/v2/search \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "query": "software engineer from Ohio", "type": "fast", "insights": true, "profile_scoring": true }' ``` -------------------------------- ### GET /api/candidates/{id} Source: https://apidocs.pearch.ai/reference/post_v1-find-matching-jobs Retrieves the full profile of a specific candidate using their unique identifier. ```APIDOC ## GET /api/candidates/{id} ### Description Retrieves the full profile of a specific candidate using their unique identifier. This endpoint provides access to all available information about a candidate, including personal details, professional experience, contact information, and skills. ### Method GET ### Endpoint /api/candidates/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the candidate to retrieve. #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **id** (string) - Unique identifier for the candidate. - **first_name** (string) - First name of the candidate. - **middle_name** (string) - Middle name of the candidate. - **last_name** (string) - Last name of the candidate. - **picture_url** (string) - URL to the candidate's profile picture. - **title** (string) - Current job title or headline. - **summary** (string) - Professional summary or bio. - **gender** (string) - Gender of the candidate. Supported values: "male", "female". - **is_decision_maker** (number) - Whether the candidate is a decision maker (0 for no, 1 for yes). - **languages** (array) - List of languages the candidate knows with proficiency levels. - **language** (string) - Language name. - **proficiency** (string) - Proficiency level (A1, A2, B1, B2, C1, C2, unknown). - **inferred_languages** (array) - Languages inferred from the candidate's profile with proficiency levels. - **language** (string) - Language name. - **proficiency** (string) - Proficiency level (A1, A2, B1, B2, C1, C2, unknown). - **location** (string) - Current location of the candidate. - **is_top_universities** (boolean) - Whether the candidate attended a top university. - **is_opentowork** (boolean) - Whether the candidate is open to work opportunities (only if realtime profiles are enabled and status is public). - **is_hiring** (boolean) - Whether the candidate is currently hiring (only if realtime profiles are enabled). - **total_experience_years** (number) - Total years of professional experience. - **estimated_age** (number) - Estimated age of the candidate. - **expertise** (array) - Areas of expertise or skills. - **has_emails** (boolean) - Whether the candidate has any email addresses available. - **emails** (array) - List of all email addresses associated with the candidate. - **best_personal_email** (string) - Best personal email address for the candidate. - **best_business_email** (string) - Best business email address for the candidate. - **personal_emails** (array) - List of personal email addresses. - **business_emails** (array) - List of business email addresses. - **has_phone_numbers** (boolean) - Whether the candidate has any phone numbers available. - **phone_numbers** (array) - List of phone numbers associated with the candidate. - **phone_types** (array) - List of phone number types available for the candidate (e.g., "mobile"). - **websites** (array) - List of social profile URLs found during phone or email enrichment. - **followers_count** (integer) - Number of followers on LinkedIn. - **connections_count** (integer) - Number of connections on LinkedIn. - **experiences** (array) - List of professional work experiences grouped by company. - **company_info** (object) - Information about the company. #### Response Example ```json { "id": "jason-tysl", "first_name": "Jason", "middle_name": "Michael", "last_name": "Tysl", "picture_url": "https://example.com/profile.jpg", "title": "Software Engineer II", "summary": "Experienced software engineer with expertise in...", "gender": "male", "is_decision_maker": 1, "languages": [ { "language": "English", "proficiency": "C1" } ], "inferred_languages": [ { "language": "English", "proficiency": "C1" } ], "location": "Dayton, Ohio, United States", "is_top_universities": true, "is_opentowork": false, "is_hiring": false, "total_experience_years": 3.5, "estimated_age": 28, "expertise": [ "Python", "Machine Learning", "Software Engineering" ], "has_emails": true, "emails": [ "jtysl@agileblue.com", "jason.tysl@gmail.com" ], "best_personal_email": "jason.tysl@gmail.com", "best_business_email": "jtysl@agileblue.com", "personal_emails": [ "jason.tysl@gmail.com" ], "business_emails": [ "jtysl@agileblue.com" ], "has_phone_numbers": true, "phone_numbers": [ "+1-555-123-4567" ], "phone_types": [ "mobile" ], "websites": [ "https://twitter.com/johndoe", "https://github.com/johndoe" ], "followers_count": 150, "connections_count": 500, "experiences": [ { "company_info": { "name": "Tech Solutions Inc." } } ] } ``` ``` -------------------------------- ### GET /v1/list_jobs Source: https://apidocs.pearch.ai/reference/post_v2-search Retrieve a list of all jobs currently indexed for the authenticated user, ordered by creation date. ```APIDOC ## GET /v1/list_jobs ### Description Retrieve a list of all jobs currently indexed for the authenticated user. This endpoint returns job metadata including job IDs, descriptions, and creation timestamps. ### Method GET ### Endpoint /v1/list_jobs ### Parameters #### Query Parameters - **limit** (integer) - Optional - Maximum number of jobs to return (1-1000, default: 100) ### Response #### Success Response (200) - **status** (string) - Status of the operation - **jobs** (array) - List of job objects - **total_count** (integer) - Total number of jobs in index - **returned_count** (integer) - Number of jobs returned #### Response Example { "status": "success", "jobs": [ { "job_id": "engineer-001", "job_description": "Senior Software Engineer for AI startup", "created_at": "2024-01-15T10:30:45" } ], "total_count": 150, "returned_count": 50 } ``` -------------------------------- ### Basic Authentication (Username and Password) Source: https://apidocs.pearch.ai/reference/post_v1-upsert-jobs Explains how to use Basic Authentication by combining username and password into a base64-encoded string, sent in the 'Authorization' header. This is a standard HTTP authentication scheme. ```http GET /resource HTTP/1.1 Host: api.example.com Authorization: Basic ENCODED_TOKEN ``` -------------------------------- ### GET /candidate-profile Source: https://apidocs.pearch.ai/reference/post_v2-search Retrieves a structured candidate profile including scoring insights and professional background information. ```APIDOC ## GET /candidate-profile ### Description Retrieves a candidate's profile data, including relevance scores against specific subqueries and detailed professional attributes. ### Method GET ### Endpoint /candidate-profile ### Parameters #### Query Parameters - **profile_scoring** (boolean) - Optional - Enables relevance scoring for the candidate. - **docid_whitelist** (string) - Optional - List of document IDs to include in results. - **high_freshness** (boolean) - Optional - Forces retrieval of the most up-to-date profile data. ### Response #### Success Response (200) - **score** (integer) - Numerical relevance score (1-4). - **profile** (object) - Structured candidate profile data. - **insights** (array) - Analysis of candidate matches based on subqueries. #### Response Example { "score": 4, "profile": { "docid": "jason-tysl", "first_name": "Jason", "last_name": "Tysl", "title": "Software Engineer II", "total_experience_years": 3.5, "expertise": ["Python", "Machine Learning"] }, "insights": [ { "subquery": "software engineer", "match_level": "Exceeds Expectations", "priority": "Essential" } ] } ``` -------------------------------- ### Custom Filters for Advanced Search Source: https://apidocs.pearch.ai/reference/post_v2-search Demonstrates how to use custom filters for advanced profile searching. This example filters by specific locations and job titles, combining conditions with AND logic and options within a condition with OR logic. ```json { "custom_filters": { "locations": ["San Francisco", "New York"], "titles": ["Software Engineer", "Data Scientist"] } } ```