Skip to content
OpenAPI 3.1.0API v1.0.031 operations

Job application API reference

Search current jobs, store candidate facts, submit real employer applications, and let your own agent answer form questions. Every endpoint below is rendered from the same OpenAPI contract served by the API.

OpenAPI JSON Agent-readable docs
Base URL
https://api.applyguy.ai
Search
0.05 credit / 25
Managed application
2 credits · $0.10
Your agent answers
1 credit · $0.05
EndpointsSetup

Authentication

Send your developer key as Authorization: Bearer $APPLYGUY_API_KEY. The bootstrap endpoint is public; API-key management uses the separate account access token returned during bootstrap.

Endpoint group

Setup

Create a developer account and manage API keys.

post/developer/bootstrapNo authentication

Create an account and first API key

Creates a zero-balance, API-credit-only developer account, an API key, and account access tokens in one call while new registrations are enabled. The API key and refresh token are returned only once. No application can run until credits are purchased.

operationId: bootstrapDeveloper

Request body

application/json · required
emailrequired
string (email)
—
passwordrequired
string (password)
—
name
string
Default: Default agent
scopes
array
—
expiresAt
string (date-time)
—
View request schema
{
  "$ref": "#/components/schemas/DeveloperBootstrap"
}

Responses

201
Account, one-time API key, account tokens, and next setup endpoints.
DeveloperBootstrapResult
400
The account or key configuration is invalid.
ManagementError
403
New account registration is currently paused.
ManagementError
409
An account already exists for this email.
ManagementError
413
The bootstrap payload exceeds 64 KB.
ManagementError
429
Too many bootstrap attempts from this address.
ManagementError
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/developer/bootstrap' \
  --header 'Content-Type: application/json' \
  --data '{"email":"agent-builder@example.com","password":"correct-horse-battery-staple","name":"Production agent"}'
get/developer/api-keysAccount access token

List API keys

Lists key metadata. Full secrets are never returned after creation.

operationId: listApiKeys

Responses

200
API key metadata.
object
401
The account access token is missing or invalid.
ManagementError
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/developer/api-keys' \
  --header "Authorization: Bearer $APPLYGUY_ACCESS_TOKEN"
post/developer/api-keysAccount access token

Create an API key

Creates a scoped developer key. Store the returned key immediately because it cannot be retrieved again.

operationId: createApiKey

Request body

application/json · required
name
string
Default: Default agent
scopes
array
—
expiresAt
string (date-time)
—
View request schema
{
  "$ref": "#/components/schemas/ApiKeyCreate"
}

Responses

201
One-time API key and metadata.
ApiKeyCreated
400
The key configuration is invalid.
ManagementError
401
The account access token is missing or invalid.
ManagementError
409
The account already has the maximum 20 active API keys.
ManagementError
413
The management payload exceeds 64 KB.
ManagementError
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/developer/api-keys' \
  --header "Authorization: Bearer $APPLYGUY_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"CI application agent","scopes":["jobs:read","credits:spend","applications:read","applications:write"]}'
post/auth/refreshNo authentication

Rotate account access and refresh tokens

Uses the latest refresh token returned by bootstrap or a prior refresh. The old token is revoked; store the replacement atomically. This account token is for API-key and integration management, not /v1 requests.

operationId: refreshAccountSession

Request body

application/json · required
refreshTokenrequired
string
The latest refresh token. Refresh tokens rotate on every successful use.
View request schema
{
  "$ref": "#/components/schemas/SessionRefresh"
}

Responses

200
Rotated account tokens.
SessionRefreshResult
400
A refresh token is required.
ManagementError
401
The refresh token is invalid, expired, or revoked.
ManagementError
409
Another request rotated this token first; retry with the token returned by that request.
ManagementError
429
Too many refresh attempts.
ManagementError
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/auth/refresh' \
  --header 'Content-Type: application/json' \
  --data '{"refreshToken":"the-latest-refresh-token"}'
delete/developer/api-keys/{id}Account access token

Revoke an API key

Immediately revokes a developer API key owned by the account.

operationId: revokeApiKey

