Run hiring from your agent.

Start here

Connect Muse, Instinct, dots, or another browser agent

1. The recruiter signs into Agent access and creates a separate one-time link or agent key. Keys expire in 24 hours by default; persistent keys are optional.
2. Share the credential only with a trusted agent in a private session. It may remain in chat history. Never place it in a search, public URL, form, or candidate message.
3. An agent with browser interaction opens the one-time link and explicitly selects Sign in as browser agent. Alternatively, it opens agent sign-in and enters the key. Opening a link alone does not consume it.
4. Verify the signed-in workspace and account before taking action. Browser access lasts up to 24 hours and ends when the key expires or is revoked. Agents cannot create new credentials or connect Google using this login.
5. Then copy the appropriate starter prompt and ask one recruitment question at a time. Confirm the complete draft, final hiring decisions, and any paid or recurring charges with the recruiter.

Public page reading in ChatGPT or Claude does not provide interactive browser login or authenticated API access. For those web assistants, connect the supported remote MCP connector first. A copied prompt cannot install a connector or grant tools.

Apply with your agent

Every public job application offers a candidate prompt. An agent with HTTP or interactive browser tools can help prepare and submit an application. Reading pages alone cannot upload files or submit; in that case, the agent can draft answers for you to paste into the form.

1. Read GET /api/public/campaigns/{slug}/agent for the role, actual questions, current form version, file limits, and JSON submission schema.
2. Gather the candidate's actual experience and chosen materials. Show the full answers and attachments for explicit approval. A confirmed=true field records the submitting agent's attestation; it is not independently verified human approval.
3. Upload approved files to POST /api/public/campaigns/{slug}/uploads, one multipart file per request. PDF/DOCX, up to 5 MB each, at most two file questions. Map the returned upload IDs to the corresponding question keys.
4. Submit to POST /api/public/campaigns/{slug}/agent-apply. Supply name, email, responses keyed by the text-question keys, files keyed by file-question keys, form_version, and boolean confirmed.
5. Only a successful 202 response with received=true confirms collection. Return its receipt reference, role, and timestamp to the candidate. This is not a screening result or an offer. A 409 duplicate creates no new application; a changed form requires a fresh review and approval.

No recruiter credential is needed. This public interface cannot read candidates, resumes, scores, or recruiter records. Existing application limits, upload expiry, file validation, and duplicate protections apply. This workflow submits an application only; follow the recruiter’s separate AI/tools policy for any assessment.

Create a role candidates can understand

Use the Job posts tab or POST /api/campaigns. A good campaign has a specific title, a short introduction followed by headings and bullet points for responsibilities, requirements, and application steps, organization and recruiter names, job-related scoring criteria, and questions that ask for evidence. The default form asks for a resume or work material, plus role-specific examples. Files are PDF/DOCX up to 5 MB; a link is the fallback if private file storage is full. You can change questions before sharing the link.

Each criterion has a name, description of evidence, relative weight, and minimum 0–5 score. Badal versions changes to live criteria; earlier reports keep their original rubric version. Short, relevant exercises are available for engineering, GTM, marketing, product, and other roles. Ask candidates for a reasonable time commitment and allow accommodations.

Browse role and assignment ideas or read the agent map to let your assistant ask setup questions.

{
  "title": "Backend Engineering Intern",
  "organization_name": "Example Studio",
  "recruiter_name": "Sam",
  "booking_url": "https://calendly.com/example-studio/interview",
  "description": "Build small APIs and explain tradeoffs.",
  "criteria": [
    {"name":"API work","description":"Shows a working API example","weight":2,"minimum_score":3},
    {"name":"Debugging","description":"Explains a concrete bug and fix","weight":1,"minimum_score":2}
  ],
  "assessment_template": "coding"
}

For exact current request schemas, see OpenAPI. Recruiters can edit their own campaign while it is live, close the public form with {"status":"closed"}, and reopen it with {"status":"active"}. Set an optional HTTPS booking_url on a role; qualified candidates receive it after assessment. Without it, the candidate stays in review for a human next step. Update the link at any time; it affects future invitations. Add assessment_spec to a create or update request for a custom exercise with title, instructions, and 1–8 response questions. Each applicant keeps the exercise version that was active when they applied.

What happens after submission

Candidate email names the organization, recruiter, and role when the recruiter has entered them. It gives the next step or a clear update. Humans can inspect uncertain reports and make the final decision. Failed background work stays visible for retry.

Reports & analytics

