Schema Reference

This section defines all data entities used across our API. Understanding these schemas is crucial for correctly interacting with the API.

Agency

Represents a staffing or recruitment agency in the system.

{
  "id": "example_string",
  "name": "example_string",
  "email": "example_string",
  "phone": "example_string",
  "isApproved": true,
  "website": "example_string",
  "createdAt": "2025-07-26T12:00:00Z",
  "updatedAt": "2025-07-26T12:00:00Z",
  "domain": {
    "name": "example_string",
    "verified": true,
    "requestedAt": "2025-07-26T12:00:00Z"
  },
  "locations": [
    {
      "id": "example_string",
      "name": "example_string",
      "about": "example_string",
      "country": "example_string",
      "region": "example_string",
      "city": "example_string"
    }
  ],
  "settings": {
    "logoUrl": "example_string",
    "webhook": {
      "enabled": true,
      "url": "example_string",
      "events": [
        "resume.parsed"
      ]
    }
  }
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the agency
name	string	Yes	Name of the agency
email	string	Yes	Public contact email address of the agency
phone	string	Yes	Public contact phone number of the agency
isApproved	boolean	Yes	Indicates whether the agency has been approved by the platform
website	string	Yes	Public website of the agency
createdAt	string date-time	No	Timestamp when the user was created
updatedAt	string date-time	No	Timestamp when the user was last updated
domain	object AgencyDomain	Yes	Domain verification metadata. See AgencyDomain schema.
locations	array AgencyLocation	Yes	List of physical or operational locations for the agency. See AgencyLocation schema.
settings	object AgencySettings	Yes	Agency-specific settings. See AgencySettings schema.

Agency Location

Represents a physical or operational location associated with an agency.

{
  "id": "example_string",
  "name": "example_string",
  "about": "example_string",
  "country": "example_string",
  "region": "example_string",
  "city": "example_string"
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the location
name	string	Yes	Name of the location (must be unique within the agency)
about	string	Yes	Brief description of the location
country	string	Yes	Country where the location is based
region	string	Yes	Region or state of the location
city	string	Yes	City of the location

Agency Domain

Represents the domain associated with an agency, including verification status.

{
  "name": "example_string",
  "verified": true,
  "requestedAt": "2025-07-26T12:00:00Z"
}

Fields

Field	Type	Required	Description
name	string	Yes	Domain name linked to the agency (e.g., example.com)
verified	boolean	Yes	Whether the domain has been successfully verified
requestedAt	string date-time	No	Unix timestamp indicating when verification was requested

Agency Settings

Represents configuration, branding, and webhook integration settings for an agency.

{
  "logoUrl": "example_string",
  "webhook": {
    "enabled": true,
    "url": "example_string",
    "events": [
      "resume.parsed"
    ]
  }
}

Fields

Field	Type	Required	Description
logoUrl	string	No	URL to the agency's logo used for display purposes
webhook	object Webhook	No	Webhook configuration for receiving event notifications. See Webhook schema.

Agent

Represents a team member (agent) within an agency, such as an admin or recruiter.

{
  "id": "example_string",
  "createdAt": "2025-07-26T12:00:00Z",
  "updatedAt": "2025-07-26T12:00:00Z",
  "firstName": "example_string",
  "lastName": "example_string",
  "email": "example_string",
  "agencyId": "example_string",
  "locations": [
    {
      "locationId": "example_string",
      "role": [
        "admin",
        "recruiter",
        "viewer"
      ]
    }
  ],
  "isPrimary": true,
  "settings": {
    "defaultLocationId": "example_string",
    "profilePictureUrl": "example_string"
  }
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the agent
createdAt	string date-time	Yes	Timestamp when the agent account was created
updatedAt	string date-time	Yes	Timestamp when the agent was last updated
firstName	string	Yes	Agent's first name
lastName	string	Yes	Agent's last name
email	string	Yes	Email address associated with the agent
agencyId	string	Yes	ID of the agency this agent belongs to
locations	array AgentLocation	Yes	List of locations the agent is assigned to, along with their role at each location. See AgentLocationAssignment.
isPrimary	boolean	Yes	Indicates whether the agent is the primary account holder or main contact for the agency
settings	object AgentSettings	Yes	Agent-specific settings such as profile picture and default location. See AgentSettings.

Agent Location

Represents the role an agent holds at a specific agency location.

{
  "locationId": "example_string",
  "role": [
    "admin",
    "recruiter",
    "viewer"
  ]
}

Fields

Field	Type	Required	Description
locationId	string	Yes	ID of the location the agent is assigned to
role	string AgentRoles	Yes	Role assigned to the agent at the specified location. See AgentRoles.

Agent Roles

Defines the allowed roles that an agent can hold within a location.

[
  "admin",
  "recruiter",
  "viewer"
]

Fields

Field	Required	Description
admin	No	Has full administrative access across the agency, including managing agents, locations, and settings.
recruiter	No	Can manage jobs and candidates for assigned locations but cannot manage agency-wide settings.
viewer	No	Has read-only access to data across assigned locations.

Agent Settings

Represents customizable settings for an agent, such as login preferences and profile configuration.

{
  "defaultLocationId": "example_string",
  "profilePictureUrl": "example_string"
}

Fields

Field	Type	Required	Description
defaultLocationId	string	No	ID of the default location selected by the agent when signing in
profilePictureUrl	string	No	URL to the agent's profile picture for use in dashboards or communication

Candidate

Represents a candidate added or managed by an agency. Includes basic contact details and online profiles.

{
  "id": "example_string",
  "createdAt": "2025-07-26T12:00:00Z",
  "updatedAt": "2025-07-26T12:00:00Z",
  "agencyId": "example_string",
  "agentId": "example_string",
  "name": "example_string",
  "firstName": "example_string",
  "lastName": "example_string",
  "email": "example_string",
  "phone": "example_string",
  "profiles": [
    {
      "__id": "example_string",
      "network": "example_string",
      "username": "example_string",
      "url": "example_string"
    }
  ]
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the candidate
createdAt	string date-time	Yes	Timestamp when the candidate was created
updatedAt	string date-time	Yes	Timestamp when the candidate was last updated
agencyId	string	Yes	ID of the agency that owns the candidate record
agentId	string	Yes	ID of the agent who added or owns the candidate
name	string	Yes	Full name of the candidate
firstName	string	No	First name of the candidate (optional override of parsed name)
lastName	string	No	Last name of the candidate (optional override of parsed name)
email	string	Yes	Email address of the candidate
phone	string	No	Phone number of the candidate
profiles	array CandidateProfile	Yes	List of public or social profiles associated with the candidate

Candidate Profile

Represents a public or social profile associated with a candidate (e.g., LinkedIn, GitHub).

{
  "__id": "example_string",
  "network": "example_string",
  "username": "example_string",
  "url": "example_string"
}

Fields

Field	Type	Required	Description
__id	string	Yes	Unique identifier for the profile entry
network	string	Yes	Name of the platform or network (e.g., LinkedIn, GitHub)
username	string	Yes	Username or handle used on the platform
url	string	Yes	Direct URL to the candidate's profile on the platform

Webhook

Represents the webhook configuration used by an agency to receive event notifications.

{
  "enabled": true,
  "url": "example_string",
  "events": [
    "resume.parsed"
  ]
}

Fields

Field	Type	Required	Description
enabled	boolean	Yes	Whether the webhook is currently active
url	string	Yes	Target URL where webhook events will be delivered
events	array	Yes	List of subscribed events. Supported: ["resume.parsed"]

Webhook Events

Lists all the supported webhook events that can be subscribed to in your webhook configuration.

[
  "resume.parsed",
  "job.posted",
  "candidate.applied"
]

Fields

Field	Required	Description
resume.parsed	No	Triggered when a resume has been successfully parsed.
job.posted	No	Triggered when a new job is posted.
candidate.applied	No	Triggered when a candidate applies to a job.

Job Post

Represents a structured job post within the system, including metadata, parsed content, and posting details.

{
  "id": "example_string",
  "createdAt": "2025-07-26T12:00:00Z",
  "updatedAt": "2025-07-26T12:00:00Z",
  "agencyId": "example_string",
  "agentId": "example_string",
  "locationId": "example_string",
  "rawText": "example_string",
  "parseStatus": "example_string",
  "title": "example_string",
  "postedAt": "2025-07-26T12:00:00Z",
  "jobUrl": "example_string",
  "jobId": "example_string",
  "applicationDeadline": "example_string",
  "applicationInstructions": "example_string",
  "industry": "example_string",
  "tags": [],
  "languageRequirements": [],
  "company": {},
  "location": [],
  "employmentType": "example_string",
  "experienceLevel": "example_string",
  "educationLevel": [],
  "salaryRange": {},
  "remoteWorkOption": "example_string",
  "description": "example_string",
  "requirements": [],
  "responsibilities": [],
  "benefits": [],
  "department": [],
  "skills": [],
  "mustHaveSkills": [],
  "minimumRequirements": [],
  "niceToHaveSkills": [],
  "preferredQualifications": []
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the job post
createdAt	string date-time	Yes	Timestamp when the job post was created
updatedAt	string date-time	Yes	Timestamp when the job post was last updated
agencyId	string	Yes	ID of the agency that owns the job post
agentId	string	Yes	ID of the agent who added or imported the job post
locationId	string	Yes	ID of the primary agency location associated with the job
rawText	string	Yes	Original raw text of the job post
parseStatus	string	Yes	Current parse status (e.g., 'pending', 'success', 'error')
title	string	Yes	Job title
postedAt	string date-time	No	ISO timestamp of when the job was originally posted
jobUrl	string	No	URL of the original job posting
jobId	string	No	Original job identifier from the source system
applicationDeadline	string	No	Application deadline if provided
applicationInstructions	string	No	Instructions for how to apply
industry	string	No	Industry of the job
tags	array	No	Custom tags or keywords associated with the job
languageRequirements	array	No	Languages required for the job
company	object	Yes	Information about the company offering the job
location	array	Yes	Location(s) where the job is based
employmentType	string	No	Type of employment (e.g., full-time, contract)
experienceLevel	string	No	Required experience level (e.g., entry-level, senior)
educationLevel	array	No	Minimum required education levels
salaryRange	object	No	Structured salary information
remoteWorkOption	string	No	Remote work policy (e.g., remote, hybrid, on-site)
description	string	Yes	Detailed job description
requirements	array	Yes	List of job requirements
responsibilities	array	Yes	List of key responsibilities
benefits	array	Yes	List of job benefits
department	array	No	Department(s) the job belongs to
skills	array	No	General skills required for the role
mustHaveSkills	array	No	Critical must-have skills
minimumRequirements	array	No	Minimum qualifications or baseline requirements
niceToHaveSkills	array	No	Nice-to-have or optional skills
preferredQualifications	array	No	Preferred qualifications or bonuses

User

Represents a user in the system.

{
  "id": "example_string",
  "name": "example_string",
  "email": "example_string",
  "createdAt": "2025-07-26T12:00:00Z",
  "updatedAt": "2025-07-26T12:00:00Z",
  "lastLogin": "2025-07-26T12:00:00Z",
  "settings": {
    "notificationsEnabled": true,
    "theme": "example_string",
    "language": "example_string"
  }
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the user
name	string	Yes	Full name of the user
email	string	Yes	Email address of the user
password	string	Yes	User's password (write-only)
createdAt	string date-time	No	Timestamp when the user was created
updatedAt	string date-time	No	Timestamp when the user was last updated
lastLogin	string date-time	No	Timestamp of the user's last login
settings	object UserSettings	No	User-specific settings. See UserSettings schema.

User Settings

Defines the customizable settings for a user.

{
  "notificationsEnabled": true,
  "theme": "example_string",
  "language": "example_string"
}

Fields

Field	Type	Required	Description
notificationsEnabled	boolean	No	Whether the user receives notifications.
theme	string	No	The preferred theme for the user interface (e.g., 'light', 'dark', 'system').
language	string	No	The preferred language for the user interface (e.g., 'en', 'es').

Product

Represents a product in the catalog.

{
  "id": "example_string",
  "name": "example_string",
  "description": "example_string",
  "price": 123,
  "currency": "example_string",
  "inStock": true,
  "imageUrl": "example_string"
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier for the product
name	string	Yes	Name of the product
description	string	No	Detailed description of the product
price	number	Yes	Price of the product
currency	string	Yes	Currency of the product price (e.g., USD, EUR)
inStock	boolean	Yes	Availability status of the product
imageUrl	string	No	URL to the product image

Error

Standard error response format.

{
  "code": "example_string",
  "message": "example_string",
  "details": {}
}

Fields

Field	Type	Required	Description
code	string	Yes	A unique error code
message	string	Yes	A human-readable error message
details	object	No	Optional additional error details