Parameters

idrequired
path · string (uuid)
API key ID.

Responses

204
Key revoked.
400
The API key ID must be a UUID.
ManagementError
401
The account access token is missing or invalid.
ManagementError
404
The key does not exist or was already revoked.
ManagementError
cURL
curl --request DELETE \
  --url 'https://api.applyguy.ai/developer/api-keys/24a9829d-7ec5-4fcc-917c-229006d22b06' \
  --header "Authorization: Bearer $APPLYGUY_ACCESS_TOKEN"

Endpoint group

Jobs

Search the fresh Apply Guy job catalog or retrieve one listing. Billable reads require jobs:read and credits:spend; successful requests use fractional credits.

get/v1/jobsAPI key

Search fresh jobs

Requires both jobs:read and credits:spend. jobs:read alone returns 403 without charging; credits:spend is explicit authorization for this key to incur catalog-read charges and grants no read access by itself. Searches active, non-stale U.S. jobs ordered by recency. A successful 200 costs 0.05 credit per requested block of up to 25 results: limits 1–25 cost 0.05, 26–50 cost 0.10, 51–75 cost 0.15, and 76–100 cost 0.20. Billing uses the requested limit, not the number of matches returned. Invalid requests, authorization failures, rate limits, and 5xx responses are not charged. Use the returned job ID directly when creating an application. Developer API v1 does not expose other country catalogs.

operationId: searchJobs

Parameters

q
query · string
Text matched against job title and company.
ats
query · string
Filter by applicant tracking system.
country
query · string
Developer API v1 country. Only US is accepted.
remote
query · string
—
limit
query · integer
—
cursor
query · integer
Numeric offset returned as nextCursor.

Responses

200
A page of current jobs. With jobs:read and credits:spend, this response is charged and includes decimal cost plus post-charge balance headers, with exact milli-credit equivalents.
Response headers
X-ApplyGuy-Credit-CostDecimal credits charged for this successful request.
X-ApplyGuy-Credit-BalanceDecimal credit balance after this request was charged.
X-ApplyGuy-Credit-Cost-MilliExact charge in thousandths of a credit. Prefer this header for accounting.
X-ApplyGuy-Credit-Balance-MilliExact remaining balance in thousandths of a credit. Prefer this header for accounting.
object
400
One or more search filters are invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
402
The account does not have enough credits for the requested search page.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --include --request GET \
  --url 'https://api.applyguy.ai/v1/jobs?q=software%20engineer&ats=greenhouse&country=US&remote=remote&limit=25&cursor=0' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
get/v1/jobs/{id}API key

Get a job and cached description

Requires both jobs:read and credits:spend. jobs:read alone returns 403 without charging; credits:spend is explicit authorization for this key to incur catalog-read charges and grants no read access by itself. Returns one active U.S. catalog job, enriched role metadata, and the cached employer-provided description. A successful 200 costs 0.01 credit. Invalid IDs, unavailable or stale jobs, authorization failures, rate limits, and 5xx responses are not charged. Description HTML can be loaded from Apply Guy object storage when the database copy is absent. Stale and non-U.S. jobs intentionally return 404.

operationId: getJob

Parameters

idrequired
path · string (uuid)
Catalog job ID.

Responses

200
Current job detail. With jobs:read and credits:spend, this response is charged and includes decimal cost plus post-charge balance headers, with exact milli-credit equivalents.
Response headers
X-ApplyGuy-Credit-CostDecimal credits charged for this successful request.
X-ApplyGuy-Credit-BalanceDecimal credit balance after this request was charged.
X-ApplyGuy-Credit-Cost-MilliExact charge in thousandths of a credit. Prefer this header for accounting.
X-ApplyGuy-Credit-Balance-MilliExact remaining balance in thousandths of a credit. Prefer this header for accounting.
object
400
The job ID must be a UUID.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
402
The account does not have enough credits to retrieve this job detail.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
The job is unavailable or stale.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --include --request GET \
  --url 'https://api.applyguy.ai/v1/jobs/951f7024-bbf7-4aa5-98fc-f45625584f9b' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"

