Create an API key in the Erika app under Settings → API Keys and send it in the X-Api-Key header on every request. Authorization: Bearer is not supported. Keys look like ek_live_…, and their permissions are fixed when you create them.
Auto Campaign API permission: campaign builds and sourcing reads (Manage to create builds, View to read).
Jobs and Candidates permissions (View or Manage): the ATS endpoints.
Every request is scoped to the key's organization.
Responses and errors
Successful responses wrap the payload as { "success": true, "data": … }. List endpoints are cursor-paginated: pass nextCursor back as cursor while hasMore is true. Errors return { "success": false, "error": "…", "code": "…", "requestId": "…" }; quote the requestId when you contact support.
Create a Job, generate creatives + videos, and launch a Meta campaign end to end from one call. Requires the MANAGE_CAMPAIGN_API scope. Returns 202 immediately; poll the status URL or receive a signed webhook on completion.
Description Erika builds a NEW job from. Provide exactly one of jobDescription or jobId.50–20000 chars
jobId
string (uuid)
Reuse an EXISTING Erika job (no new job is created); targeting is seeded from its details. Provide exactly one of jobDescription or jobId.
budget
number
Total credit envelope. Production (videos + AI) is spent from it; the remainder funds Meta.required · > 0
budgetCurrency
"CREDITS" | "USD" | "EUR"
default "CREDITS"
duration
integer
Campaign run length in daysrequired · > 0
city
string
Work-location city. Inferred from the job description when omitted.1–120 chars
countryCode
string
ISO-3166 alpha-2 (e.g. CZ). Inferred from the job description when omitted.2–2 chars
language
string
Ad + screening language (e.g. cs). Inferred from the job description when omitted.2–5 chars
startDate
string
Scheduled launch day, ISO YYYY-MM-DD. Omitted launches today. A past date is clamped to now.pattern ^\d{4}-\d{2}-\d{2}$
callbackUrl
string (uri)
HTTPS endpoint POSTed a signed result on completion/failure
metadata
map of string
Caller-defined tracking, echoed back verbatim on the status endpoint and the completion webhook (your job id, client, brand, campaign ref). Opaque to Erika. Up to 20 keys; key <= 40 chars, value <= 500 chars.
idempotencyKey
string
Required. A retry with the same key returns the same build (no double spend).required · 8–255 chars
200 Jobs page. data: Job[], plus nextCursor, hasMore
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Create job
POSThttps://app.erikawork.com/api/jobs
Request body
Field
Type
Description
title
string
required · 1–200 chars
externalRef
string
Your own reference for this position, typically the job ID from your ATS. Free text, up to 100 characters. Every application on this job returns it as jobExternalRef, so you can match applications without a lookup.max 100 chars
The AI qualifier checks each sourced candidate against the position's must-haves and, in mode move, moves the qualified ones to targetStage (the next stage unless the position picked another one from targetOptions). It never rejects. requirements is the position's own list when one was set, else null (Erika derives the must-haves from the job and the application form).
Parameters
Parameter
Type
Description
jobId
string
path · required
Response
200 Qualifier setting. data: object
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
Set the mode, where qualified candidates go (targetStageId, one of targetOptions; null = the next stage after the one candidates land in, the default) and/or the position's own must-haves (requirements: null goes back to Erika's own list). Switching a position off also makes off the company default for new campaigns.
Parameters
Parameter
Type
Description
jobId
string
path · required
Request body
Field
Type
Description
mode
"move" | "rank_only" | "off"
move = Erika moves qualified candidates to the target stage; rank_only = only marks them, without moving (the value keeps its name for compatibility); off.
targetStageId
string | null
requirements
object[] | null
Response
200 Saved. data: object
400 Validation error or business-rule violation
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Candidates
List candidates
GEThttps://app.erikawork.com/api/candidates
Parameters
Parameter
Type
Description
source
string
query
tag
string
query
search
string
query
limit
integer
query · ≥ 1 · ≤ 100
cursor
string
query
Response
200 Candidates page. data: Candidate[], plus nextCursor, hasMore
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Create candidate
POSThttps://app.erikawork.com/api/candidates
Request body
Field
Type
Description
firstName
string
required · 1–100 chars
lastName
string
required · 1–100 chars
email
string (email)
phonePrefix
string
max 10 chars
phoneNumber
string
max 40 chars
linkedinUrl
string (uri)
source
string
max 60 chars
tags
string[]
Response
201 Created. data: object
400 Validation error or business-rule violation
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Bulk create candidates
POSThttps://app.erikawork.com/api/candidates/bulk
Up to 1000 rows per request. Duplicates by email are skipped and reported in the response.
Request body
Field
Type
Description
rows
object[]
required · min 1 items
Response
200 Bulk result. data: object
400 Validation error or business-rule violation
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Get candidate by ID
GEThttps://app.erikawork.com/api/candidates/{id}
Full candidate detail including every application, its form answers, and the candidate's stated situation facts (candidateProfile: start availability, salary expectation, job-search status, best time to call). candidateProfile requires the API key to hold VIEW_SCREENING.
Soft-deletes the candidate and cascades to their applications + notes (the platform talent profile is left intact). Returns the bulk-delete result (deletedCount is 1 for this single-id path; deletedApplications is the cascade count).
Parameters
Parameter
Type
Description
id
string
Resource ID (UUID)path · required
Response
200 Deleted. data: object
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
Removes the application from boards, lists, exports and search. Destructive — distinct from rejecting (which keeps the record). Returns the bulk-delete result (deletedCount is 1 for this single-id path).
For a candidate the AI qualifier judged not qualified, add them to one of the other open positions it suggested (qualifier.suggestions on the application). Creates a new application with the same source; the original application stays. Both timelines note where the candidate came from. Requires MANAGE_CANDIDATES.
Parameters
Parameter
Type
Description
id
string
path · required
Request body
Field
Type
Description
jobId
string (uuid)
required
Response
201 Added. data: object
400 Validation error or business-rule violation
401 Missing or invalid API key
403 API key lacks the permission for this endpoint, or endpoint is web-only
Chronological history (newest first) of credit top-ups, auto-recharges and subscription plan grants with the amount + currency charged — for billing transparency. Readable with either the VIEW_CAMPAIGN_API or MANAGE_CAMPAIGN_API scope.
Parameters
Parameter
Type
Description
limit
string
Page size, 1–100 (default 20).query
before
string
ISO timestamp cursor from a previous page's nextCursor — returns purchases strictly older than this.query
403 API key lacks the permission for this endpoint, or endpoint is web-only
500 Internal server error
Schemas
Organization
Field
Type
Description
id
string
required
pid
integer
required
name
string
required
slug
string
required
timezone
string
required
language
string
required
dateCreated
string (date-time)
required
ErrorResponse
Error response. Quote the requestId when contacting support.
Field
Type
Description
success
false
required
error
string
required
code
string
requestId
string
Job
Field
Type
Description
id
string
required
pid
integer
required
title
string
required
externalRef
string | null
Your own reference for this position, typically the job ID from your ATS. Free text, up to 100 characters. Every application on this job returns it as jobExternalRef, so you can match applications without a lookup.required · max 100 chars
Candidate-stated situation facts, collected during screening. Null when the API key lacks VIEW_SCREENING or the candidate stated none of them.
Field
Type
Description
startAvailability
object | null
How soon they can start / notice periodrequired
salaryExpectation
object | null
Verbatim, with currency and period as they said itrequired
jobSearchStatus
object | null
required
bestTimeToCall
object | null
required
capturedAt
string (date-time) | null
When the facts were capturedrequired
isStale
boolean
Captured over 30 days ago — show the date, do not present as currentrequired
CallWindow
Field
Type
Description
days
integer[]
ISO weekdays, 1 = Monday … 7 = Sundayrequired
from
string
"HH:mm", candidate-localrequired
to
string
"HH:mm", exclusive endrequired
CallException
Field
Type
Description
date
string
"YYYY-MM-DD", candidate-localrequired
from
string
required
to
string
required
ApplicationSummary
Field
Type
Description
id
string
required
candidateId
string
required
candidateName
string
required
candidateEmail
string | null
required
candidateTags
string[]
required
jobId
string
required
jobTitle
string
required
jobExternalRef
string | null
The job's externalRef: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.required
stageName
string
required
stageCategory
string
required
source
string
required
ApplicationListItem
Field
Type
Description
id
string
required
pid
integer
required
candidate
object
required
jobExternalRef
string | null
The job's externalRef: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.required
The job's externalRef: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.required
currentStage
object
required
status
"active" | "rejected" | "withdrawn" | "hired"
required
source
string
required
firstViewedAt
string (date-time) | null
required
firstViewedBy
string | null
required
isViewed
boolean
required
rejectedAt
string (date-time) | null
required
rejectionReason
string | null
required
activities
object[]
required
attachments
object[]
required
ratings
object[]
required
averageRating
number | null
required
ratingCount
integer
required
applicationAnswers
object[]
required
answerFit
map of any | null | null
Advisory per-answer requirement labels. Null when not evaluated.required
qualifier
object | null
AI qualifier result for sourced candidates: the position's must-haves checked one by one. It never rejects. Null when not judged (qualifier off, not a sourced candidate, or not run yet).required
Shown ONCE. Verify the x-webhook-signature (base64 HMAC-SHA256) on the callback with it.
CreateCampaignBuild
Field
Type
Description
jobDescription
string
Description Erika builds a NEW job from. Provide exactly one of jobDescription or jobId.50–20000 chars
jobId
string (uuid)
Reuse an EXISTING Erika job (no new job is created); targeting is seeded from its details. Provide exactly one of jobDescription or jobId.
budget
number
Total credit envelope. Production (videos + AI) is spent from it; the remainder funds Meta.required · > 0
budgetCurrency
"CREDITS" | "USD" | "EUR"
default "CREDITS"
duration
integer
Campaign run length in daysrequired · > 0
city
string
Work-location city. Inferred from the job description when omitted.1–120 chars
countryCode
string
ISO-3166 alpha-2 (e.g. CZ). Inferred from the job description when omitted.2–2 chars
language
string
Ad + screening language (e.g. cs). Inferred from the job description when omitted.2–5 chars
startDate
string
Scheduled launch day, ISO YYYY-MM-DD. Omitted launches today. A past date is clamped to now.pattern ^\d{4}-\d{2}-\d{2}$
callbackUrl
string (uri)
HTTPS endpoint POSTed a signed result on completion/failure
metadata
map of string
Caller-defined tracking, echoed back verbatim on the status endpoint and the completion webhook (your job id, client, brand, campaign ref). Opaque to Erika. Up to 20 keys; key <= 40 chars, value <= 500 chars.
idempotencyKey
string
Required. A retry with the same key returns the same build (no double spend).required · 8–255 chars
CampaignBuildStatus
Field
Type
Description
buildId
string
required
status
"queued" | "running" | "completed" | "failed"
required
step
string
required
campaignId
string | null
required
jobId
string | null
required
metadata
map of string
The tracking data you submitted on create, echoed back. Absent if none was sent.
manual = one-off top-up you bought; auto_recharge = charged automatically when the balance ran low; subscription = monthly plan credit grant (renewal, initial subscribe, or plan change); granted = credits Erika added to your account at no charge (no amount, no invoice).required
credits
integer
Credits granted by this purchase.required
amount
integer | null
Money charged in MINOR units of currency (e.g. 425000 = 4,250.00 CZK). Null only for legacy top-ups recorded before the amount was stored.required
currency
string | null
Lowercase ISO currency code (e.g. "czk"), or null if unknown.required
invoiceId
string | null
Stripe invoice id, when one exists.required
reference
string | null
Stripe checkout-session/invoice id or auto-recharge attempt id.required
