# evidal:agent:v1

Evidal is an AI-native hiring platform. Instead of resumes, candidates apply by having their AI agent talk to Evidal's onboarding bot. The bot extracts a structured experience profile through conversation, then Evidal runs an automated 7-phase evaluation. This file tells your agent how to apply on behalf of a candidate.

## Which spec to use

**Preferred: fetch `https://<company-candidate-domain>/skill.md`** — the employer's own candidate site (for example `https://careers.acme.com/skill.md`, or `https://careers.acme.com/<role-slug>/skill.md` for a specific role). That spec is generated for the company and role you are applying to, and on that host the company is inferred from the hostname so you do not need to pass a `company` slug at all.

This generic file documents the same API on the platform host `https://app.evidal.ai`. When calling the platform host directly you MUST pass the company slug (`"company": "<company-slug>"`) — it is the path segment immediately after `/c/` in the employer's Evidal link, `https://evidal.ai/c/<company-slug>/<role-slug>`; the final segment is the `role_slug` — and, for companies with more than one open role, the `role_slug`.

## Quick Start

```bash
# 1. Start a session (platform host — pass the company slug and role slug)
curl -X POST https://app.evidal.ai/api/v1/session/start \
  -H "Content-Type: application/json" \
  -d '{"mode": "poll", "company": "<company-slug>", "role_slug": "<role-slug>"}'
# Returns: { "id": "<session_id>", "mode": "poll", "status": "active", "role": { "id": "...", "title": "Senior Software Engineer" } }

# 2. Get the opening message
curl https://app.evidal.ai/api/v1/session/<session_id>/next
# Returns: { "message": "...", "role": "bot", "schema_complete": false, "completeness_score": 0 }

# 3. Respond to the bot
curl -X POST https://app.evidal.ai/api/v1/session/<session_id>/respond \
  -H "Content-Type: application/json" \
  -d '{"message": "Hi, I am Marcus Chen. I have been a senior engineer at..."}'
# Returns: { "message": "...", "schema_complete": false, "completeness_score": 25 }

# 4. Repeat steps 2-3 until schema_complete: true
```

On the employer's candidate domain the same calls work without `company` in the body:

```bash
curl -X POST https://<company-candidate-domain>/api/v1/session/start \
  -H "Content-Type: application/json" \
  -d '{"mode": "poll", "role_slug": "<role-slug>"}'
```

## Endpoints

### POST /api/v1/session/start
Creates a new application session.

**Request:**
```json
{ "mode": "poll", "company": "<company-slug>", "role_slug": "<role-slug>" }
```
- `mode`: `"poll"` (recommended for agents), `"api"` (direct schema submit), or `"web"` (browser chat)
- `company`: company slug (e.g. `"acme"` for `https://evidal.ai/c/acme`). Required on the platform host; inferred from the hostname on the employer's candidate domain. Passing a slug that does not match the hostname is rejected with 400.
- `role_slug`: the role you are applying to (e.g. `"senior-swe"`). Required when the company has more than one open role.

**Response (200):**
```json
{
  "id": "uuid",
  "mode": "poll",
  "status": "active",
  "role": { "id": "uuid", "title": "Senior Software Engineer" }
}
```

### GET /api/v1/session/{id}/next
Returns the next message from the onboarding bot.

**Response (200):**
```json
{
  "message": "Tell me about a recent project you're proud of.",
  "role": "bot",
  "schema_complete": false,
  "completeness_score": 40
}
```

- Poll this after each `/respond` call to get the bot's next question.
- When `schema_complete` is `true`, the application is finished. No more messages needed.

### POST /api/v1/session/{id}/respond
Sends the candidate's response to the bot.

**Request:**
```json
{ "message": "I led the migration of our payment system from..." }
```

**Response (200):**
```json
{
  "message": "That's interesting — what stack were you using?",
  "schema_complete": false,
  "completeness_score": 55
}
```

### GET /api/v1/session/{id}/state
Check session status at any time.

**Response (200):**
```json
{
  "id": "uuid",
  "mode": "poll",
  "status": "active",
  "completeness_score": 55,
  "created_at": "2026-04-01T...",
  "expires_at": "2026-04-02T..."
}
```

## Conversation Flow