Endpoint group

Candidate profile

Store the candidate facts and resume used during applications.

get/v1/profileAPI key

Get the candidate profile

Returns the stored candidate context plus resume presence. Requires profile:read.

operationId: getCandidateProfile

Responses

200
Candidate profile and resume metadata.
object
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/profile' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
put/v1/profileAPI key

Merge candidate profile facts

Merges supplied candidateContext properties into the existing profile. Deterministic fields such as name, contact information, address, and LinkedIn are reused directly during applications.

operationId: updateCandidateProfile

Request body

application/json · required
candidateContextrequired
CandidateContext
—
View request schema
{
  "type": "object",
  "required": [
    "candidateContext"
  ],
  "properties": {
    "candidateContext": {
      "$ref": "#/components/schemas/CandidateContext"
    }
  }
}

Responses

200
Merged candidate profile.
object
400
candidateContext is required.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
413
The profile payload exceeds 256 KB.
Error
422
The candidate profile contains invalid values.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request PUT \
  --url 'https://api.applyguy.ai/v1/profile' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"candidateContext":{"firstName":"Jordan","lastName":"Bamber","email":"jordan@example.com","phone":"+1 415 555 0199","location":"San Francisco, CA","linkedin":"https://www.linkedin.com/in/jordan-bamber"}}'
put/v1/profile/resumeAPI key

Upload the primary resume

Uploads a PDF, DOC, or DOCX resume up to 5 MB as multipart field file. The resume safely replaces the prior upload and becomes the default document for applications. Uploads are limited to 5 per minute and 20 per hour per account.

operationId: uploadResume

Request body

multipart/form-data · required
filerequired
string (binary)
—
View request schema
{
  "type": "object",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  }
}

Responses

200
Resume uploaded.
object
400
Upload a multipart field named file.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
413
The multipart payload or resume exceeds the 5 MB file limit.
Error
422
The file type or size is unsupported.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
503
Resume storage is temporarily unavailable.
Error
cURL
curl --request PUT \
  --url 'https://api.applyguy.ai/v1/profile/resume' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --form 'file=@./resume.pdf'

Endpoint group

Integrations

Configure account integrations required by some ATS workflows.

get/secrets/statusAccount access token

Check Workday email integration readiness

Uses the account accessToken returned by bootstrap, not a developer API key. No email secret is ever returned.

operationId: getEmailIntegrationStatus

Responses

200
Email integration readiness and the ATSes that require it.
EmailIntegrationStatus
401
The account access token is missing or invalid.
ManagementError
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/secrets/status' \
  --header "Authorization: Bearer $APPLYGUY_ACCESS_TOKEN"
put/secrets/email-integrationAccount access token

Verify and save Gmail IMAP credentials

Uses the account accessToken returned by bootstrap. Apply Guy verifies the Gmail username and 16-character app password over IMAP before encrypting both values. Creating the Gmail app password requires a one-time human Google Account setup; it is required for Workday even though the API call itself is automatable.

operationId: configureEmailIntegration

Request body

application/json · required
gmailUserrequired
string (email)
—
gmailAppPasswordrequired
string
A 16-character Gmail app password. Spaces are accepted and removed before validation; this is not the Gmail account password.
View request schema
{
  "$ref": "#/components/schemas/EmailIntegrationCreate"
}

Responses

200
Credentials verified and stored.
object
400
The email address or Gmail app-password shape is invalid.
ManagementError
401
The account access token is missing or invalid.
ManagementError
413
The integration payload exceeds the management API limit.
ManagementError
422
Gmail rejected the IMAP credentials.
ManagementError
503
Gmail credential validation is temporarily unavailable.
ManagementError
cURL
curl --request PUT \
  --url 'https://api.applyguy.ai/secrets/email-integration' \
  --header "Authorization: Bearer $APPLYGUY_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"gmailUser":"candidate@gmail.com","gmailAppPassword":"abcd efgh ijkl mnop"}'

Endpoint group

Credits

Inspect the balance or purchase credits through hosted Stripe Checkout.

get/v1/creditsAPI key