The Candidates tab shows a filterable table and a detailed report for each candidate. The Analytics tab summarizes applicants by stage, decisions, and conversion through the funnel. Use these counts to find where applicants stop, then adjust the form, rubric, or exercise. Numbers reflect candidates in your own roles only.

After AI credits are used, new applicants show Waiting for AI screen. Their form submissions and Stage 1 Sheet rows remain available. Once screening capacity is added, queue them from the candidate table or through POST /api/candidates/{id}/screen.

Agents can read GET /api/analytics, list campaigns and candidates, and inspect individual evaluations. They should state the rubric version and evidence behind a recommendation. An AI score is decision support; ask the recruiter before recording a final keep or reject decision.

Work from ChatGPT, Claude, or Codex

ChatGPT Work: enable the Developer mode and Apps setup available to your plan/workspace, then create a custom MCP app with URL https://badal.work/mcp. Choose that connection in a new Work chat, sign in to Badal in the browser, and approve access. Add the MCP URL through the supported Apps setup; asking Plugin Creator to package a Codex connection can instead produce a 127.0.0.1 callback that needs a local Codex listener. ChatGPT’s direct connection uses a chatgpt.com callback. If a used approval page says “invalid or expired,” start a fresh connection instead of submitting the same form again. Your API key stays out of the chat. Developer mode availability can depend on workspace policy. OpenAI connection guide.

Other MCP clients: connect https://badal.work/mcp and store a Badal agent key in the client’s private credential settings as Authorization: Bearer <key>. ChatGPT Work’s native plugin still uses the browser OAuth approval above.

Direct HTTP agents: store an agent API key privately and call the HTTP API. Read the agent map and OpenAPI before writing. A downloadable Badal skill is available for agent harnesses that support skills. Connected apps appear in Agent access, where you can revoke them. To let an agent record a final keep or reject decision, open that candidate’s report and approve that exact action in Badal; approval expires after 10 minutes.

Help me run hiring with Badal at https://badal.work.
Read https://badal.work/llms.txt and https://badal.work/docs.
Connect https://badal.work/mcp if your app supports MCP. In ChatGPT Work, let me authorize in my browser; in another client, use a Badal agent key from its private credential store.
Ask me one question at a time for missing organization, recruiter, role,
candidate materials, screening criteria, cross questions, assignment,
and an optional Calendly or Google booking link. Use details I already gave you.
Draft the role for my review, create it with the connected tool,
show its public form, and explain reports with source evidence.
Ask before a final keep or reject decision.

Claude Web: connect once, then recruit in chat

Claude Web and Claude Code use different setup paths. For claude.ai, use a remote MCP connector with OAuth, not a local skill helper or an API key pasted into chat.

1. In Claude, open Customize → Connectors, choose + → Add custom connector, and enter https://badal.work/mcp.
2. Add the connector, choose Connect, sign in to Badal in the browser, and approve the requested permissions. Tokens are managed through the connector; do not put credentials in chat.
3. Enable Badal for the conversation through the chat’s + menu → Connectors. Ask it to verify the account and list your roles before creating anything.
4. Copy the Claude Web starter request from Badal. Review the job draft, then approve publication. Confirm final hiring decisions and payment actions separately.

Anthropic currently documents custom connectors across Free, Pro, Max, Team and Enterprise; Free is limited to one custom connector. Organization owners must add connectors for Team/Enterprise first. Availability and labels can change; check Anthropic’s current guide. Badal supports OAuth and refresh tokens, but a completed connection must still be verified in the actual Claude client.

ChatGPT Web: check workspace capabilities first

Use the custom MCP app setup available under ChatGPT Apps and approve Badal’s OAuth connection. OpenAI currently documents full read/write MCP for Business and Enterprise/Edu; Pro custom MCP access is read/fetch only. Organization permissions also apply. Do not promise publication from a read-only connection. See OpenAI’s current guide.

What happens after connection?

The chat app invokes Badal’s tools as needed and attaches the authenticated token. Badal runs screening, email and Sheet jobs on its server after an approved action, so the conversation does not have to remain open for those jobs. Routine token refresh should not require another login; revoked or expired access may require reconnecting. A skill teaches a workflow but cannot supply tools that the host does not expose.

If the connector is unavailable, draft the role in chat and use Badal’s workspace to publish and review. Badal’s MCP final-decision approval remains a separate dashboard step. Public docs and copied prompts never grant account access.

Install Badal Recruiter

A reusable skill guides your agent through role setup, application questions, assignments, candidate reports, and final decisions. It asks one question at a time, reads Badal’s current documentation and role library, and shows a draft before creating a job post.

Download the skill package · Read the instructions · Detailed recruiter workflow

