# Tsenta for AI agents: Sign up and apply to jobs from your agent, over plain HTTP.

> An AI agent can create or connect a person's Tsenta account, add their résumé, apply to jobs and check that the applications went out, with curl and a Bearer token. The person reads a 6-digit code from their inbox, gives their street address and ZIP code (a résumé doesn't have them), and approves each tailored résumé unless they turn on auto-approval. A new account gets 25 free applications.

Tsenta finds jobs that fit a résumé, tailors the résumé for each one, applies through the employer's own application system and tracks every application. This page is for an agent, or the developer behind it, checking whether Tsenta works for them.

- API base: https://api.autojobs.me
- Sign up: `POST /api/v1/agent-signup/start`, then `POST /api/v1/agent-signup/verify`
- Tools: `GET /api/v1/agent/tools` lists every tool with its input schema. `POST /api/v1/agent/tools/<name>` runs one.
- MCP server: https://api.autojobs.me/api/v1/mcp, with the same access token
- OpenAPI: https://api.autojobs.me/api/v1/agent/openapi.json
- Refresh a token: `POST https://api.autojobs.me/oauth/token`
- Markdown version: https://tsenta.com/agents.md

<a id="quickstart"></a>

## Quickstart: one script, start to finish

The script below runs the whole path with curl and jq. It sends real job applications for the person, so run it only with their agreement, using their email and their résumé. It waits on the person at a few points: the code from the email, their work authorization, their street address and ZIP code when the profile has none (always the case on a new account), and a yes before it applies.

1. Starts a signup with the person's email. Tsenta emails them a 6-digit code.
2. Asks for the code, trades it for an access token and a refresh token, and saves both to `tsenta-token.json`.
3. Sends the résumé with `submit-resume` when the account has none yet or reading the last one failed, so a run after a failed one sends it again. It is JSON you extract from the person's résumé (`resume.json`, example below).
4. Polls `get-profile-status` until Tsenta has read the résumé, and prints `missingForApplication`.
5. Asks the person about their work authorization on every run and saves their answers with `set-work-authorization`.
6. Reads matches with `get-job-recommendations` and keeps 2 that Tsenta can apply to.
7. Applies to them with `apply-to-job` once the person says yes.
8. Polls `get-evaluation-summary` and prints its verdict.

`tsenta-quickstart.sh`:

```bash
#!/usr/bin/env bash
# Tsenta agent quickstart. Creates or connects the person's Tsenta account, adds
# their resume, applies to 2 jobs they approve and prints whether it worked.
# Needs curl and jq. It sends real job applications for the person, so run it
# only with their agreement.
#
#   TSENTA_EMAIL=person@example.com bash tsenta-quickstart.sh
set -euo pipefail

API="https://api.autojobs.me"
EMAIL="$TSENTA_EMAIL"              # the person's email: the code goes there
AGENT_NAME="My job search agent"   # the name the person sees for this connection
RESUME_JSON="resume.json"          # the person's resume as JSON (example below)
[ -f "$RESUME_JSON" ] || { echo "Write the person's resume to $RESUME_JSON first." >&2; exit 1; }

TMP=$(mktemp); trap 'rm -f "$TMP"' EXIT

# post PATH JSON [CURL ARGS]: print the response body, and fail on an HTTP error.
post() {
  local route="$1" body="$2" code; shift 2
  code=$(curl -sS -o "$TMP" -w '%{http_code}' -X POST "$API$route" \
    -H "Content-Type: application/json" "$@" -d "$body") || return 1
  cat "$TMP"
  if [ "$code" -ge 400 ]; then echo "HTTP $code from $route: $(cat "$TMP")" >&2; return 1; fi
}

# tool NAME JSON: run one Tsenta tool and print its result.
tool() { post "/api/v1/agent/tools/$1" "$2" -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.result'; }

# yn QUESTION: ask until the person answers yes or no, and print true or false.
yn() {
  local answer
  while read -r -p "$1 [y/n] " answer; do
    case "$answer" in
      [Yy] | [Yy][Ee][Ss]) echo true; return ;;
      [Nn] | [Nn][Oo]) echo false; return ;;
    esac
    echo "Please answer y or n." >&2
  done
  return 1   # no more input
}

# 1. Start the signup. Tsenta emails the person a 6-digit code (valid 10 minutes).
START=$(post /api/v1/agent-signup/start "$(jq -n --arg email "$EMAIL" --arg agent "$AGENT_NAME" \
  '{email: $email, agent_name: $agent}')")
SIGNUP_ID=$(jq -r .signup_id <<<"$START")
echo "Code sent to $(jq -r .sent_to <<<"$START")."

# 2. Ask the person for the code and trade it for tokens. 5 tries in all.
while true; do
  read -r -p "6-digit code from the email: " CODE
  BODY=$(jq -n --arg id "$SIGNUP_ID" --arg code "$CODE" '{signup_id: $id, code: $code}')
  if TOKENS=$(post /api/v1/agent-signup/verify "$BODY"); then break; fi
  case $(jq -r .error <<<"$TOKENS") in wrong_code|invalid_code) ;; *) exit 1 ;; esac
done
(umask 077; echo "$TOKENS" > tsenta-token.json)   # holds the refresh token: keep it private
ACCESS_TOKEN=$(jq -r .access_token <<<"$TOKENS")
ACCOUNT=$(jq -r .account <<<"$TOKENS")             # "created" or "existing"
echo "Signed in to a $ACCOUNT account."

# 3. Send the resume you extracted unless the account already has one Tsenta read.
#    Decided from the profile, not from "created", so a run after a failed one
#    (or on a web account that never added a resume) sends it too.
STATUS=$(tool get-profile-status '{}')
if jq -e '.profileExtractionStatus != "processing" and (.profileExtractionStatus == "failed" or
  (.hasResume | not) or any(.missingForApplication[]; .field == "profile"))' <<<"$STATUS" >/dev/null; then
  tool submit-resume "$(jq '{resumeData: .}' "$RESUME_JSON")"
  STATUS=$(tool get-profile-status '{}')
fi
# 4. Tsenta reads it in the background (usually 30 to 60 seconds), then makes a PDF.
for _ in $(seq 60); do
  jq -e '.profileExtractionStatus != "processing" and
    (.profileExtractionStatus != "completed" or .hasResume)' <<<"$STATUS" >/dev/null && break
  sleep 10
  STATUS=$(tool get-profile-status '{}')
done
jq '{profileExtractionStatus, profileExtractionError, missingForApplication}' <<<"$STATUS"
[ "$(jq -r .profileExtractionStatus <<<"$STATUS")" != failed ] || exit 1

# 5. Work authorization comes from the person: application forms ask it. A new
#    profile starts at "authorized in the US, no sponsorship", and a stored answer
#    may be that guess, so ask on every run. Other saved answers stay as they are.
#    For another country, pass its ISO code as countryCode.
AUTH=$(yn "Is the person authorized to work in the US?")
SPONSOR=$(yn "Will they need visa sponsorship, now or later?")
tool set-work-authorization "$(jq -n --argjson a "$AUTH" --argjson s "$SPONSOR" \
  '{countryCode: "US", isAuthorizedToWork: $a, needsSponsorship: $s}')"
# A resume never has the street address or ZIP code, and applications need them.
# Ask the person and save their own answers with set-personal-info.
STATUS=$(tool get-profile-status '{}')
if jq -e 'any(.missingForApplication[]; .field == "personalInformation.address" or
  .field == "personalInformation.zipCode")' <<<"$STATUS" >/dev/null; then
  read -r -p "The person's street address: " ADDRESS
  read -r -p "Their ZIP or postal code: " ZIP
  tool set-personal-info "$(jq -n --arg a "$ADDRESS" --arg z "$ZIP" '{address: $a, zipCode: $z}')" >/dev/null
  STATUS=$(tool get-profile-status '{}')
fi
# Anything still listed blocks applying. Set a missing phone with
# set-personal-info and other answers with set-application-preferences, always
# with the person's own answers.
jq -r '.missingForApplication[] | "Still missing: \(.label)"' <<<"$STATUS"

# 6. Read matching jobs and keep the top 2 that Tsenta can apply to.
JOBS=$(tool get-job-recommendations '{"limit": 20}')
PICKS=$(jq -c '[.jobs[] | select(.isSupportedAts)] | .[:2]' <<<"$JOBS")
[ "$(jq length <<<"$PICKS")" -gt 0 ] || { jq '{zeroResultReason, activeFilters}' <<<"$JOBS"; exit 1; }
jq -r '.[] | "- \(.title) at \(.companyName), match \(.matchScore)"' <<<"$PICKS"

# 7. Apply if the person says yes. Each queued application uses 1 from the account.
[ "$(yn "Apply to these jobs for the person?")" = true ] || exit 0
# A new account holds each tailored resume for the person to approve, so nothing
# is sent until they do. Their choice: send tailored resumes without asking.
if [ "$(yn "Send tailored resumes without the person approving each one?")" = true ]; then
  tool set-apply-preferences '{"autoApproveResume": true}' >/dev/null
fi
APPLY_BODY=$(jq -c '{jobIds: map(.id)}' <<<"$PICKS")
APPLY=$(tool apply-to-job "$APPLY_BODY")
jq -r '.summary, (.results[] | "- \(.companyName // "job"): \(.message)")' <<<"$APPLY"
if jq -e 'any(.results[]; .missingFields)' <<<"$APPLY" >/dev/null; then
  # The message above has a sign-in link to the person's Tsenta profile
  # (profileUrl). It signs them in, so give it only to them.
  read -r -p "Once the person has filled in the missing fields there, press Enter. "
  APPLY=$(tool apply-to-job "$APPLY_BODY")
  jq -r '.summary, (.results[] | "- \(.companyName // "job"): \(.message)")' <<<"$APPLY"
fi

# 8. Check the result once nothing is tailoring, queued or sending (20 minutes at most).
for _ in $(seq 80); do
  SUMMARY=$(tool get-evaluation-summary '{}')
  jq -e '.applications.counts | .tailoring + .queued + .sending == 0' <<<"$SUMMARY" >/dev/null && break
  sleep 15
done
jq -r '.verdict, (.nextSteps[]? | "- \(.)")' <<<"$SUMMARY"
echo "Applications that need review wait for the person: https://tsenta.com/agents#review"
```