Get balance, pricing, and purchase bounds

Returns the live balance and pricing. There are 20 credits per dollar. Search costs 0.05 credit per requested block of up to 25 results, a job-detail 200 costs 0.01 credit, managed applications cost 2 credits, and bring-your-own-agent applications cost 1 credit.

operationId: getCredits

Responses

200
Credit account.
object
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/credits' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
post/v1/credits/checkoutAPI key

Create hosted checkout for a dollar amount

Creates a Stripe-hosted checkout session for any whole-cent USD amount within the bounds returned by GET /v1/credits. Stripe requires human payment approval. Workday separately requires a one-time human Google Account step to create a Gmail app password.

operationId: createCreditCheckout

Request body

application/json · required
amountCentsrequired
integer
$5.00, yielding 100 credits at the current rate.
View request schema
{
  "type": "object",
  "required": [
    "amountCents"
  ],
  "properties": {
    "amountCents": {
      "type": "integer",
      "example": 500,
      "description": "$5.00, yielding 100 credits at the current rate."
    }
  }
}

Responses

201
Hosted checkout URL and expected credit grant.
object
400
The amount is outside the advertised purchase bounds.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
The developer credit account was not found.
Error
413
The JSON payload exceeds 256 KB.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
503
Billing is temporarily unavailable.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/credits/checkout' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"amountCents":500}'
get/v1/credits/checkout/{id}API key

Poll checkout and reconcile paid credits

Returns Stripe checkout state. If payment completed before the webhook arrived, this request safely reconciles the credit grant.

operationId: getCreditCheckout

Parameters

idrequired
path · string
Stripe Checkout Session ID.

Responses

200
Checkout state. A paid response means the credit grant has been reconciled.
object
400
The checkout session ID is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
The checkout session is not owned by this account.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
503
Billing is temporarily unavailable.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/credits/checkout/cs_live_a1b2c3' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"

Endpoint group

Usage

Measure application outcomes, credit economics, latency, and API-key activity or share a read-only report.

get/v1/usageAPI key

Get application and credit usage analytics

Returns outcome counts, success rate, completion-time percentiles, credit economics, time-series buckets, ATS/mode/API-key breakdowns, and normalized failure reasons. Requires usage:read. successRate is a 0–100 percentage computed as success / (success + failed) × 100, excluding in-progress and cancelled applications; it is 0 when no outcomes are resolved. Reports contain operational aggregates, not candidate PII.

operationId: getUsageReport

Parameters

range
query · UsageRange
Rolling reporting range. Defaults to 30d.

Responses

200
Usage analytics for the selected range.
object
400
The usage range is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/usage' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"

Endpoint group

Applications

Preflight, submit, monitor, and cancel job applications.

post/v1/applications/preflightAPI key

Check readiness before spending credits

Checks ATS availability, required profile facts, resume presence, inbox requirements, requested mode, and cost. A catalog jobId is also checked for current U.S. catalog eligibility and freshness. A caller-supplied raw jobUrl is validated for supported ATS ownership and URL shape, but its live availability and U.S. suitability are not known until the application runs. Preflight is free and no credits are reserved.

operationId: preflightApplication

Request body

application/json · required
jobId
string (uuid)
A job returned by the catalog.
jobUrl
string (uri)
A supported platform-owned HTTPS employer application URL for a caller-selected U.S.-appropriate role. Raw URL availability is resolved during application execution.
ats
string
Optional ATS hint when submitting a URL. It must agree with the URL host.
mode
string
Managed costs 2 credits. Agent mode costs 1 credit and requests structured answers from your agent.
View request schema
{
  "$ref": "#/components/schemas/ApplicationCreate"
}

Responses

200
Readiness details and exact application cost.
object
400
Provide exactly one jobId or jobUrl.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
The catalog job is unavailable or stale.
Error
413
The JSON payload exceeds 256 KB.
Error
422
The ATS or raw employer URL is unsupported or unsafe.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/applications/preflight' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"jobId":"951f7024-bbf7-4aa5-98fc-f45625584f9b","mode":"agent"}'
get/v1/applicationsAPI key