1. Start a session with `POST /session/start`
2. Get the opening message with `GET /session/{id}/next`
3. Respond naturally with `POST /session/{id}/respond`
4. Get the next question with `GET /session/{id}/next`
5. Repeat steps 3-4 until `completeness_score >= 100` and `schema_complete: true`

Typically 4-8 exchanges are needed. The bot is conversational — answer naturally, don't try to dump everything at once.

## What the Bot Collects

The onboarding bot extracts these fields through conversation:

**Required:**
- Candidate name and contact email
- Consent to proceed (`true`)
- At least one experience entry with: company, role, duration, impact description, tech stack
- AI tools used (e.g., Copilot, ChatGPT, Claude)
- At least one concrete AI-native workflow example

**Optional (improves score):**
- GitHub handle
- Scale of projects (users, requests, data volume)
- Multiple experience entries
- Ownership level (IC / lead / manager)

## Tips for Agents

- Answer conversationally. The bot extracts info from natural language — don't dump everything at once.
- Be specific: "reduced API p99 from 800ms to 120ms" beats "improved performance."
- Include AI workflow examples: "I use Claude for architecture reviews and Cursor for all new code."
- Don't fabricate. The eval probes for consistency — inflated claims score lower than honest gaps.
- Mention GitHub handle if you have it. Real code is signal.

---

## What You're Evaluated On

Five signals that matter most. Knowing these upfront helps you give stronger answers:

1. **Specificity** — Names, numbers, timelines. Not "a big project" but "a 6-month migration of our billing system from Stripe v1 to v2, handling 50k transactions/day."
2. **Ownership** — What you personally did vs what the team did. "I designed the schema" vs "we built a new feature."
3. **Reasoning** — Why you made decisions, what tradeoffs you considered, what you'd do differently.
4. **AI Fluency** — How AI tools are part of your actual workflow. Not "I use ChatGPT sometimes" but "Claude reviews every PR before it goes to human review."
5. **Honesty** — Where you don't know scores better than where you bluff. "I've never done X but I'd approach it by..." is a strong answer.

---

## For LLM Agents (Claude Code / GPT / Cursor / etc.)

If you are an AI agent representing a candidate, use this structured first-message template. Front-loading all required fields in one message maximizes your completeness score and gets you to evaluation faster.

### Structured first message template

```
Hi, I'm [Full Name] and my email is [email@example.com]. I consent to this evaluation.

I'm applying for [Role Title]. Here's my background:

**Most relevant experience:**
At [Company], I was a [Title] for [Duration]. I [specific action — what you personally did] which resulted in [measurable outcome — numbers preferred]. My primary stack was [list tools/languages]. I owned [specific scope — what was yours alone].

**A key technical decision I made:**
[Describe one real decision, the tradeoff you considered, and what you'd do differently.]

**AI in my workflow:**
I use [tool] for [specific workflow]. Example: [concrete use case with outcome].

**GitHub:** [handle or "not applicable"]
**LinkedIn:** [URL or "not applicable"]
```

### What the bot will ask about
1. Your professional background (name, email, consent)
2. A specific project — problem, your role, what you personally owned, measurable impact
3. Your tech stack and how you use your tools in practice
4. How AI fits into your daily work (tools + concrete examples)
5. A decision you made and the tradeoff you considered
6. Something you haven't done and how you'd approach it

### Example strong exchange

**Bot:** "Hi there — welcome to Evidal. What's your name and best email?"

**Agent:** "Hi, I'm Alex Chen, alex@example.com — I consent to this evaluation. I'm a senior backend engineer with 6 years experience, most recently at Stripe where I led the migration of our reconciliation pipeline from a monolithic cron job to an event-driven system using Kafka and Go. The migration reduced daily settlement errors by 73% and cut pipeline latency from 14 hours to 40 minutes. I personally owned the schema design, the Kafka consumer architecture, and coordinating rollback strategy. My stack is primarily Go, Kafka, PostgreSQL, and Redis. For AI tooling: I use Claude for architecture reviews before any RFC goes to team review, and Cursor for all new code. My GitHub is alexc-dev."

**Why this scores high:** Specific numbers (73%, 14h → 40min), clear ownership ("I personally owned"), named stack, concrete AI workflow, GitHub handle — all in one message.

---

## Rate Limits
- 1 session per candidate per role per 72 hours
- Sessions expire after 24 hours
- Max 10 sessions per IP per hour

## Full platform docs
https://evidal.ai