{"openapi":"3.1.0","info":{"title":"HireDirector Jobs API","version":"1.0.0","summary":"Search the open jobs listed on HireDirector (India).","description":"Free, read-only access to the open jobs on HireDirector: search by keywords, place, category, job type, work mode, experience and pay, and read full job details. No authentication. Every job links to its page and to a free application form (no account needed). Jobs with hiring.type = agency are recruited by HireDirector for client employers whose names are confidential: describe them that way, never as a named company. Rate limit: 120 requests a minute per client IP.","contact":{"name":"HireDirector","url":"https://hiredirector.com/contact"},"termsOfService":"https://hiredirector.com/terms-of-service"},"servers":[{"url":"https://hiredirector.com"}],"externalDocs":{"description":"Developer guide, including the MCP server","url":"https://hiredirector.com/developers"},"paths":{"/api/public/v1/jobs":{"get":{"operationId":"searchJobs","summary":"Search open jobs","description":"Search open jobs by free text or by place, category, job type, work mode, experience and minimum monthly pay. Best title matches first, then newest; 10 per page by default (per_page up to 20), up to 10 pages.","x-openai-isConsequential":false,"parameters":[{"name":"q","in":"query","required":false,"description":"Free text: a role or skills, or a whole request such as \"remote data analyst internship in Bhubaneswar\". A city, state or region; the job types internship, part-time, full-time, contract, freelance and temporary; remote/work from home or hybrid; \"fresher\"; years of experience (\"3 years\"); and minimum pay (\"above 25,000\", \"30k a month\") found in the text are applied as filters. The other words must appear in the job (title, category, summary or skills). Best in English.","schema":{"type":"string","maxLength":200}},{"name":"city","in":"query","required":false,"description":"City name. Common other spellings are accepted (Bombay = Mumbai); a state or region name searches all of its cities. Use getCatalog for the cities that have jobs.","schema":{"type":"string","maxLength":80}},{"name":"state","in":"query","required":false,"description":"State or region, e.g. to search all cities in it.","schema":{"type":"string","maxLength":80}},{"name":"category","in":"query","required":false,"description":"Job category, e.g. IT, Finance, Healthcare, Marketing, Sales. Use getCatalog for the full list; an unknown category is searched as words.","schema":{"type":"string","maxLength":80}},{"name":"job_type","in":"query","required":false,"description":"Employment type.","schema":{"type":"string","enum":["full-time","part-time","internship","contract","temporary"]}},{"name":"work_mode","in":"query","required":false,"description":"remote = work from home; onsite = at the workplace.","schema":{"type":"string","enum":["remote","hybrid","onsite"]}},{"name":"fresher","in":"query","required":false,"description":"true: only jobs open to freshers (marked fresher-friendly or asking for at most 1 year of experience).","schema":{"type":"boolean"}},{"name":"experience_years","in":"query","required":false,"description":"The candidate's years of experience; returns jobs whose experience range includes it.","schema":{"type":"number","minimum":0,"maximum":50}},{"name":"min_monthly_pay","in":"query","required":false,"description":"Minimum pay per month in INR (e.g. 25000 for ₹25,000 a month; divide a yearly figure by 12). Compares the top of each listing's advertised range, converted to monthly.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"posted_within_days","in":"query","required":false,"description":"Only jobs posted in the last N days.","schema":{"type":"integer","enum":[1,3,7,14,30]}},{"name":"page","in":"query","required":false,"description":"Results page (1–10). Use next_page from the previous response.","schema":{"type":"integer","minimum":1,"maximum":10,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1–20, default 10).","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Matching jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"Invalid parameter; the message says which values are allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Get one job in full","description":"Full details of one job: description, responsibilities, qualifications, benefits, skills, pay and the apply link. Closed jobs answer 410 with similar open jobs.","x-openai-isConsequential":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The job id from searchJobs results (the slug in the job page URL).","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetail"}}}},"404":{"description":"No job with this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The job is closed; alternatives lists similar open jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid parameter; the message says which values are allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/v1/take-home":{"get":{"operationId":"calculateTakeHome","summary":"Take-home salary from an Indian CTC","description":"Monthly in-hand pay from a yearly CTC in INR for FY 2026-27 under the new and old tax regimes (PF, professional tax, income tax). Same rules as the site's salary calculator; includes a page link.","x-openai-isConsequential":false,"parameters":[{"name":"ctc","in":"query","required":true,"description":"Yearly CTC (cost to company) in INR, e.g. 1200000 for ₹12 lakh or 12 LPA. For a monthly figure, multiply by 12.","schema":{"type":"number","minimum":10000,"maximum":100000000}},{"name":"basic_percent","in":"query","required":false,"description":"Basic pay as a percentage of CTC (default 40).","schema":{"type":"number","minimum":10,"maximum":100,"default":40}},{"name":"pf","in":"query","required":false,"description":"Provident fund: full = 12% of basic pay; capped = 12% of the ₹15,000 monthly wage ceiling (₹1,800 a month); none = no PF.","schema":{"type":"string","enum":["full","capped","none"],"default":"full"}},{"name":"employer_pf_in_ctc","in":"query","required":false,"description":"Whether the CTC includes the employer's PF contribution (default true, as in most Indian offers).","schema":{"type":"boolean","default":true}},{"name":"gratuity_in_ctc","in":"query","required":false,"description":"Whether the CTC includes gratuity (4.81% of basic pay). Default false.","schema":{"type":"boolean","default":false}},{"name":"professional_tax","in":"query","required":false,"description":"Professional tax a year in INR (default 2400; 0 in states that have none).","schema":{"type":"number","minimum":0,"maximum":2500,"default":2400}},{"name":"deductions_80c","in":"query","required":false,"description":"Old regime only: yearly 80C investments besides PF (80C is capped at ₹1.5 lakh including PF).","schema":{"type":"number","minimum":0,"maximum":150000,"default":0}},{"name":"other_deductions","in":"query","required":false,"description":"Old regime only: other yearly deductions such as 80D health insurance, HRA exemption or home-loan interest.","schema":{"type":"number","minimum":0,"maximum":10000000,"default":0}}],"responses":{"200":{"description":"Breakdown for both regimes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeHome"}}}},"400":{"description":"Invalid parameter; the message says which values are allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/v1/catalog":{"get":{"operationId":"getCatalog","summary":"List cities, categories and job types","description":"Cities, job categories, job types and work modes that have open jobs, with counts and page links. Use it to pick valid filter values.","x-openai-isConsequential":false,"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"JobSummary":{"type":"object","properties":{"id":{"type":"string","description":"Job id (its URL slug). Pass it to getJob for the full job."},"title":{"type":"string"},"hiring":{"type":"object","description":"Who is hiring. type \"agency\": the site recruits for a client employer whose name is confidential, so the job is not attributed to a named company.","properties":{"type":{"type":"string","enum":["agency","portal","employer"]},"name":{"type":"string","description":"Recruiter or employer name."},"employer":{"type":"string","description":"\"confidential\" for agency roles."},"display":{"type":"string","description":"How to name the hirer in an answer."}},"required":["type","name","employer","display"]},"location":{"type":"object","properties":{"city":{"type":["string","null"],"description":"City"},"state":{"type":["string","null"],"description":"State or region"},"country":{"type":"string"},"remote":{"type":"boolean","description":"True when the role is fully remote (work from home)."}},"required":["city","state","country","remote"]},"work_mode":{"type":["string","null"],"description":"remote, hybrid or onsite"},"job_type":{"type":["string","null"],"description":"full-time, part-time, internship, contract or temporary"},"category":{"type":["string","null"],"description":"Job category"},"salary":{"type":["object","null"],"description":"Advertised pay range; null when the listing shows none.","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string","description":"ISO 4217 code, e.g. INR"},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","yearly"]},"label":{"type":"string","description":"Display text, e.g. \"₹25,000–35,000 a month\""},"take_home":{"type":"object","description":"India only, salaried roles: estimated monthly in-hand pay after PF, professional tax and income tax (new regime), treating the advertised pay as CTC. Absent when not estimated.","properties":{"min_monthly":{"type":"integer"},"max_monthly":{"type":"integer"},"label":{"type":"string","description":"e.g. \"₹26,900–45,000 a month\""},"basis":{"type":"string"},"calculator_url":{"type":"string"}},"required":["min_monthly","max_monthly","label","basis","calculator_url"]}},"required":["min","max","currency","period","label"]},"experience":{"type":"object","properties":{"min_years":{"type":["number","null"],"description":"Minimum years asked for"},"max_years":{"type":["number","null"],"description":"Maximum years asked for"},"label":{"type":["string","null"],"description":"e.g. \"0–1 yr\", \"2–5 yrs\", \"Fresher\""},"fresher_friendly":{"type":"boolean","description":"Open to freshers (0–1 year of experience)."}},"required":["min_years","max_years","label","fresher_friendly"]},"summary":{"type":"string","description":"Short plain-text description (up to 300 characters)."},"posted_date":{"type":["string","null"],"description":"YYYY-MM-DD"},"valid_through":{"type":["string","null"],"description":"YYYY-MM-DD; the listing closes after this date"},"url":{"type":"string","description":"Job page. Link to it when mentioning the job."},"apply_url":{"type":"string","description":"Application form: free, no account needed."}},"required":["id","title","hiring","location","work_mode","job_type","category","salary","experience","summary","posted_date","valid_through","url","apply_url"]},"JobDetail":{"type":"object","properties":{"id":{"type":"string","description":"Job id (its URL slug). Pass it to getJob for the full job."},"title":{"type":"string"},"hiring":{"type":"object","description":"Who is hiring. type \"agency\": the site recruits for a client employer whose name is confidential, so the job is not attributed to a named company.","properties":{"type":{"type":"string","enum":["agency","portal","employer"]},"name":{"type":"string","description":"Recruiter or employer name."},"employer":{"type":"string","description":"\"confidential\" for agency roles."},"display":{"type":"string","description":"How to name the hirer in an answer."}},"required":["type","name","employer","display"]},"location":{"type":"object","properties":{"city":{"type":["string","null"],"description":"City"},"state":{"type":["string","null"],"description":"State or region"},"country":{"type":"string"},"remote":{"type":"boolean","description":"True when the role is fully remote (work from home)."}},"required":["city","state","country","remote"]},"work_mode":{"type":["string","null"],"description":"remote, hybrid or onsite"},"job_type":{"type":["string","null"],"description":"full-time, part-time, internship, contract or temporary"},"category":{"type":["string","null"],"description":"Job category"},"salary":{"type":["object","null"],"description":"Advertised pay range; null when the listing shows none.","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string","description":"ISO 4217 code, e.g. INR"},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","yearly"]},"label":{"type":"string","description":"Display text, e.g. \"₹25,000–35,000 a month\""},"take_home":{"type":"object","description":"India only, salaried roles: estimated monthly in-hand pay after PF, professional tax and income tax (new regime), treating the advertised pay as CTC. Absent when not estimated.","properties":{"min_monthly":{"type":"integer"},"max_monthly":{"type":"integer"},"label":{"type":"string","description":"e.g. \"₹26,900–45,000 a month\""},"basis":{"type":"string"},"calculator_url":{"type":"string"}},"required":["min_monthly","max_monthly","label","basis","calculator_url"]}},"required":["min","max","currency","period","label"]},"experience":{"type":"object","properties":{"min_years":{"type":["number","null"],"description":"Minimum years asked for"},"max_years":{"type":["number","null"],"description":"Maximum years asked for"},"label":{"type":["string","null"],"description":"e.g. \"0–1 yr\", \"2–5 yrs\", \"Fresher\""},"fresher_friendly":{"type":"boolean","description":"Open to freshers (0–1 year of experience)."}},"required":["min_years","max_years","label","fresher_friendly"]},"summary":{"type":"string","description":"Short plain-text description (up to 300 characters)."},"posted_date":{"type":["string","null"],"description":"YYYY-MM-DD"},"valid_through":{"type":["string","null"],"description":"YYYY-MM-DD; the listing closes after this date"},"url":{"type":"string","description":"Job page. Link to it when mentioning the job."},"apply_url":{"type":"string","description":"Application form: free, no account needed."},"description":{"type":"string","description":"Full plain-text job description."},"responsibilities":{"type":"array","items":{"type":"string"},"description":"What the job involves"},"qualifications":{"type":"array","items":{"type":"string"},"description":"What the candidate needs"},"benefits":{"type":"array","items":{"type":"string"},"description":"What the job offers"},"skills":{"type":"array","items":{"type":"string"},"description":"Skills the listing requires"},"skills_preferred":{"type":"array","items":{"type":"string"},"description":"Good-to-have skills; not required"}},"required":["id","title","hiring","location","work_mode","job_type","category","salary","experience","summary","posted_date","valid_through","url","apply_url","description","responsibilities","qualifications","benefits","skills","skills_preferred"]},"SearchResult":{"type":"object","properties":{"total":{"type":"integer","description":"Number of matching open jobs."},"page":{"type":"integer"},"per_page":{"type":"integer"},"has_more":{"type":"boolean"},"next_page":{"type":["integer","null"],"description":"Pass as page to get the next results; null on the last page (or after page 10)."},"criteria":{"type":"object","description":"Filters the search ran with, after reading the query (e.g. a city found in q) and any relaxing described in notes.","additionalProperties":true},"notes":{"type":"array","items":{"type":"string"},"description":"How the query was read or relaxed. Pass them on when they change the answer."},"browse_url":{"type":["string","null"],"description":"The site's own page for these results, when there is one."},"about":{"type":"string","description":"How listings on this site work, including who is hiring."},"results":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}}},"required":["total","page","per_page","has_more","next_page","criteria","notes","browse_url","about","results"]},"Catalog":{"type":"object","properties":{"total_jobs":{"type":"integer"},"newest_job":{"type":["string","null"],"description":"YYYY-MM-DD"},"cities":{"type":"array","description":"Cities with open jobs (valid values for city).","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"categories":{"type":"array","description":"Job categories with open jobs (valid values for category).","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"job_types":{"type":"array","description":"Valid values for job_type.","items":{"type":"object","properties":{"value":{"type":"string"},"jobs":{"type":"integer"}},"required":["value","jobs"]}},"work_modes":{"type":"array","description":"Valid values for work_mode.","items":{"type":"object","properties":{"value":{"type":"string"},"jobs":{"type":"integer"}},"required":["value","jobs"]}},"collections":{"type":"array","description":"Job-type pages: internships, part-time, fresher and work-from-home jobs.","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"note":{"type":"string"}},"required":["total_jobs","newest_job","cities","categories","job_types","work_modes","collections","note"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"invalid_parameter, not_found, job_closed, method_not_allowed, rate_limited or server_error"},"message":{"type":"string","description":"What went wrong and how to fix the request."},"parameter":{"type":"string","description":"The parameter at fault, for invalid_parameter."}},"required":["code","message"]},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"},"description":"Open jobs like a closed one (job_closed only)."}},"required":["error"]},"TakeHome":{"type":"object","properties":{"financial_year":{"type":"string","description":"Indian financial (tax) year the rules are for, e.g. 2026-27"},"currency":{"type":"string"},"ctc":{"type":"integer","description":"Yearly CTC"},"basic_pay":{"type":"integer","description":"Yearly basic pay"},"employer_pf":{"type":"integer","description":"Employer PF inside the CTC (yearly)"},"gratuity":{"type":"integer","description":"Gratuity inside the CTC (yearly)"},"gross_salary":{"type":"integer","description":"Yearly gross salary: CTC less employer PF and gratuity"},"employee_pf":{"type":"integer","description":"Employee PF deducted (yearly)"},"professional_tax":{"type":"integer","description":"Professional tax (yearly)"},"regimes":{"type":"object","properties":{"new":{"type":"object","properties":{"taxable_income":{"type":"integer","description":"Yearly taxable income"},"income_tax":{"type":"integer","description":"Yearly income tax including surcharge and cess"},"take_home_yearly":{"type":"integer","description":"In-hand pay for the year"},"take_home_monthly":{"type":"integer","description":"In-hand pay a month"}},"required":["taxable_income","income_tax","take_home_yearly","take_home_monthly"]},"old":{"type":"object","properties":{"taxable_income":{"type":"integer","description":"Yearly taxable income"},"income_tax":{"type":"integer","description":"Yearly income tax including surcharge and cess"},"take_home_yearly":{"type":"integer","description":"In-hand pay for the year"},"take_home_monthly":{"type":"integer","description":"In-hand pay a month"}},"required":["taxable_income","income_tax","take_home_yearly","take_home_monthly"]}},"required":["new","old"]},"better_regime":{"type":"string","enum":["new","old"],"description":"The regime that leaves more in hand with the deductions given"},"monthly_difference":{"type":"integer","description":"Difference in monthly in-hand pay between the two regimes"},"summary":{"type":"string","description":"One-sentence answer to quote"},"assumptions":{"type":"string"},"page_url":{"type":"string","description":"The site's calculator page for this CTC. Link to it in the answer."}},"required":["financial_year","currency","ctc","basic_pay","employer_pf","gratuity","gross_salary","employee_pf","professional_tax","regimes","better_regime","monthly_difference","summary","assumptions","page_url"]}}}}