List developer applications

Returns up to the 100 most recently queued developer applications for the account. applications:read exposes requiresAnswers, but answerRequest and submittedAnswers are redacted unless the key also has profile:read.

operationId: listApplications

Responses

200
Recent developer applications.
object
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/applications' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
post/v1/applicationsAPI key

Reserve credits and start an application

Queues a job application and atomically reserves its credits. Reusing the same Idempotency-Key with the same API key and equivalent request returns the original application instead of charging twice; reusing it for a different job or mode returns idempotency_conflict. A user can have only one application in progress per canonical employer target. A prior success returns already_applied, and two failed runs for the same target in a rolling 24-hour window return application_retry_limit_reached until the Retry-After delay expires. Rotating API keys, changing idempotency keys, or adding tracking query parameters does not create a new target identity.

operationId: createApplication

Parameters

Idempotency-Keyrequired
header · string
Unique operation key, at most 200 characters.

Request body

application/json · required
jobId
string (uuid)
A job returned by the catalog.
jobUrl
string (uri)
A supported platform-owned HTTPS employer application URL for a caller-selected U.S.-appropriate role. Raw URL availability is resolved during application execution.
ats
string
Optional ATS hint when submitting a URL. It must agree with the URL host.
mode
string
Managed costs 2 credits. Agent mode costs 1 credit and requests structured answers from your agent.
View request schema
{
  "$ref": "#/components/schemas/ApplicationCreate"
}

Responses

200
The equivalent idempotent request already exists.
object
201
Application created and queued.
object
400
The body or Idempotency-Key is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
402
The account does not have enough credits.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
The catalog job is unavailable or stale.
Error
409
The ATS is disabled, the mode is unsupported, a required inbox is disconnected, an equivalent target is already active/successful, the target reached two failed attempts in 24 hours, or the Idempotency-Key was reused for a different request. Codes: ats_disabled, agent_mode_unsupported, email_integration_required, application_already_in_progress, already_applied, application_retry_limit_reached, idempotency_conflict. Retry-limit responses include failedAttempts, limit, windowHours, retryAt, and retryAfterSeconds details and a Retry-After header.
Error
413
The JSON payload exceeds 256 KB.
Error
422
Required profile fields are incomplete, or the ATS/raw employer URL is unsupported or unsafe.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/applications' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Idempotency-Key: apply-job-951f7024-v1' \
  --header 'Content-Type: application/json' \
  --data '{"jobId":"951f7024-bbf7-4aa5-98fc-f45625584f9b","mode":"managed"}'
get/v1/applications/{id}API key

Get application state

Returns the latest state and stable failure reason. requiresAnswers is always visible; candidate-sensitive answerRequest and submittedAnswers require profile:read in addition to applications:read.

operationId: getApplication

Parameters

idrequired
path · string (uuid)
Application ID.

Responses

200
Application state.
object
400
The application ID must be a UUID.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
Application not found.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/applications/529f67cf-7296-40ea-a90a-a1dcc09f1e8d' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
post/v1/applications/{id}/cancelAPI key

Cancel before submission

Cancels a queued or awaiting-answers application. Reserved developer credits are refunded idempotently.

operationId: cancelApplication

Parameters

idrequired
path · string (uuid)
Application ID.

Responses

200
Application cancelled and credits refunded.
object
400
The application ID must be a UUID.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
Application not found.
Error
409
The application can no longer be cancelled.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/applications/529f67cf-7296-40ea-a90a-a1dcc09f1e8d/cancel' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"

Endpoint group

Agent answers

Complete structured answer rounds in bring-your-own-agent mode.

get/v1/applications/{id}/answer-requestAPI key

Get a pending agent prompt and JSON Schema

When an agent-mode application enters awaiting_answers, fetch this request and have your own model return JSON matching responseSchema. This endpoint requires both applications:read and profile:read because the prompt contains candidate data.

operationId: getAnswerRequest

Parameters

idrequired
path · string (uuid)
Application ID.

Responses