Codex and Claude Code

Extract the package so that badal-recruiter/SKILL.md sits inside the personal skills folder below. Keep the package’s scripts and references alongside it. If you have customized an older copy, back it up before replacing it.

Start a new session after installing. Ask: “Use badal-recruiter to help me hire. Ask one question at a time.”

Connect with a one-time link

1. Sign in to Badal → Agent access. Enter an agent name and choose Create connection link.
2. In a trusted local Codex or Claude Code chat where the skill helper can run, you may paste the link directly and ask the agent to redeem it immediately. The link remains in that chat history. For a more private route, run the connect command above and paste it at the hidden terminal prompt. Never put the link in a shell argument, web search, or candidate message.
3. The helper redeems the link once and saves the issued credential privately on that machine. It prints only safe status information. Verify your account using request GET /api/me before making changes.

Connect with a manual key

For access that persists across sessions, create a Manual API key in Agent access. It appears only once and stays valid until revoked. Run python3 ~/.agents/skills/badal-recruiter/scripts/badal.py connect-key locally (for Claude Code, use ~/.claude/skills/) and enter the key at its hidden prompt. The helper checks the key against Badal, then saves it in the same private local credential store. Do not paste a permanent key into chat. Use a separate named key for each device or agent environment and revoke it in Agent access when no longer needed.

Opening or previewing a connection link does not redeem it. Revoking a connection removes both the unused link and any credential issued through it. Either credential grants your existing recruiter API permissions for your own workspace; it cannot create more credentials. The skill asks before final decisions, and the MCP final-decision tool additionally requires dashboard approval.

ChatGPT Web

Use the recruiter instruction file as guidance and connect Badal through the supported MCP flow. A skill file does not install an HTTP runtime or grant account access. The connection helper works only in a trusted environment that can run Python and make private HTTPS requests. Do not ask ChatGPT to fetch the private link through web search.

Connection API

Signed-in browser sessions create and revoke links with POST /api/agent-connections and DELETE /api/agent-connections/{id}. Metadata is available from GET /api/agent-connections. The helper sends POST /api/agent-connections/redeem with a JSON token value from the link fragment. The response contains a credential once; both MCP bearer authentication and REST X-Admin-Key authentication enforce its expiry. Read OpenAPI for exact schemas and the connection reference for recovery steps.

What your agent can do

Once Badal is connected, ChatGPT’s MCP tools and the Codex/Claude Code skill cover the same day-to-day hiring work. The agent should ask one question at a time, show the complete role before publishing, and state what actually happened after each action.

The agent map, OpenAPI schema, and MCP tools/list give agents the current contract. Screening, email, and Sheet sync can be queued; check status before claiming completion. A booking invitation does not prove that a slot was booked.

Muse, Instinct, and other agents

Badal exposes the same hiring service to any agent host with suitable tools. Start with the public JSON capability manifest, service guide, and API contract. These are service facts and optional workflow guidance. They do not override a recruiter’s instructions or grant account access.

Muse by Meta and Instinct: use the connection method your host actually exposes. Badal does not claim a native connector, automatic installation, or that every agent plan supports MCP. Credentials belong in the host’s private credential storage. Create an agent key or temporary connection link in Agent access.

Recruiting workflow

Verify the connected account, gather missing role details one question at a time, review the job post and assessment draft, then publish through an authorized tool. Return the public application link. Read candidate evidence and scores, inspect analytics, and verify asynchronous jobs rather than assuming an email was delivered. Final keep/reject decisions require recruiter approval; MCP also requires a separate approval in Badal’s candidate report. Paid processing and recurring card charges require explicit consent.

Google Sheets must be connected by the recruiter in the workspace. Interviews use the recruiter’s booking link. Badal does not schedule calendar events. Public discovery contains no candidate records or credentials.

Agent API keys

For generic MCP clients, direct HTTP agents, and a persistent local Badal Recruiter skill connection, create a key in the Agent access tab after signing in. A new key is displayed once; save it in the client’s private credential store. Codex and Claude Code can run the skill helper’s connect-key command and enter the key at its hidden prompt. Never paste a permanent key in agent chat. ChatGPT Work’s native plugin uses the MCP browser authorization above instead. The key grants access to that recruiter’s roles and candidate records. You can view key labels and creation dates, then revoke a key from the same tab. A revoked key stops working.

curl https://badal.work/api/me \
  -H 'X-Admin-Key: YOUR_PRIVATE_KEY'