Run it as `TSENTA_EMAIL=person@example.com bash tsenta-quickstart.sh` in a terminal where someone can answer its questions. An agent whose shell can't answer prompts can send the same requests one at a time, as shown under [Without the script](#by-hand).

On a new account, expect the verdict to say the applications need review: each tailored résumé waits for the person's approval, as described under [Check every application before it is sent](#review).

<a id="resume-json"></a>

## resume.json: the résumé as submit-resume takes it

Read the person's résumé yourself, from a PDF, pasted text or a LinkedIn profile, and write it in this shape. Keep every key, with null or an empty list when the résumé has nothing for it. The full schema is under `submit-resume` in `GET /api/v1/agent/tools`. This example is made up, so never send it for a real person.

`resume.json`:

```json
{
  "validation": {
    "isValidResume": true,
    "invalidReason": null,
    "documentType": null
  },
  "personalInfo": {
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "jordan.lee@example.com",
    "phone": "4155550123",
    "phoneCountryCode": "1",
    "city": "San Francisco",
    "state": "CA",
    "country": "United States",
    "website": null,
    "githubUrl": "https://github.com/jordanlee",
    "linkedinUrl": "https://www.linkedin.com/in/jordanlee"
  },
  "headline": null,
  "summary": "Backend engineer with 4 years of experience building payment services in Go and Python.",
  "workExperience": [
    {
      "company": "Acme Payments",
      "role": "Software Engineer",
      "location": "San Francisco, CA",
      "startDate": "Jun 2022",
      "endDate": "Present",
      "isCurrentRole": true,
      "responsibilities": [
        "Built the refunds service in Go, handling 2 million requests a day",
        "Cut p95 checkout latency from 900 ms to 300 ms"
      ],
      "technologies": [
        "Go",
        "PostgreSQL",
        "Kafka"
      ]
    }
  ],
  "projects": [],
  "education": [
    {
      "degree": "Bachelor of Science",
      "major": "Computer Science",
      "minor": null,
      "university": "University of California, Davis",
      "startDate": "2017",
      "endDate": "2021",
      "gpa": null
    }
  ],
  "skillCategories": [
    {
      "id": "skills",
      "name": "Skills",
      "skills": [
        "Go",
        "Python",
        "PostgreSQL",
        "AWS"
      ],
      "order": 0
    }
  ],
  "certifications": [],
  "additionalSections": []
}
```