200
Pending answer request.
object
400
The application ID must be a UUID.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
Application not found.
Error
409
The application is not awaiting answers.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/applications/529f67cf-7296-40ea-a90a-a1dcc09f1e8d/answer-request' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
post/v1/applications/{id}/answersAPI key

Validate an agent answer and resume

Validates answer against the exact responseSchema, rejects stale fingerprints, and resumes the application. A later form step may create another answer round.

operationId: submitAgentAnswers

Parameters

idrequired
path · string (uuid)
Application ID.

Request body

application/json · required
requestIdrequired
string (uuid)
—
fingerprintrequired
string
—
answerrequired
object
JSON value conforming exactly to answerRequest.responseSchema.
View request schema
{
  "$ref": "#/components/schemas/AgentAnswer"
}

Responses

202
Answer accepted and application re-queued.
object
400
The answer envelope is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
409
The request is stale or no longer pending.
Error
413
The external answer envelope exceeds 64 KB.
Error
422
The answer does not match responseSchema.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/applications/529f67cf-7296-40ea-a90a-a1dcc09f1e8d/answers' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"905c7655-7582-4556-a13d-bf49fcb63bf8","fingerprint":"b4fc0d55a3f819c70a37f2f8931f29fb848bff0e1f0b7976e5b04e49c015bbd2","answer":{"answers":[{"fieldId":"work_authorization","value":"Yes"}]}}'

Endpoint group

Webhooks

Receive signed application state changes without polling.

get/v1/webhooksAPI key

List webhooks

Lists webhook endpoints and subscribed events. Signing secrets are never returned after creation.

operationId: listWebhooks

Responses

200
Registered webhooks.
object
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request GET \
  --url 'https://api.applyguy.ai/v1/webhooks' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"
post/v1/webhooksAPI key

Register a signed HTTPS webhook

Registers a public HTTPS endpoint. The HMAC-SHA256 signing secret is returned once. If events is omitted, all application events are subscribed. An account can register at most 10 endpoints and cannot register the same URL twice.

operationId: createWebhook

Request body

application/json · required
urlrequired
string (uri)
—
events
array
—
View request schema
{
  "$ref": "#/components/schemas/WebhookCreate"
}

Responses

201
Webhook and one-time signing secret.
WebhookCreatedResponse
400
The URL or event list is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
409
The URL is already registered or the account has reached 10 webhooks.
Error
413
The JSON payload exceeds 256 KB.
Error
422
The URL is not a public HTTPS endpoint.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request POST \
  --url 'https://api.applyguy.ai/v1/webhooks' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://agent.example.com/webhooks/applyguy","events":["application.awaiting_answers","application.succeeded","application.failed"]}'
patch/v1/webhooks/{id}API key

Update a webhook

Changes the URL, event subscriptions, or active state of an existing webhook.

operationId: updateWebhook

Parameters

idrequired
path · string (uuid)
Webhook ID.

Request body

application/json · required
url
string (uri)
—
events
array
—
active
boolean
—
View request schema
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/WebhookEventType"
      }
    },
    "active": {
      "type": "boolean"
    }
  }
}

Responses

200
Updated webhook.
object
400
The webhook update is invalid.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
Webhook not found.
Error
413
The JSON payload exceeds 256 KB.
Error
422
The URL is not a public HTTPS endpoint.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request PATCH \
  --url 'https://api.applyguy.ai/v1/webhooks/ec41686d-d579-48c6-9b92-b47cfa086f93' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"active":false}'
delete/v1/webhooks/{id}API key

Delete a webhook

Permanently removes a webhook endpoint owned by the account.

operationId: deleteWebhook

Parameters

idrequired
path · string (uuid)
Webhook ID.

Responses

204
Webhook deleted.
400
The webhook ID must be a UUID.
Error
401
Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.
Error
403
The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).
Error
404
Webhook not found.
Error
429
The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.
Error
cURL
curl --request DELETE \
  --url 'https://api.applyguy.ai/v1/webhooks/ec41686d-d579-48c6-9b92-b47cfa086f93' \
  --header "Authorization: Bearer $APPLYGUY_API_KEY"