For MCP, configure Authorization: Bearer <key> on https://badal.work/mcp. Direct HTTP /api calls use X-Admin-Key. Keep keys out of shared prompts, candidate forms, URLs, and source control. Browser sign-in uses a secure session cookie.

Connect Google Sheets

Google sign-in opens your recruiter workspace. Granting Sheets access also lets Badal create a spreadsheet for each role, with tabs for application screening, assessment, and interview. The spreadsheet mirrors Badal’s candidate stages; Badal remains the source of truth. If you skip Sheets permission during sign-in, open Integrations later and choose Connect Google Sheets.

For interviews, enter an HTTPS Calendly, Google Calendar appointment schedule, or similar booking page in the role wizard or campaign settings. After a qualifying assessment, Badal emails that link to the candidate. The candidate books directly with your provider. Badal does not read your availability, create calendar events, or confirm when a slot is booked. Without a booking link, qualified candidates wait in review for you to decide the next step.

1. In Google Cloud Console, create or select a project and enable the Google Sheets API.
2. Configure the Google Auth Platform branding and audience. Set app name Badal, support email, and badal.work as an authorized domain. Add test users while the app is in Testing.
3. Create an OAuth Web application client. Add https://badal.work/api/google/callback as an authorized redirect URI and https://badal.work as an authorized JavaScript origin if requested.
4. Provide the client ID and secret privately for GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Set GOOGLE_REDIRECT_URI=https://badal.work/api/google/callback.
5. In Badal Integrations, choose Connect Google Sheets and complete consent. Existing connections may need to reconnect if the requested scopes changed.

Google references: OAuth web server flow and Sheets creation.

AI credits and Stripe checkout

Forms, resume collection, and Stage 1 Google Sheets sync remain free. Your first 10 candidate screenings are free. Choose $5 for 25 candidates ($0.20 each), $50 for 278 (about $0.18 each), or $500 for 3,334 (about $0.15 each), including the later assessment. Larger packs round credits up. Open Credits to see your balance and the current offer.

Checkout runs on Stripe. Credits appear only after payment is verified. You may choose automatic top-ups using your chosen pack while candidates are waiting and your credits are exhausted; this authorizes later saved-card charges. It is off by default. Use the On/Off switch in Credits; enabling requires a saved-card authorization or opens Stripe to authorize one. Select a reload pack and explicitly approve its price; changing packs does not immediately charge your card. It can be disabled anytime. A failed charge stops automatic retries and asks you to complete payment. Test mode is marked clearly and does not charge real money.

Agents can use GET /api/billing and POST /api/billing/checkout (or the matching MCP tools) to show you the live offer and checkout link. They must ask before enabling automatic top-up or queuing waiting applicants. Card information never belongs in agent chat or candidate forms.

Email updates and delivery status

Applicants receive an application receipt, assessment invitation and submission receipt, interview booking link when invited, and a polite final decision update. Each message identifies the role and organization and includes a relevant action. Replies to applicant emails go to the recruiter’s account email.

Recruiters receive job-live and closed notices, hourly new-application summaries, review and assessment updates, low-credit alerts, and verified payment or auto-reload confirmations. Manage hiring updates and credit alerts in Integrations → Email updates. Sign-in and payment confirmations are service messages and remain enabled.

Agents can use GET/PATCH /api/notification-preferences and GET /api/notifications?page=1&page_size=10, or MCP tools get_notification_preferences, update_notification_preferences, and list_notifications. History supports 10, 25, or 50 entries per page. Delivered means the provider accepted the request; it does not prove inbox delivery or that a recipient opened the email. Failed attempts retain a private error type and retry up to three times. Emails have no tracking pixels.

API reference

OpenAPI schema is the exact machine-readable contract. Interactive API reference is available for inspecting endpoints. These are the routes an agent uses most often:

Candidate forms are public; never include your API key in their URL or payload. Expect validation errors for missing role details, 401 for an invalid key, and 429 if the campaign daily application limit is reached. The 10-screening AI limit does not close the form. Background screening and email are asynchronous, so read candidate status again after submission.

Common questions

Google Analytics and Ads measurement

Marketing measurement is optional and requires visitor consent. Badal sends public marketing page views and confirmed recruiter signup, allowlisted recruiter activities, or live Stripe purchase conversions; candidate forms and hiring data are excluded. Operators configure GA4 and Ads tag IDs on the server. Disable Enhanced measurement in the GA4 Web stream to keep events limited to this explicit tracking plan. This does not grant agents permission to spend on advertising.

Screening credit balances and payment records in the authenticated API remain the source of truth. Google measurement omits visitors who decline consent.

Google consent mode guide · GA4 explicit pageviews