Job dates need a month and a year ("Jun 2022") or "Present". Education dates can be a year. The phone is digits only, with the country code in `phoneCountryCode`. Tsenta keeps the email the account signed up with, not the one on the résumé.

<a id="by-hand"></a>

## Without the script: the signup requests

Start the signup. `name` is optional and only used for a new account.

```bash
curl -sS -X POST https://api.autojobs.me/api/v1/agent-signup/start \
  -H "Content-Type: application/json" \
  -d '{"email": "person@example.com", "agent_name": "My job search agent", "name": "Jordan Lee"}'
# {"signup_id": "as_...", "sent_to": "p...@example.com", "expires_in": 600, "next": "..."}
```

The response is the same whether or not the email already has an account. For an existing account, the code goes to the address on file. Then send the code the person reads you:

```bash
curl -sS -X POST https://api.autojobs.me/api/v1/agent-signup/verify \
  -H "Content-Type: application/json" \
  -d '{"signup_id": "as_...", "code": "482913"}'
```

```json
{
  "account": "created",
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "client_id": "...",
  "mcp_url": "https://api.autojobs.me/api/v1/mcp",
  "tools_url": "https://api.autojobs.me/api/v1/agent/tools",
  "openapi_url": "https://api.autojobs.me/api/v1/agent/openapi.json",
  "token_url": "https://api.autojobs.me/oauth/token",
  "docs_url": "https://tsenta.com/agents",
  "next_steps": ["..."]
}
```

`account` is `created` for a new account and `existing` when the email already had one. For an existing account, call `get-evaluation-summary` first: it may already have a résumé and applications. Keep `refresh_token` and `client_id` private, like a password.

<a id="tool-calls"></a>

## Calling a tool

Every tool the Tsenta MCP server offers is also a plain HTTP endpoint. POST the tool's input as the JSON body (`{}` when it takes none), with the access token as a Bearer token. The tool's output is under `result`.

```bash
# List the tools, with each one's input schema
curl -sS https://api.autojobs.me/api/v1/agent/tools \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.tools[] | {name, read_only}'

# Run one: the JSON body is the tool's input
curl -sS -X POST https://api.autojobs.me/api/v1/agent/tools/get-profile-status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{
  "tool": "get-profile-status",
  "ok": true,
  "result": {
    "profileExtractionStatus": "completed",
    "hasResume": true,
    "missingForApplication": [
      { "field": "personalInformation.address", "label": "Address", "section": "personal" },
      { "field": "personalInformation.zipCode", "label": "Zip Code", "section": "personal" }
    ]
  }
}
```

`GET /api/v1/agent/tools` returns each tool's `name`, `description`, `input_schema` (JSON Schema), `read_only` and `destructive`. Read it instead of guessing inputs: a body that doesn't match comes back as 400 `invalid_input` with an `issues` list. The [OpenAPI document](https://api.autojobs.me/api/v1/agent/openapi.json) describes the signup, tool and token endpoints.

Tool calls run with the same permissions, limits and checks as the MCP server. A tool that runs and refuses returns 422 `tool_error` with `ok: false` and a plain `message`. Some tools report a problem inside a 200 result instead: `apply-to-job` lists each job with `success` and `message`, and returns `remainingBalance`.

<a id="mcp"></a>

## Use MCP instead

The same access token works as a Bearer token on the MCP server, `mcp_url` in the verify response, so an agent that speaks MCP gets the same tools. In Claude Code:

```bash
claude mcp add --transport http tsenta "$(jq -r .mcp_url tsenta-token.json)" \
  --header "Authorization: Bearer $(jq -r .access_token tsenta-token.json)"
```

A header keeps the token it was given, and access tokens last an hour. When it expires, refresh it, then remove the server (`claude mcp remove tsenta`) and add it again. Or connect with OAuth, which signs in through the browser and refreshes on its own: see [the MCP setup guide](https://tsenta.com/mcp).

<a id="review"></a>

## Check every application before it is sent

Two separate controls let the person see what Tsenta prepared before an employer gets it. Both reviews belong to the person: show them what Tsenta prepared and act on their answer, never on your own judgment.

### Résumé review

A new account starts with resume auto-approval off. After Tsenta tailors the résumé for a job, the application waits as `PENDING_RESUME_REVIEW` (counted as `needsReview` by `get-evaluation-summary`), and nothing is sent. Get a link to the tailored résumé, show it to the person, and approve only after they say yes:

```bash
# With the script's tool function. APP_ID comes from apply-to-job or list-applications.
tool list-applications '{"filter": "needs"}'
tool get-application-status '{"applicationId": "APP_ID", "include": ["resumePdfUrl"]}'
# Only after the person has read the resume and said yes:
tool approve-application '{"applicationId": "APP_ID"}'
```

The résumé link expires 5 minutes after the call. If the person would rather have applications sent without reading each résumé, they can turn auto-approval on: `set-apply-preferences` with `{"autoApproveResume": true}`.

### Form review (review before submit)

With review before submit on, Tsenta fills the employer's form and stops before the final submit, as `PENDING_SUBMIT_REVIEW`. Read every filled answer with `get-application-review`, show it to the person, then send their decision with `submit-application-review`:

```bash
tool set-apply-preferences '{"reviewBeforeSubmit": true}'
# Later, for an application waiting as PENDING_SUBMIT_REVIEW:
tool get-application-review '{"applicationId": "APP_ID"}'
# Send it with the person's changes, or use "decision": "reject" to skip it:
tool submit-application-review '{"applicationId": "APP_ID", "decision": "approve", "edits": {"FIELD_KEY": "New answer"}}'
```

`edits` is optional and takes only keys from the review's `editableFieldIds`. A choice field takes one of its `options[].value`. `"decision": "reject"` skips the application and returns it to the person's allowance. Form review works on application systems that can pause before submitting. On other systems the application is sent without this pause, even with the setting on.

<a id="refresh"></a>

## Refresh the access token

Access tokens last an hour (`expires_in`). Get a new one from the token endpoint with the refresh token and client ID from the verify response:

```bash
curl -sS -X POST https://api.autojobs.me/oauth/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode "refresh_token=$(jq -r .refresh_token tsenta-token.json)" \
  --data-urlencode "client_id=$(jq -r .client_id tsenta-token.json)"
# {"access_token": "...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "...", "scope": "..."}
```

The response has a new `access_token` and the same `refresh_token`. A refresh token expires after 30 days without a refresh. After that, sign in again with start and verify, which connects the existing account.

<a id="limits"></a>

## Limits

- A new account gets 25 free applications, once, not monthly. Each application Tsenta queues uses one, and one that fails or is skipped is given back. Plans with more are at [tsenta.com/pricing](https://tsenta.com/pricing).
- The code has 6 digits, expires in 10 minutes and allows 5 tries. Starting again sends a new code, and the old one stops working.
- Starting a signup is rate limited: a 429 carries `retry_after` and a `Retry-After` header, in seconds. Too many wrong codes pause the email for a while (423 `paused`).
- Tool calls are throttled per account, and some tools have a daily cap per account that resets at midnight UTC. A refused call returns 422 `tool_error` saying so and counts nothing.
- Reading a résumé usually takes 30 to 60 seconds. Poll every 10 to 15 seconds, not faster.
- Only the person can read the code and decide on what Tsenta prepared. Their street address and ZIP code come from them too: ask, and save their answers with `set-personal-info`.

<a id="errors"></a>

## Errors

Signup and tool endpoints answer with `{"error": "<code>", "message": "<one sentence>"}`, plus the extra fields named below. The token endpoint, and a 401 from the tool endpoints, use OAuth's `{"error", "error_description"}` instead. In the table, start and verify are the two signup requests, tools is any request under `/api/v1/agent/tools`, and token is `/oauth/token`.

| Endpoint | Status | error | What it means |
| --- | --- | --- | --- |
| start | 400 | `invalid_request` | The body isn't JSON or a field is wrong. `agent_name` takes 1 to 80 characters, `name` up to 120. |
| start | 400 | `invalid_email` | Not a single email address, or a Tsenta inbox address. Use the person's own email. |
| start | 403 | `agent_not_allowed` | Tsenta doesn't accept this `agent_name`. |
| start | 422 | `signup_refused` | Tsenta refused the signup, for example for a temporary inbox. `message` says why. |
| start | 429 | `rate_limited` | Too many signups started. Wait `retry_after` seconds (also in the `Retry-After` header). |
| start, verify | 423 | `paused` | Too many wrong codes for this email. Wait before trying again. |
| start | 502 | `send_failed` | The email with the code couldn't be sent. Try again. |
| start, verify | 503 | `unavailable` | Temporary. Try again shortly. |
| verify | 400 | `invalid_code` | The code isn't 6 digits. Spaces are fine. |
| verify | 400 | `wrong_code` | Wrong code. `tries_left` says how many tries remain. |
| verify | 410 | `code_expired` | The code expired, a newer code replaced it, or 5 wrong tries used it up. Start again. |
| verify | 403 | `account_unavailable` | The account is deleted, suspended or refused. |
| verify | 409 | `email_conflict` | An unfinished signup on the Tsenta website holds this email. `message` tells the person to sign in there once. Then start again. |
| tools | 400 | `invalid_input` | The body doesn't match the tool's input schema. `issues` lists each problem with its `path`. |
| tools | 401 | `invalid_token` | The access token is missing, invalid or expired, or the account or agent is no longer accepted. The reason is in `error_description` (OAuth's shape, not `message`), and the `WWW-Authenticate` header points at the sign-in metadata. Refresh the token once. Refreshing only helps an expired token, so if the 401 comes back, relay `error_description` to the person. |
| tools | 404 | `unknown_tool` | No tool by that name for agents. `GET /api/v1/agent/tools` lists them. |
| tools | 413 | `body_too_large` | The body is too large. Send a smaller tool input. |
| tools | 422 | `tool_error` | The tool ran and refused or failed (`ok: false`). `message` says why, such as a daily limit or a résumé that is still being read. |
| tools | 429 | `rate_limited` | Too many calls for this account. Wait `retry_after` seconds (also in the `Retry-After` header). |
| token | 400 | `invalid_grant` | The refresh token expired, is unknown, or belongs to another `client_id`. Sign in again with start and verify. |
| token | 400 | `invalid_request` | `refresh_token` or `client_id` is missing. |

A 200 can still carry a problem in `result`. From `apply-to-job`, a job's `message` can say the account is out of applications, the profile is missing something (with `missingFields` and a sign-in link in `profileUrl`), the person already applied, the posting closed, or Tsenta doesn't support that application system yet.

<a id="more"></a>

## More

- [MCP setup for Claude, ChatGPT, Cursor and Codex](https://tsenta.com/mcp), with OAuth sign-in instead of a pasted token.
- [OpenAPI document](https://api.autojobs.me/api/v1/agent/openapi.json) for the signup, tool and token endpoints.
- [This guide as markdown](https://tsenta.com/agents.md), and in the [Tsenta docs](https://docs.tsenta.com/product/agent-quickstart).
- [Pricing](https://tsenta.com/pricing) once the free applications run out.
- Questions: [founders@tsenta.com](mailto:founders@tsenta.com).

---

Web page: https://tsenta.com/agents
Contact: founders@tsenta.com

## Next steps for agents

- Create or connect the person's Tsenta account and apply over plain HTTP: https://tsenta.com/agents.md
- OpenAPI for the agent API: https://api.autojobs.me/api/v1/agent/openapi.json
- MCP server: https://api.autojobs.me/api/v1/mcp
- Sign up or sign in in a browser instead: https://dashboard.tsenta.com
- The regular page, for a browser: https://tsenta.com/agents?view=html
