Appearance
API Reference
Interactive documentation for the Recruitly Nova API. Try endpoints directly from the browser.
The Recruitly Nova API is a simple, lightweight REST API that responds to https requests with JSON. Because it is a REST API, it is completely stateless. Requests are expected to be made in the form of a simple HTTP GET.
Terms of Service
https://recruitly.io/terms-of-serviceServers
https://api.recruitly.io
List campaigns
GET
/api/nova/campaigns/list
Returns the account's email campaigns, newest first. Accepts page and size query parameters (size defaults to 20 and is capped at 100), an optional query matched against the campaign name and subject, an optional status filter (DRAFT, SCHEDULED, PREPARING, PAUSED, SENDING, FAILED, SENT, CANCELLED) and archived=true to list archived campaigns instead of live ones. Each campaign includes id, reference, name, subject, status, statusMessage, archived, suspended, senderName, senderEmail, distributionListId, distributionListName, scheduledOn, sentOn, ownerId, ownerName, createdOn and modifiedOn. Returns 400 for an unknown status and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
archived
archived
Type
boolean
Default
falsepage
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20status
status
Type
string
Responses
OK
application/json
JSON "data": [ { "additionalProperties": { } } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get campaign by ID
GET
/api/nova/campaigns/{campaignId}
Fetches a single email campaign by the campaignId path parameter, scoped to the authenticated API user's account. The response carries the same fields as the list endpoint. Returns 404 if the campaign is not found and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete campaign
DELETE
/api/nova/campaigns/{campaignId}
Permanently deletes a DRAFT campaign together with its statistics. A scheduled campaign is unscheduled first. Campaigns that have started sending cannot be deleted; archive them instead. Returns 400 if the campaign is not found or has already been sent and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Archive campaign
POST
/api/nova/campaigns/{campaignId}/archive
Archives a campaign so it drops out of the live list (list it back with archived=true). Returns 404 if the campaign is not found, 400 if it cannot be archived and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Cancel scheduled campaign
POST
/api/nova/campaigns/{campaignId}/cancel
Cancels a campaign that is scheduled but not yet sending and returns it to draft. Returns 404 if the campaign is not found, 400 if it is not in a cancellable state and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Get campaign statistics
GET
/api/nova/campaigns/{campaignId}/stats
Returns delivery and engagement counters for a sent campaign: requests, dispatches, delivered, opens, uniqueOpens, clicks, uniqueClicks, softBounce, hardBounce, unsubscribes, spamComplaints, failures, rejects and drops. Counters are zero for campaigns that have not been sent. Returns 404 if the campaign is not found and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Unarchive campaign
POST
/api/nova/campaigns/{campaignId}/unarchive
Restores an archived campaign to the live list. Returns 404 if the campaign is not found, 400 if it cannot be restored and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
campaignId*
campaignId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Candidates
Operations
POST/api/nova/candidatesPOST/api/nova/candidates/parseGET/api/nova/candidates/savedsearchesGET/api/nova/candidates/searchGET/api/nova/candidates/{candidateId}PUT/api/nova/candidates/{candidateId}DELETE/api/nova/candidates/{candidateId}PUT/api/nova/candidates/{candidateId}/internalnotesPUT/api/nova/candidates/{candidateId}/overviewPUT/api/nova/candidates/{candidateId}/sourcePUT/api/nova/candidates/{candidateId}/statusPUT/api/nova/candidates/{candidateId}/tags
Create a candidate
POST
/api/nova/candidates
Creates a new candidate from the JSON request body. Supported fields include first and last name, email addresses, phone numbers, social profile links, date of birth, overview, internal notes, skills, tags (group and value pairs, matching the shape returned by candidate reads), work permit, right to work and do-not-contact flags, rating, ownerId (unknown ids are ignored and ownership defaults to the API user), statusId and sourceId master data references, education history, employment history, and custom (UDF) field values. The create counts towards the account's candidate record limit. A duplicate check runs before the record is created: an existing candidate matching on email, LinkedIn profile, or first name, surname and current employer combination blocks the create and responds with 409, carrying the existing candidate's ID in the data field so it can be updated instead. Returns the new candidate's ID on success, 401 for an invalid API key, and 429 when the record limit or rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "currentEmployer": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "doNotContact": true, "educationHistory": [ { "educationLevelId": "string", "endYear": 0, "grade": "string", "major": "string", "organisation": "string", "startYear": 0 } ], "email": "string", "employmentHistory": [ { "companyName": "string", "employmentTypeId": "string", "endDate": "string", "jobTitle": "string", "startDate": "string", "workSummary": "string" } ], "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "internalNotes": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "overview": "string", "ownerId": "string", "rating": 0, "rightToWork": true, "skills": [ "string" ], "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "workPermit": true, "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Parse a CV into a candidate
POST
/api/nova/candidates/parse
Uploads a CV file (pdf, doc, or docx) as multipart form data and parses it into a candidate record. After parsing, a duplicate check by email, name, and current employer is performed: if a match is found the existing candidate is returned with the duplicate flag set to true, otherwise a new candidate is created with the CV attached. The response contains the candidate ID, reference, full name, the duplicate flag, and the stored CV file's ID and name. Parsing is rate limited per minute based on the account's subscription plan, with additional hourly and daily request caps and plan-based daily and monthly parse allowances. Responds with 400 when no file is supplied, 401 for an invalid API key, and 429 when a limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Request Body
multipart/form-data
Format
"binary"Responses
OK
application/json
JSON "data": { "candidateId": "string", "cvFileId": "string", "cvFileName": "string", "duplicate": true, "name": "string", "reference": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List saved searches
GET
/api/nova/candidates/savedsearches
Lists the candidate saved searches available to the account. A saved search is created in the Recruitly app (Candidates grid, Save Search) and can express any filter criteria — tags, custom field values, statuses, sources, and more. Use the returned id as the savedSearchId parameter of GET /api/nova/candidates/search to retrieve only the candidates matching that search. Each entry carries the search's id, name, creator, creation date, and whether it is shared with the team. Responds with 401 for an invalid API key and 429 when the account's read rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": [ { "createdBy": "string", "createdOn": "dd/MM/yyyy HH:mm", "id": "string", "name": "string", "shared": true } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search candidates
GET
/api/nova/candidates/search
Runs a paged keyword search over the candidates in your account. The optional query parameter matches against candidate data, while page (default 0) and size (default 20, maximum 100) control pagination; results are sorted by creation date, newest first. Pass the optional savedSearchId parameter (from GET /api/nova/candidates/savedsearches) to return only the candidates matching that saved search's criteria — tags, custom fields, statuses, or any other filter saved in Recruitly; query then searches within the saved search's results. Returns a list of candidate records plus paging metadata and the total match count. Responds with 401 for an invalid API key and 429 when the account's read rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
savedSearchId
savedSearchId
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "alternateEmail": "string", "createdOn": "string", "currentEmployer": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "doNotContact": true, "educationHistory": [ { "endYear": 0, "grade": "string", "id": "string", "level": "string", "major": "string", "organisation": "string", "startYear": 0 } ], "email": "string", "employmentHistory": [ { "companyName": "string", "employmentType": "string", "endDate": "string", "id": "string", "jobTitle": "string", "startDate": "string", "workSummary": "string" } ], "facebook": "string", "firstName": "string", "hasCv": true, "homePhone": "string", "id": "string", "inPipeline": true, "internalNotes": "string", "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "overview": "string", "ownerId": "string", "ownerName": "string", "placed": true, "rating": 0, "reference": "string", "rightToWork": true, "skills": [ "string" ], "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "workPermit": true, "workPhone": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get a candidate
GET
/api/nova/candidates/{candidateId}
Fetches a single candidate by its ID. The response contains the full candidate record, including contact details, current employer and job title, location, skills, status, source, tags, rating, overview, internal notes, education and employment history, and custom field values. Responds with 404 if no candidate with the given ID exists, 401 for an invalid API key, and 429 when the account's read rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "alternateEmail": "string", "createdOn": "string", "currentEmployer": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "doNotContact": true, "educationHistory": [ { "endYear": 0, "grade": "string", "id": "string", "level": "string", "major": "string", "organisation": "string", "startYear": 0 } ], "email": "string", "employmentHistory": [ { "companyName": "string", "employmentType": "string", "endDate": "string", "id": "string", "jobTitle": "string", "startDate": "string", "workSummary": "string" } ], "facebook": "string", "firstName": "string", "hasCv": true, "homePhone": "string", "id": "string", "inPipeline": true, "internalNotes": "string", "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "overview": "string", "ownerId": "string", "ownerName": "string", "placed": true, "rating": 0, "reference": "string", "rightToWork": true, "skills": [ "string" ], "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "workPermit": true, "workPhone": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update a candidate
PUT
/api/nova/candidates/{candidateId}
Applies a partial update to an existing candidate. Text fields are only overwritten when supplied (name and email additionally ignore blank values), while skills, tags, education history, employment history, and custom fields are replaced wholesale when present in the body. Note that the workPermit, rightToWork, and doNotContact booleans are always taken from the request and default to false when omitted. Returns the candidate ID on success, 404 if the candidate does not exist, 401 for an invalid API key, and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "currentEmployer": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "doNotContact": true, "educationHistory": [ { "educationLevelId": "string", "endYear": 0, "grade": "string", "major": "string", "organisation": "string", "startYear": 0 } ], "email": "string", "employmentHistory": [ { "companyName": "string", "employmentTypeId": "string", "endDate": "string", "jobTitle": "string", "startDate": "string", "workSummary": "string" } ], "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "internalNotes": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "overview": "string", "ownerId": "string", "rating": 0, "rightToWork": true, "skills": [ "string" ], "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "workPermit": true, "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete a candidate
DELETE
/api/nova/candidates/{candidateId}
Deletes the candidate with the given ID. The candidate is looked up first, so a missing record responds with 404 rather than deleting silently. Returns the deleted candidate's ID on success, 401 for an invalid API key, and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update internal notes
PUT
/api/nova/candidates/{candidateId}/internalnotes
Replaces the candidate's internal notes with the text field from the request body. Internal notes are held separately from the candidate overview. Responds with 404 when the candidate does not exist, 401 for an invalid API key, and 429 when rate limited. Returns the candidate ID on success.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update candidate overview
PUT
/api/nova/candidates/{candidateId}/overview
Replaces the candidate's overview text with the text field from the request body. Responds with 404 when the candidate does not exist, 401 for an invalid API key, and 429 when rate limited. Returns the candidate ID on success.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update candidate source
PUT
/api/nova/candidates/{candidateId}/source
Sets a candidate's source to one of the source master data values. The sourceId field is required and must reference an existing source; an optional referrerId can be supplied to record the referring record against the change. Responds with 400 when sourceId is blank, 404 when the candidate or source cannot be found, and returns the candidate ID on success.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update candidate status
PUT
/api/nova/candidates/{candidateId}/status
Sets a candidate's status to one of the candidate status master data values. The statusId field is required and must reference an existing candidate status; an optional comments field is recorded with the change. Responds with 400 when statusId is missing, 404 when the candidate or status cannot be found, and returns the candidate ID on success.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace candidate tags
PUT
/api/nova/candidates/{candidateId}/tags
Replaces the candidate's entire tag set with the tags supplied in the request; existing tags not present in the request are removed. The tags field is required and sending an empty list clears all tags. Each tag has a value and an optional group; entries with a blank value are skipped. Responds with 400 when tags is missing, 404 when the candidate does not exist, and returns the candidate ID on success.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
candidateId*
candidateId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Companies
Operations
POST/api/nova/companiesGET/api/nova/companies/listGET/api/nova/companies/searchGET/api/nova/companies/{companyId}PUT/api/nova/companies/{companyId}PUT/api/nova/companies/{companyId}/internalnotesPUT/api/nova/companies/{companyId}/overviewPUT/api/nova/companies/{companyId}/sourcePUT/api/nova/companies/{companyId}/statusPUT/api/nova/companies/{companyId}/tags
Create a company
POST
/api/nova/companies
Creates a new company from the request body. Supported fields include name, description, website, email, phone, faxNo, linkedIn, facebook, twitter, domain, employeeCount, annualRevenue, foundedYear, client flag, rating, statusId and customFields (user-defined fields referenced by fieldId). The account's company record limit is checked first and a 429 is returned if it has been reached. On success the response contains the ID of the newly created company.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "annualRevenue": 0, "client": true, "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "domain": "string", "email": "string", "employeeCount": 0, "facebook": "string", "faxNo": "string", "foundedYear": 0, "id": "string", "linkedIn": "string", "name": "string", "ownerId": "string", "phone": "string", "rating": 0, "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "website": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List all companies
GET
/api/nova/companies/list
Returns a paginated list of all companies in the account, sorted by creation date with the newest first. Accepts page (default 0) and size (default 20, capped at 100) parameters. This is equivalent to calling the search endpoint with an empty query. The response includes the company records plus page, size and total count metadata.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "activeJobCount": 0, "annualRevenue": 0, "client": true, "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "domain": "string", "email": "string", "employeeCount": 0, "facebook": "string", "faxNo": "string", "foundedYear": 0, "id": "string", "industryId": "string", "industryName": "string", "lastActivityDate": "string", "linkedIn": "string", "location": "string", "name": "string", "ownerId": "string", "ownerName": "string", "parentCompanyId": "string", "parentCompanyName": "string", "phone": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "size": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "totalPlacementCount": 0, "twitter": "string", "updatedOn": "string", "website": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search companies
GET
/api/nova/companies/search
Searches companies using a free-text query and returns a paginated list. Accepts query (defaults to empty, which matches all companies), page (default 0) and size (default 20, capped at 100) parameters. Results are sorted by creation date, newest first. The response contains the matching company records plus page, size and total count metadata. Returns 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "activeJobCount": 0, "annualRevenue": 0, "client": true, "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "domain": "string", "email": "string", "employeeCount": 0, "facebook": "string", "faxNo": "string", "foundedYear": 0, "id": "string", "industryId": "string", "industryName": "string", "lastActivityDate": "string", "linkedIn": "string", "location": "string", "name": "string", "ownerId": "string", "ownerName": "string", "parentCompanyId": "string", "parentCompanyName": "string", "phone": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "size": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "totalPlacementCount": 0, "twitter": "string", "updatedOn": "string", "website": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get company by ID
GET
/api/nova/companies/{companyId}
Fetches a single company record by its ID. The response contains the full company details including status, tags, source and custom fields. Returns 404 if no company exists with the given ID, and 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "activeJobCount": 0, "annualRevenue": 0, "client": true, "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "domain": "string", "email": "string", "employeeCount": 0, "facebook": "string", "faxNo": "string", "foundedYear": 0, "id": "string", "industryId": "string", "industryName": "string", "lastActivityDate": "string", "linkedIn": "string", "location": "string", "name": "string", "ownerId": "string", "ownerName": "string", "parentCompanyId": "string", "parentCompanyName": "string", "phone": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "size": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "totalPlacementCount": 0, "twitter": "string", "updatedOn": "string", "website": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update a company
PUT
/api/nova/companies/{companyId}
Updates an existing company identified by its ID. This is a partial update: only the fields supplied in the request body overwrite the current values, and omitted fields are left unchanged. Supported fields match the create endpoint, including name, contact details, social links, company metrics, client flag, rating, statusId and customFields. Returns 404 if the company does not exist, otherwise the response contains the updated company's ID.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "annualRevenue": 0, "client": true, "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "domain": "string", "email": "string", "employeeCount": 0, "facebook": "string", "faxNo": "string", "foundedYear": 0, "id": "string", "linkedIn": "string", "name": "string", "ownerId": "string", "phone": "string", "rating": 0, "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "website": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update company internal notes
PUT
/api/nova/companies/{companyId}/internalnotes
Replaces the company's internal notes with the text supplied in the request body. Internal notes are free-form text held on the company record for internal reference. Returns 404 if the company does not exist. On success the response contains the company ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update company overview
PUT
/api/nova/companies/{companyId}/overview
Replaces the company's overview, also known as the client description, with the text supplied in the request body. The text field is written as-is to the company record. Returns 404 if the company does not exist. On success the response contains the company ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update company source
PUT
/api/nova/companies/{companyId}/source
Sets the source of a company to the source master record identified by sourceId in the request body. sourceId is required and a 400 is returned if it is blank; a 404 is returned if the company or the source record cannot be found. An optional referrerId can be supplied to record the referrer alongside the source. On success the response contains the company ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update company status
PUT
/api/nova/companies/{companyId}/status
Sets the status of a company to the status master record identified by statusId in the request body. statusId is required and a 400 is returned if it is blank. Returns 404 if either the company or the status record cannot be found. On success the response contains the company ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace company tags
PUT
/api/nova/companies/{companyId}/tags
Replaces the company's entire tag set with the list of tags supplied in the request body; any existing tags not included are removed. The tags field is required and a 400 is returned if it is missing. Returns 404 if the company does not exist. On success the response contains the company ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Contacts
Operations
POST/api/nova/contactsGET/api/nova/contacts/listGET/api/nova/contacts/searchGET/api/nova/contacts/{contactId}PUT/api/nova/contacts/{contactId}PUT/api/nova/contacts/{contactId}/internalnotesPUT/api/nova/contacts/{contactId}/overviewPUT/api/nova/contacts/{contactId}/sourcePUT/api/nova/contacts/{contactId}/statusPUT/api/nova/contacts/{contactId}/tags
Create a contact
POST
/api/nova/contacts
Creates a new contact from the request body. Supported fields include firstName, lastName, email, alternateEmail, mobile, homePhone, workPhone, jobTitle, companyId, secondaryCompanyId, ownerId, tags, linkedIn, facebook, twitter, skype, dateOfBirth, description, internalNotes, skills, statusId, sourceId and customFields (user-defined fields referenced by fieldId). The account's contact record limit is checked first and a 429 is returned if it has been reached. A duplicate check runs before the record is created: an existing contact matching on email, LinkedIn profile, or first name, surname and company combination blocks the create and responds with 409, carrying the existing contact's ID in the data field so it can be updated instead. On success the response contains the ID of the newly created contact.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "companyId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "description": "string", "email": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "internalNotes": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "ownerId": "string", "secondaryCompanyId": "string", "skills": [ "string" ], "skype": "string", "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List all contacts
GET
/api/nova/contacts/list
Returns a paginated list of all contacts in the account, sorted by creation date with the newest first. Accepts page (default 0) and size (default 20, capped at 100) parameters. This is equivalent to calling the search endpoint with an empty query. The response includes the contact records plus page, size and total count metadata.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "alternateEmail": "string", "companyId": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "description": "string", "doNotContact": true, "email": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industries": [ "string" ], "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "reference": "string", "secondaryCompanyId": "string", "secondaryCompanyName": "string", "sectors": [ "string" ], "skills": [ "string" ], "skype": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "workPhone": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search contacts
GET
/api/nova/contacts/search
Searches contacts using a free-text query and returns a paginated list. Accepts query (defaults to empty, which matches all contacts), page (default 0) and size (default 20, capped at 100) parameters. Results are sorted by creation date, newest first. The response contains the matching contact records plus page, size and total count metadata. Returns 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "alternateEmail": "string", "companyId": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "description": "string", "doNotContact": true, "email": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industries": [ "string" ], "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "reference": "string", "secondaryCompanyId": "string", "secondaryCompanyName": "string", "sectors": [ "string" ], "skills": [ "string" ], "skype": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "workPhone": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get contact by ID
GET
/api/nova/contacts/{contactId}
Fetches a single contact record by its ID. The response contains the full contact details including status, tags, source and custom fields. Returns 404 if no contact exists with the given ID, and 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "alternateEmail": "string", "companyId": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "description": "string", "doNotContact": true, "email": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industries": [ "string" ], "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "reference": "string", "secondaryCompanyId": "string", "secondaryCompanyName": "string", "sectors": [ "string" ], "skills": [ "string" ], "skype": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "workPhone": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update a contact
PUT
/api/nova/contacts/{contactId}
Updates an existing contact identified by its ID. This is a partial update: only the fields supplied in the request body overwrite the current values, and omitted fields are left unchanged. Supported fields match the create endpoint, including name, contact details, companyId, secondaryCompanyId, ownerId, tags, social links, dateOfBirth, description, internalNotes, skills, statusId, sourceId and customFields. Returns 404 if the contact does not exist, otherwise the response contains the updated contact's ID.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "companyId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "description": "string", "email": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "internalNotes": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "ownerId": "string", "secondaryCompanyId": "string", "skills": [ "string" ], "skype": "string", "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update contact internal notes
PUT
/api/nova/contacts/{contactId}/internalnotes
Replaces the contact's internal notes with the text supplied in the request body. Internal notes are free-form text held on the contact record for internal reference. Returns 404 if the contact does not exist. On success the response contains the contact ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update contact overview
PUT
/api/nova/contacts/{contactId}/overview
Replaces the contact's overview description with the text supplied in the request body. The text field is written as-is to the contact record's description. Returns 404 if the contact does not exist. On success the response contains the contact ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update contact source
PUT
/api/nova/contacts/{contactId}/source
Sets the source of a contact to the source master record identified by sourceId in the request body. sourceId is required and a 400 is returned if it is blank; a 404 is returned if the contact or the source record cannot be found. An optional referrerId can be supplied to record the referrer alongside the source. On success the response contains the contact ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update contact status
PUT
/api/nova/contacts/{contactId}/status
Sets the status of a contact to the status master record identified by statusId in the request body. statusId is required and a 400 is returned if it is blank. Returns 404 if either the contact or the status record cannot be found. On success the response contains the contact ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace contact tags
PUT
/api/nova/contacts/{contactId}/tags
Replaces the contact's entire tag set with the list of tags supplied in the request body; any existing tags not included are removed. The tags field is required and a 400 is returned if it is missing. Returns 404 if the contact does not exist. On success the response contains the contact ID with a confirmation message.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
contactId*
contactId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List custom field definitions
GET
/api/nova/customfields
Returns the account's custom field (user-defined field) definitions. Each entry contains the fieldId to use when writing customFields on create and update endpoints, the display label, the input type (for example INPUT_TEXT, INPUT_NUMBER, INPUT_DATE, YES_NO, DROPDOWN, MULTI_SELECT), the record types the field applies to, the allowed values for dropdown and multi-select fields and whether the field is mandatory. Accepts an optional recordType parameter (for example CONTACT, COMPANY, JOB, CANDIDATE, LEAD, OPPORTUNITY, PLACEMENT) to return only the definitions for that module; a 400 is returned for an unrecognised recordType. Returns 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
recordType
recordType
Type
string
Responses
OK
application/json
JSON "data": [ { "allowedValues": [ "string" ], "id": "string", "inputType": "string", "label": "string", "mandatory": true, "recordTypes": [ "string" ] } ], "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List file categories
GET
/api/nova/files/categories
Returns the account's file categories as id and name pairs. Use an id here as the optional categoryId when uploading a file, so the document lands in the right category on the record's Files tab. The only required parameter is the apiKey; returns 401 if it is invalid and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": [ { "id": "string", "name": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
List files on a record
GET
/api/nova/files/record/{recordId}
Returns the documents attached to the record given by the recordId path parameter, newest first - the same list the record's Files tab shows. Works for any record type. Accepts page and size query parameters (size defaults to 20 and is capped at 100). Each entry contains the file id, name, extension, content type, size, category, who uploaded it and when. Returns 404 when the record does not exist, 401 for an invalid API key and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
recordId*
recordId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "categoryId": "string", "categoryName": "string", "contentType": "string", "expiresOn": "string", "extension": "string", "id": "string", "name": "string", "recordId": "string", "recordLabel": "string", "recordType": "string", "showInClientPortal": true, "size": 0, "uploadedBy": "string", "uploadedOn": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Upload a file to a record
POST
/api/nova/files/upload
Stores a document as multipart form data and attaches it to the record given by recordId, so it appears on that record's Files tab. Works for any record type - job, candidate, company, contact, lead, opportunity or placement - because the type is resolved from the record itself and does not have to be supplied. categoryId is optional and, when given, is resolved against the account's file categories. Allowed file types are controlled by the account's upload extension list (docx, doc, odf, rtf, txt, csv, pdf, odt, ppt, xls, png, jpg, jpeg, tiff by default). The response contains the stored file's id, name, content type, size and the record it was linked to. Returns 400 when the file is missing, the record cannot be found, the category is unknown or the file type is not allowed, 401 for an invalid API key and 429 when the account's daily file allowance or rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Request Body
multipart/form-data
Format
"binary"Responses
OK
application/json
JSON "data": { "categoryId": "string", "categoryName": "string", "contentType": "string", "expiresOn": "string", "extension": "string", "id": "string", "name": "string", "recordId": "string", "recordLabel": "string", "recordType": "string", "showInClientPortal": true, "size": 0, "uploadedBy": "string", "uploadedOn": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Get file metadata
GET
/api/nova/files/{fileId}
Returns the stored document identified by the fileId path parameter without downloading its contents: name, extension, content type, size, category, expiry, client portal visibility, who uploaded it and when, plus the record it is attached to. Returns 404 when the file does not exist in the account, 401 for an invalid API key and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
fileId*
fileId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "categoryId": "string", "categoryName": "string", "contentType": "string", "expiresOn": "string", "extension": "string", "id": "string", "name": "string", "recordId": "string", "recordLabel": "string", "recordType": "string", "showInClientPortal": true, "size": 0, "uploadedBy": "string", "uploadedOn": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete a file
DELETE
/api/nova/files/{fileId}
Permanently removes the document identified by the fileId path parameter and detaches it from the record it was attached to, refreshing that record's search index. This cannot be undone. Returns the file id with the message Deleted on success, 404 when the file does not exist in the account, 401 for an invalid API key and 429 when the delete rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
fileId*
fileId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Download a file
GET
/api/nova/files/{fileId}/download
Streams the raw contents of the document identified by the fileId path parameter as an attachment, with the original filename in the Content-Disposition header. Unlike the other endpoints the body is the file itself, not a JSON envelope. To hand the document to a person or a browser instead of receiving the bytes, use GET /api/nova/files/{fileId}/link, which returns a short-lived direct URL. Returns 404 when the file does not exist in the account or its contents are still pending upload, 401 for an invalid API key and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
fileId*
fileId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
*/*
JSON
"string"
Get a temporary download link
GET
/api/nova/files/{fileId}/link
Returns a short-lived direct download URL for the document identified by the fileId path parameter, instead of streaming the file through the API. The link points straight at secure storage, expires 15 minutes after it is issued, and needs no API key of its own — so it can be handed to a browser or an end user. Use this when you want to give someone the file; use /download when you need the bytes themselves. Returns 404 when the file does not exist in the account or its contents are still pending upload, 401 for an invalid API key and 429 when rate limited.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
fileId*
fileId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "contentType": "string", "expiresOn": "string", "id": "string", "name": "string", "size": 0, "url": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Jobs
Operations
POST/api/nova/jobsGET/api/nova/jobs/listGET/api/nova/jobs/searchGET/api/nova/jobs/{jobId}PUT/api/nova/jobs/{jobId}DELETE/api/nova/jobs/{jobId}GET/api/nova/jobs/{jobId}/pipelinePOST/api/nova/jobs/{jobId}/pipelinePUT/api/nova/jobs/{jobId}/pipeline/{pipelineId}/statusPUT/api/nova/jobs/{jobId}/sourcePUT/api/nova/jobs/{jobId}/statusPUT/api/nova/jobs/{jobId}/tags
Create a job
POST
/api/nova/jobs
Creates a new job from the request body. Supported fields include title, description, shortDescription, internalDescription, openPositions, skills, boolean flags (remoteWorking, hot, visaSponsored, relocation, flexiHours), closingDate, startDate, rating, companyId, contactId, master-data IDs (statusId, employmentTypeId, sourceId) and customFields for user-defined fields. The account's job usage limit is checked first and a 429 is returned if it has been reached. On success the response contains the new job's ID with the message Created. Returns 401 for an invalid API key and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "closingDate": "string", "companyId": "string", "contactId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "employmentTypeId": "string", "experienceLevelId": "string", "flexiHours": true, "hot": true, "id": "string", "internalDescription": "string", "maxPay": 0, "minPay": 0, "openPositions": 0, "ownerId": "string", "payCurrency": "string", "payTenure": "string", "rating": 0, "relocation": true, "remoteWorking": true, "shortDescription": "string", "skills": [ "string" ], "sourceId": "string", "startDate": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "title": "string", "visaSponsored": true
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List jobs
GET
/api/nova/jobs/list
Lists jobs in the account by running the job search with an empty query, so both open and closed jobs are returned. Query parameters are apiKey (required) plus page and size for the response metadata; size is capped at 100. The response contains the jobs with page, size and total count. Returns 401 for an invalid API key and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "closingDate": "string", "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOpened": "string", "employmentTypeId": "string", "employmentTypeName": "string", "experienceLevelId": "string", "experienceLevelName": "string", "flexiHours": true, "hot": true, "id": "string", "internalDescription": "string", "lastActivityDate": "string", "location": "string", "maxPay": 0, "minPay": 0, "openPositions": 0, "ownerId": "string", "ownerName": "string", "payCurrency": "string", "payTenure": "string", "rating": 0, "reference": "string", "relocation": true, "remoteWorking": true, "shortDescription": "string", "skills": [ "string" ], "sourceId": "string", "sourceName": "string", "startDate": "string", "statusId": "string", "statusName": "string", "statusReason": "string", "tags": [ { "group": "string", "value": "string" } ], "title": "string", "updatedOn": "string", "visaSponsored": true } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search jobs
GET
/api/nova/jobs/search
Searches jobs in the account using a case-insensitive contains match on the query parameter against the job title, job reference, and the linked company and contact names and references. Query parameters are apiKey (required), query (the search text, empty by default), and page and size for the response metadata; size is capped at 100. The response contains the matching jobs with page, size and total count. Returns 401 for an invalid API key and 500 with an error message if the search fails.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "closingDate": "string", "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOpened": "string", "employmentTypeId": "string", "employmentTypeName": "string", "experienceLevelId": "string", "experienceLevelName": "string", "flexiHours": true, "hot": true, "id": "string", "internalDescription": "string", "lastActivityDate": "string", "location": "string", "maxPay": 0, "minPay": 0, "openPositions": 0, "ownerId": "string", "ownerName": "string", "payCurrency": "string", "payTenure": "string", "rating": 0, "reference": "string", "relocation": true, "remoteWorking": true, "shortDescription": "string", "skills": [ "string" ], "sourceId": "string", "sourceName": "string", "startDate": "string", "statusId": "string", "statusName": "string", "statusReason": "string", "tags": [ { "group": "string", "value": "string" } ], "title": "string", "updatedOn": "string", "visaSponsored": true } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get a job
GET
/api/nova/jobs/{jobId}
Fetches a single job by its ID, passed as a path variable, and returns the full job record including title, descriptions, status, company, contact, tags and custom fields. Requires the apiKey query parameter. Returns 404 if no job with the given ID exists in the account, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "closingDate": "string", "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOpened": "string", "employmentTypeId": "string", "employmentTypeName": "string", "experienceLevelId": "string", "experienceLevelName": "string", "flexiHours": true, "hot": true, "id": "string", "internalDescription": "string", "lastActivityDate": "string", "location": "string", "maxPay": 0, "minPay": 0, "openPositions": 0, "ownerId": "string", "ownerName": "string", "payCurrency": "string", "payTenure": "string", "rating": 0, "reference": "string", "relocation": true, "remoteWorking": true, "shortDescription": "string", "skills": [ "string" ], "sourceId": "string", "sourceName": "string", "startDate": "string", "statusId": "string", "statusName": "string", "statusReason": "string", "tags": [ { "group": "string", "value": "string" } ], "title": "string", "updatedOn": "string", "visaSponsored": true }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update a job
PUT
/api/nova/jobs/{jobId}
Updates an existing job identified by the jobId path variable, then saves it. Text, date and master-data fields are only applied when supplied (blank or missing values leave the current value unchanged), but the boolean flags (remoteWorking, hot, visaSponsored, relocation, flexiHours) and the companyId and contactId links are always taken from the request body, so omitting them resets those values. Accepts the same request body as job creation, including customFields. Returns the job ID with the message Updated on success, 404 if the job is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "closingDate": "string", "companyId": "string", "contactId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "employmentTypeId": "string", "experienceLevelId": "string", "flexiHours": true, "hot": true, "id": "string", "internalDescription": "string", "maxPay": 0, "minPay": 0, "openPositions": 0, "ownerId": "string", "payCurrency": "string", "payTenure": "string", "rating": 0, "relocation": true, "remoteWorking": true, "shortDescription": "string", "skills": [ "string" ], "sourceId": "string", "startDate": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "title": "string", "visaSponsored": true
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete a job
DELETE
/api/nova/jobs/{jobId}
Deletes a job identified by the jobId path variable. Internally the job is archived through the standard archive flow rather than being physically removed, so it disappears from active views. Returns the job ID with the message Deleted on success. Returns 404 if the job is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List pipeline candidates
GET
/api/nova/jobs/{jobId}/pipeline
Lists the candidates in the pipeline of the job identified by the jobId path variable, returning one entry per candidate with their current pipeline stage. Query parameters are apiKey (required) plus page and size for pagination; size is capped at 100 and pagination is applied in memory over the job's full pipeline. The response contains the pipeline entries with page, size and total count. Returns 401 for an invalid API key and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "candidateId": "string", "candidateName": "string", "createdOn": "string", "id": "string", "jobId": "string", "rejected": true, "stage": "string", "status": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Add candidate to pipeline
POST
/api/nova/jobs/{jobId}/pipeline
Attaches a candidate to the pipeline of the job identified by the jobId path variable. The request body must include candidateId and may include statusCode to choose the stage (SOURCED, APPLIED, SHORTLIST, CV_SENT, INTERVIEW, OFFER or PLACED; defaults to SOURCED) and an optional stateId for swimlane or sub-state placement. The call is idempotent: if the candidate is already in the job's pipeline the existing entry's ID is returned with the message Already exists instead of creating a duplicate. Writes go through the same pipeline service as the kanban UI, so webhooks, scorecards and the board stay in sync. Returns the new pipeline entry's ID with the message Created on success; 400 for a missing candidateId or an invalid statusCode, 404 if the job or candidate is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "candidateId": "string", "stateId": "string", "statusCode": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update pipeline status
PUT
/api/nova/jobs/{jobId}/pipeline/{pipelineId}/status
Moves a pipeline entry, identified by the pipelineId path variable, to a different stage of the job identified by the jobId path variable. The request body must include statusCode (SOURCED, APPLIED, SHORTLIST, CV_SENT, INTERVIEW, OFFER or PLACED) and may include an optional stateId to also set a swimlane or sub-state. The entry must belong to the given job; a mismatch returns 404, as does an unknown pipelineId. Returns the updated pipeline entry with the message Updated on success; 400 for a missing or invalid statusCode, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
pipelineId*
pipelineId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "stateId": "string", "statusCode": "string"
{
}
Responses
OK
application/json
JSON "data": { "candidateId": "string", "candidateName": "string", "createdOn": "string", "id": "string", "jobId": "string", "rejected": true, "stage": "string", "status": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update job source
PUT
/api/nova/jobs/{jobId}/source
Sets the source of a job identified by the jobId path variable. The request body must include sourceId, which is resolved against the account's source master data before being applied, and may include an optional referrerId to record who referred the job. Returns the job ID with the message Source updated on success. Returns 400 if sourceId is blank, 404 if the job or the source is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update job status
PUT
/api/nova/jobs/{jobId}/status
Changes the status of a job identified by the jobId path variable. The request body must include statusId, which is resolved against the account's job status master data before the change is applied; optional reasonId and comments can be supplied to record why the status changed. Returns the job ID with the message Status updated on success. Returns 400 if statusId is blank, 404 if the job or the status is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace job tags
PUT
/api/nova/jobs/{jobId}/tags
Replaces the full set of tags on a job identified by the jobId path variable. The request body must include a tags array where each tag has a value and an optional group; entries with a blank value are skipped, and the supplied set replaces the job's existing tags rather than being appended. Returns the job ID with the message Tags updated on success. Returns 400 if the tags array is missing, 404 if the job is not found, 429 if rate limited, 401 for an invalid API key, and 500 with an error message on failure.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List record activities
GET
/api/nova/journal/{recordId}
Returns journal/timeline activity entries linked to the record given by the recordId path parameter. Internally it scans the account's recent activity feed (limited by the size parameter) and keeps only entries linked to that record, so only recent activity is returned. Accepts page and size query parameters (size defaults to 20 and is capped at 100), which are echoed back in the pagination metadata. Each entry includes id, date, subject, message, type, the activity label where set, and the creating user's id and name. Returns 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
recordId*
recordId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "additionalProperties": { } } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Add a note to a record
POST
/api/nova/journal/{recordId}
Creates a timeline note against the record given by the recordId path parameter, which may be a candidate, contact, company, lead, job or placement. Only the note field is required; HTML is sanitized server-side. activityTypeId is resolved against the account's activity types and falls back to Comment when omitted or unknown, createdByUserId attributes the note to another user and defaults to the API key's own user, reminderDate accepts dd/MM/yyyy HH:mm:ss, and linkedRecordIds attaches the note to further records in addition to the one in the path so it appears on each of their timelines. Returns the created note id. Responds with 400 when the note is empty or any record - the one in the path or a linked one - cannot be found, and 401 for an invalid API key.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
recordId*
recordId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "activityTypeId": "string", "createdByUserId": "string", "linkedRecordIds": [ "string" ], "note": "string", "reminderDate": "string"
{
}
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Create a lead
POST
/api/nova/leads
Creates a new lead record. The request body accepts name, email and phone details, job title, company name, social links, website, description, employees, rating and a do-not-contact flag, plus statusId, sourceId, industryId, sectorId and custom UDF fields, all of which are resolved against the account's master data. Creation is subject to the account's API usage limits and returns 429 when the limit is exceeded. A duplicate check runs before the record is created: an existing lead matching on email, LinkedIn profile, or name and company combination blocks the create and responds with 409, carrying the existing record's ID in the data field so it can be updated instead. Contacts are included in that check unless the account allows contacts as leads. On success the new lead's id is returned. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "companyName": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "doNotContact": true, "email": "string", "employees": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industryId": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "ownerId": "string", "rating": 0, "sectorId": "string", "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "website": "string", "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List leads
GET
/api/nova/leads/list
Returns all leads in the account without any text filtering; internally this behaves like the search endpoint called with an empty query. Results are paginated with the page and size parameters; size defaults to 20 and is capped at 100, sorted by created date with the newest first. Returns a paged list of lead records along with the total count. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "alternateEmail": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "doNotContact": true, "email": "string", "employees": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industryId": "string", "industryName": "string", "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "pipelineId": "string", "pipelineName": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "website": "string", "workPhone": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search leads
GET
/api/nova/leads/search
Searches leads across the account using a free-text query supplied in the query parameter. Results are paginated with the page and size parameters; size defaults to 20 and is capped at 100, and records are sorted by created date with the newest first. Returns a paged list of lead records along with the total match count. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "alternateEmail": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "doNotContact": true, "email": "string", "employees": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industryId": "string", "industryName": "string", "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "pipelineId": "string", "pipelineName": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "website": "string", "workPhone": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get a lead
GET
/api/nova/leads/{leadId}
Fetches a single lead by its identifier. The response includes the lead's contact and company details together with industry, sector, source, pipeline, rating, employees, website, social links, description and the do-not-contact flag. Returns 404 when no lead exists with the given id and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "alternateEmail": "string", "companyName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "doNotContact": true, "email": "string", "employees": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industryId": "string", "industryName": "string", "jobTitle": "string", "lastActivityDate": "string", "lastName": "string", "linkedIn": "string", "location": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "pipelineId": "string", "pipelineName": "string", "rating": 0, "reference": "string", "sectorId": "string", "sectorName": "string", "sourceId": "string", "sourceName": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "updatedOn": "string", "website": "string", "workPhone": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update a lead
PUT
/api/nova/leads/{leadId}
Updates an existing lead identified by the path id. Fields supplied in the request body overwrite the existing values and most omitted fields are left unchanged, although the doNotContact flag is always applied and defaults to false when omitted. The statusId, sourceId, industryId and sectorId fields are resolved against the account's master data, and custom UDF fields replace the stored custom field values when provided. Returns 404 when the lead is not found and the lead id on success. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "companyName": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "doNotContact": true, "email": "string", "employees": "string", "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "industryId": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "ownerId": "string", "rating": 0, "sectorId": "string", "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "website": "string", "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete a lead
DELETE
/api/nova/leads/{leadId}
Deletes a lead by its identifier. The lead is looked up first and 404 is returned when it does not exist. On success the deleted lead's id is returned with a confirmation message. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update lead overview
PUT
/api/nova/leads/{leadId}/overview
Replaces the overview (description) text of a lead with the text supplied in the request body. The existing text is overwritten in full rather than appended to. Returns 404 when the lead is not found and the lead id on success. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "text": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update lead source
PUT
/api/nova/leads/{leadId}/source
Sets the source of a lead to the given source from the account's master data. The request body requires sourceId and accepts an optional referrerId identifying the referring record. Returns 400 when sourceId is missing and 404 when the lead or the source cannot be found. On success the lead id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update lead status
PUT
/api/nova/leads/{leadId}/status
Changes the status of a lead to the given status from the account's master data. The request body requires statusId and accepts optional comments recorded with the change. Returns 400 when statusId is missing and 404 when either the lead or the status cannot be found. On success the lead id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace lead tags
PUT
/api/nova/leads/{leadId}/tags
Replaces the full set of tags on a lead with the tags supplied in the request body; existing tags that are not included are removed. The tags field is required and may be an empty list to clear all tags. Returns 400 when tags is missing and 404 when the lead is not found. On success the lead id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
leadId*
leadId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List lookup data
GET
/api/nova/lookup
Returns static system-level lookup data in a single call: countries, languages and nationalities as code/name pairs sorted by name, plus the list of record types supported by the API. This data is the same for every account and changes rarely, so the response is publicly cacheable for 24 hours. The only required parameter is the apiKey; returns 401 if it is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List master data
GET
/api/nova/masterdata
Returns all account-level master/configuration data in a single call, grouped by type: candidate, job, company, contact, lead, opportunity, placement and invoice statuses, company types, lead and opportunity pipelines, job pipeline stages and reject reasons, job application labels, recruiting team roles, activity types, sources, industries, sectors, skills, employment types, education levels and genders. Each item is lightweight and contains only its id and name; use these ids when creating or filtering records elsewhere in the API. All 23 lists are loaded in parallel and the response is privately cacheable for 5 minutes. The only required parameter is the apiKey; returns 401 if it is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "activityTypes": [ { "id": "string", "name": "string" } ], "candidateStatuses": [ { "id": "string", "name": "string" } ], "companyStatuses": [ { "id": "string", "name": "string" } ], "companyTypes": [ { "id": "string", "name": "string" } ], "contactStatuses": [ { "id": "string", "name": "string" } ], "educationLevels": [ { "id": "string", "name": "string" } ], "employmentTypes": [ { "id": "string", "name": "string" } ], "genders": [ { "id": "string", "name": "string" } ], "industries": [ { "id": "string", "name": "string" } ], "invoiceStatuses": [ { "id": "string", "name": "string" } ], "jobApplicationLabels": [ { "id": "string", "name": "string" } ], "jobPipelineRejectReasons": [ { "id": "string", "name": "string" } ], "jobPipelineStages": [ { "id": "string", "name": "string" } ], "jobStatuses": [ { "id": "string", "name": "string" } ], "leadPipelines": [ { "id": "string", "name": "string" } ], "leadStatuses": [ { "id": "string", "name": "string" } ], "opportunityPipelines": [ { "id": "string", "name": "string" } ], "opportunityStates": [ { "id": "string", "name": "string" } ], "placementStatuses": [ { "id": "string", "name": "string" } ], "recruitingTeamRoles": [ { "id": "string", "name": "string" } ], "sectors": [ { "id": "string", "name": "string" } ], "skills": [ { "id": "string", "name": "string" } ], "sources": [ { "id": "string", "name": "string" } ] }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Opportunities
Operations
POST/api/nova/opportunitiesGET/api/nova/opportunities/listGET/api/nova/opportunities/searchGET/api/nova/opportunities/{opportunityId}PUT/api/nova/opportunities/{opportunityId}DELETE/api/nova/opportunities/{opportunityId}PUT/api/nova/opportunities/{opportunityId}/sourcePUT/api/nova/opportunities/{opportunityId}/statusPUT/api/nova/opportunities/{opportunityId}/tags
Create an opportunity
POST
/api/nova/opportunities
Creates a new opportunity record. The request body accepts name, description, probability, forecasted closing date, start date, actual closing date, estimated duration in months, a stateId resolved against the account's opportunity states, and custom UDF fields. Creation is subject to the account's API usage limits and returns 429 when the limit is exceeded. On success the new opportunity's id is returned. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "actualClosingDate": "string", "bidCurrency": "string", "bidValue": 0, "companyId": "string", "contactId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "estimatedDurationMonths": 0, "forecastedClosingDate": "string", "id": "string", "name": "string", "ownerId": "string", "probability": 0, "startDate": "string", "stateId": "string", "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List opportunities
GET
/api/nova/opportunities/list
Returns all opportunities in the account without any text filtering; internally this behaves like the search endpoint called with an empty query. Results are paginated with the page and size parameters; size defaults to 20 and is capped at 100, sorted by created date with the newest first. Returns a paged list of opportunity records along with the total count. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "actualClosingDate": "string", "bidCurrency": "string", "bidValue": 0, "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "estimatedDurationMonths": 0, "forecastedClosingDate": "string", "id": "string", "name": "string", "ownerId": "string", "ownerName": "string", "probability": 0, "reference": "string", "startDate": "string", "stateId": "string", "stateName": "string", "stateReason": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "updatedOn": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search opportunities
GET
/api/nova/opportunities/search
Searches opportunities across the account using a free-text query supplied in the query parameter. Results are paginated with the page and size parameters; size defaults to 20 and is capped at 100, and records are sorted by created date with the newest first. Returns a paged list of opportunity records along with the total match count. Responds with 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "actualClosingDate": "string", "bidCurrency": "string", "bidValue": 0, "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "estimatedDurationMonths": 0, "forecastedClosingDate": "string", "id": "string", "name": "string", "ownerId": "string", "ownerName": "string", "probability": 0, "reference": "string", "startDate": "string", "stateId": "string", "stateName": "string", "stateReason": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "updatedOn": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get an opportunity
GET
/api/nova/opportunities/{opportunityId}
Fetches a single opportunity by its identifier. The response includes the name, description, probability, forecasted and actual closing dates, start date, estimated duration in months, the linked company and contact, the current state with its reason, and the bid value with currency. Returns 404 when no opportunity exists with the given id and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "actualClosingDate": "string", "bidCurrency": "string", "bidValue": 0, "companyId": "string", "companyName": "string", "contactId": "string", "contactName": "string", "createdOn": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "estimatedDurationMonths": 0, "forecastedClosingDate": "string", "id": "string", "name": "string", "ownerId": "string", "ownerName": "string", "probability": 0, "reference": "string", "startDate": "string", "stateId": "string", "stateName": "string", "stateReason": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "updatedOn": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update an opportunity
PUT
/api/nova/opportunities/{opportunityId}
Updates an existing opportunity identified by the path id. Fields supplied in the request body overwrite the existing values and omitted fields are left unchanged; stateId is resolved against the account's opportunity states and custom UDF fields replace the stored custom field values when provided. Returns 404 when the opportunity is not found and the opportunity id on success. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "actualClosingDate": "string", "bidCurrency": "string", "bidValue": 0, "companyId": "string", "contactId": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "description": "string", "estimatedDurationMonths": 0, "forecastedClosingDate": "string", "id": "string", "name": "string", "ownerId": "string", "probability": 0, "startDate": "string", "stateId": "string", "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Delete an opportunity
DELETE
/api/nova/opportunities/{opportunityId}
Deletes an opportunity by its identifier. The opportunity is looked up first and 404 is returned when it does not exist. On success the deleted opportunity's id is returned with a confirmation message. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update opportunity source
PUT
/api/nova/opportunities/{opportunityId}/source
Sets the source of an opportunity to the given source from the account's master data. The request body requires sourceId and accepts an optional referrerId identifying the referring record. Returns 400 when sourceId is missing and 404 when the opportunity or the source cannot be found. On success the opportunity id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "referrerId": "string", "sourceId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update opportunity state
PUT
/api/nova/opportunities/{opportunityId}/status
Moves an opportunity to a different state, for example open, won or lost. The request body requires statusId referencing an opportunity state from the account's master data, and accepts an optional reasonId and comments recorded with the change. Returns 400 when statusId is missing and 404 when either the opportunity or the state cannot be found. On success the opportunity id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace opportunity tags
PUT
/api/nova/opportunities/{opportunityId}/tags
Replaces the full set of tags on an opportunity with the tags supplied in the request body; existing tags that are not included are removed. The tags field is required and may be an empty list to clear all tags. Returns 400 when tags is missing and 404 when the opportunity is not found. On success the opportunity id is returned. Responds with 401 for an invalid API key and 429 when API usage limits are exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
opportunityId*
opportunityId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Get job pipeline
GET
/api/nova/pipelines/job/{jobId}
Returns all pipeline entries (candidates) for the job given by the jobId path parameter. Each entry contains the pipeline entry id, jobId, candidateId, candidateName, the status code, the stage name, a rejected flag and the createdOn date. Accepts page and size query parameters (size defaults to 50 and is capped at 100), which are echoed back in the pagination metadata. Returns 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
50Responses
OK
application/json
JSON "data": [ { "candidateId": "string", "candidateName": "string", "createdOn": "string", "id": "string", "jobId": "string", "rejected": true, "stage": "string", "status": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
List placements
GET
/api/nova/placements/list
Returns the placements visible to the API user identified by the apiKey query parameter. This endpoint is an alias that delegates to the placement search endpoint, so it accepts the same optional query string plus page and size parameters (default 20, capped at 100), sorted by creation date descending. Returns a paged list of placement records with the total count; an invalid apiKey returns 401 and unexpected failures return 500.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "candidateId": "string", "candidateName": "string", "candidateRate": 0, "clientRate": 0, "companyId": "string", "companyName": "string", "createdOn": "string", "currency": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "endDate": "string", "fee": 0, "id": "string", "jobId": "string", "jobName": "string", "margin": 0, "ownerId": "string", "ownerName": "string", "placementDate": "string", "reference": "string", "salary": 0, "startDate": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "timeToFillDays": 0, "type": "string", "updatedOn": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Search placements
GET
/api/nova/placements/search
Searches placements using the same Elasticsearch engine as the placement UI, so the optional query parameter supports search syntax such as placementStartDate:[now-3d TO now+5d]; an empty query returns all placements. Authenticated by an apiKey query parameter tied to an API user; the user's saved and UI filters are skipped, but team and billing visibility restrictions still apply. Results are paged via page and size (default 20, capped at 100) and sorted by creation date descending. Returns a paged list of placement records with the total count; an invalid apiKey returns 401 and unexpected failures return 500.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0query
query
Type
string
size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "candidateId": "string", "candidateName": "string", "candidateRate": 0, "clientRate": 0, "companyId": "string", "companyName": "string", "createdOn": "string", "currency": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "endDate": "string", "fee": 0, "id": "string", "jobId": "string", "jobName": "string", "margin": 0, "ownerId": "string", "ownerName": "string", "placementDate": "string", "reference": "string", "salary": 0, "startDate": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "timeToFillDays": 0, "type": "string", "updatedOn": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get a placement
GET
/api/nova/placements/{placementId}
Fetches a single placement by the placementId path variable, subject to the visibility of the API user identified by the apiKey query parameter. Returns the placement record on success. Responds with 404 if the placement does not exist or is not visible to the user, 401 if the apiKey is invalid, and 500 on unexpected failures.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
placementId*
placementId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "candidateId": "string", "candidateName": "string", "candidateRate": 0, "clientRate": 0, "companyId": "string", "companyName": "string", "createdOn": "string", "currency": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "endDate": "string", "fee": 0, "id": "string", "jobId": "string", "jobName": "string", "margin": 0, "ownerId": "string", "ownerName": "string", "placementDate": "string", "reference": "string", "salary": 0, "startDate": "string", "statusId": "string", "statusName": "string", "tags": [ { "group": "string", "value": "string" } ], "timeToFillDays": 0, "type": "string", "updatedOn": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Update placement status
PUT
/api/nova/placements/{placementId}/status
Changes the status of the placement given by the placementId path variable. The JSON body must contain a statusId identifying the new status and may include optional comments; the service resolves the full status from the statusId. Authenticated by an apiKey query parameter tied to an API user whose visibility rules apply. Returns the placement id with a confirmation message on success. Responds with 400 if statusId is blank, 404 if the placement is not found or not visible, 401 if the apiKey is invalid, 429 when rate limited, and 500 on unexpected failures.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
placementId*
placementId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "comments": "string", "reasonId": "string", "statusId": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Replace placement tags
PUT
/api/nova/placements/{placementId}/tags
Replaces the full tag set of the placement given by the placementId path variable with the tags array supplied in the JSON body; existing tags not in the list are removed. Authenticated by an apiKey query parameter tied to an API user whose visibility rules apply. Returns the placement id with a confirmation message on success. Responds with 400 if the tags field is missing, 404 if the placement is not found or not visible, 401 if the apiKey is invalid, 429 when rate limited, and 500 on unexpected failures.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
placementId*
placementId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "tags": [ { "group": "string", "value": "string" } ]
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Public Jobs
Operations
GET/api/nova/public/jobsGET/api/nova/public/jobs/client/{companyId}GET/api/nova/public/jobs/countGET/api/nova/public/jobs/industriesGET/api/nova/public/jobs/languagesGET/api/nova/public/jobs/locationsGET/api/nova/public/jobs/sectorsGET/api/nova/public/jobs/skillsGET/api/nova/public/jobs/typesGET/api/nova/public/jobs/{jobId}
List published jobs
GET
/api/nova/public/jobs
Returns the tenant's open jobs for display on a public job board or website. This is a public endpoint authenticated only by a PUBLIC-role apiKey query parameter; an invalid key returns 401, and a disabled or under-review tenant returns an empty result. Supports optional location and country filters plus pageNumber, pageSize (default 20) and paginated query parameters for paging. Each job is returned as a JobModel that includes owner details and a public apply URL.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
country
country
Type
string
industries
industries
Type
string
jobTypes
jobTypes
Type
string
keywords
keywords
Type
string
location
location
Type
string
pageNumber
pageNumber
Type
integer
Format
"int32"Default
0pageSize
pageSize
Type
integer
Format
"int32"Default
20paginated
paginated
Type
boolean
Default
falsesectors
sectors
Type
string
Responses
OK
application/json
JSON "data": [ { "aiInstruction": "string", "applyEmail": "string", "applyUrl": "string", "archived": true, "bannerImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "benefits": [ "string" ], "clientBrief": "string", "companyName": "string", "cutOffDate": "dd/MM/yyyy", "description": "string", "employmentType": "string", "estClosingDate": "dd/MM/yyyy", "experience": "string", "hot": true, "id": "string", "industries": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "industry": "string", "internalDescription": "string", "jobDetailImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "jobType": "string", "languages": [ { "code": "string", "level": { "code": "string", "name": "string", "orderNumber": 0 }, "name": "string" } ], "location": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "openings": 0, "ownerId": "string", "ownerName": "string", "packageOverview": "string", "pay": { "candidateRate": 0, "currency": { "code": "string", "id": "string", "name": "string", "symbol": "string" }, "daysPerWeek": 0, "endDate": "yyyy-MM-dd", "endTime": "string", "hoursPerDay": 0, "jobEndDate": "string", "jobPayLabel": "string", "jobStartDate": "string", "label": "string", "maxPay": 0, "minPay": 0, "onCosts": 0, "payLabel": "string", "payRate": 0, "range": true, "startDate": "yyyy-MM-dd", "startTime": "string", "tenure": { "code": "string", "id": "string", "name": "string" } }, "postedOn": "dd/MM/yyyy", "publishToWebsite": true, "recruiter": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "aiAgent": true, "archived": true, "calendarColor": "string", "createdOn": "string", "disabled": true, "email": "string", "emailConnected": true, "fullName": "string", "headline": "string", "id": "string", "initials": "string", "languages": [ "string" ], "linkedIn": "string", "masterDataPrivileges": [ "string" ], "mobile": "string", "modifiedOn": "string", "modules": [ "string" ], "nickname": "string", "office": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "id": "string", "name": "string", "phone": "string" }, "privileges": { "anonymise": true, "bulkEmail": true, "bulkSms": true, "deleteData": true, "deleteEmails": true, "exportData": true, "invoiceReconciliation": true }, "profilePicUrl": "string", "role": "string", "teamId": "string", "teamName": "string", "timeZone": "string", "twoFactorEnforced": true, "uniqueId": 0, "workPhone": "string" }, "recruitingTeam": { "members": [ { "email": "string", "id": "string", "initials": "string", "name": "string", "owner": true, "profileImageUrl": "string", "role": "string" } ] }, "reference": "string", "remoteWorking": true, "scorecardTemplate": { "createdOn": "string", "generatedFrom": "string", "groups": [ { "attributes": [ { "id": "string", "label": "string" } ], "category": "string", "name": "string" } ], "modifiedByUserEmail": "string", "modifiedOn": "string" }, "sector": "string", "sectors": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "shortDescription": "string", "skills": [ "string" ], "status": "string", "tags": [ { "key": "string", "value": "string" } ], "tenantId": "string", "title": "string", "uniqueId": 0, "webAdvert": { "coreSkills": "string", "keyLanguages": "string", "mainResponsibilities": "string", "recruitmentProcess": "string", "whatWillYouLearn": "string", "whatsOnOffer": "string" } } ], "message": "string", "metadata": { }, "success": true, "totalCount": 0, "totalValue": 0
{
}
List jobs by client
GET
/api/nova/public/jobs/client/{companyId}
Returns all jobs linked to the client company given by the companyId path variable, for the tenant identified by the PUBLIC-role apiKey query parameter. The optional includeArchived flag (default false) also includes archived jobs in the results. Each job is returned as a JobModel including owner details and a public apply URL. An invalid apiKey returns 401.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
companyId*
companyId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
includeArchived
includeArchived
Type
boolean
Default
falseResponses
OK
application/json
JSON "data": [ { "aiInstruction": "string", "applyEmail": "string", "applyUrl": "string", "archived": true, "bannerImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "benefits": [ "string" ], "clientBrief": "string", "companyName": "string", "cutOffDate": "dd/MM/yyyy", "description": "string", "employmentType": "string", "estClosingDate": "dd/MM/yyyy", "experience": "string", "hot": true, "id": "string", "industries": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "industry": "string", "internalDescription": "string", "jobDetailImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "jobType": "string", "languages": [ { "code": "string", "level": { "code": "string", "name": "string", "orderNumber": 0 }, "name": "string" } ], "location": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "openings": 0, "ownerId": "string", "ownerName": "string", "packageOverview": "string", "pay": { "candidateRate": 0, "currency": { "code": "string", "id": "string", "name": "string", "symbol": "string" }, "daysPerWeek": 0, "endDate": "yyyy-MM-dd", "endTime": "string", "hoursPerDay": 0, "jobEndDate": "string", "jobPayLabel": "string", "jobStartDate": "string", "label": "string", "maxPay": 0, "minPay": 0, "onCosts": 0, "payLabel": "string", "payRate": 0, "range": true, "startDate": "yyyy-MM-dd", "startTime": "string", "tenure": { "code": "string", "id": "string", "name": "string" } }, "postedOn": "dd/MM/yyyy", "publishToWebsite": true, "recruiter": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "aiAgent": true, "archived": true, "calendarColor": "string", "createdOn": "string", "disabled": true, "email": "string", "emailConnected": true, "fullName": "string", "headline": "string", "id": "string", "initials": "string", "languages": [ "string" ], "linkedIn": "string", "masterDataPrivileges": [ "string" ], "mobile": "string", "modifiedOn": "string", "modules": [ "string" ], "nickname": "string", "office": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "id": "string", "name": "string", "phone": "string" }, "privileges": { "anonymise": true, "bulkEmail": true, "bulkSms": true, "deleteData": true, "deleteEmails": true, "exportData": true, "invoiceReconciliation": true }, "profilePicUrl": "string", "role": "string", "teamId": "string", "teamName": "string", "timeZone": "string", "twoFactorEnforced": true, "uniqueId": 0, "workPhone": "string" }, "recruitingTeam": { "members": [ { "email": "string", "id": "string", "initials": "string", "name": "string", "owner": true, "profileImageUrl": "string", "role": "string" } ] }, "reference": "string", "remoteWorking": true, "scorecardTemplate": { "createdOn": "string", "generatedFrom": "string", "groups": [ { "attributes": [ { "id": "string", "label": "string" } ], "category": "string", "name": "string" } ], "modifiedByUserEmail": "string", "modifiedOn": "string" }, "sector": "string", "sectors": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "shortDescription": "string", "skills": [ "string" ], "status": "string", "tags": [ { "key": "string", "value": "string" } ], "tenantId": "string", "title": "string", "uniqueId": 0, "webAdvert": { "coreSkills": "string", "keyLanguages": "string", "mainResponsibilities": "string", "recruitmentProcess": "string", "whatWillYouLearn": "string", "whatsOnOffer": "string" } } ], "message": "string", "metadata": { }, "success": true, "totalCount": 0, "totalValue": 0
{
}
Count published jobs
GET
/api/nova/public/jobs/count
Returns the total number of open jobs for the tenant identified by the PUBLIC-role apiKey query parameter. The response is a simple message object containing a success flag and the count. An invalid key returns 401 with success false and a count of 0.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "count": 0, "message": "string", "outcome": "string", "success": true
{
}
List industries with counts
GET
/api/nova/public/jobs/industries
Returns the tenant's configured industries, each with the number of jobs currently assigned to that industry. Industries are read in their configured position order and returned as name/count pairs. Authenticated by a PUBLIC-role apiKey query parameter; an invalid key returns 401. Useful for building industry filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON { "count": 0, "name": "string", "value": 0 }
[
]
List languages with counts
GET
/api/nova/public/jobs/languages
Returns aggregated job statistics grouped by language for the tenant identified by the PUBLIC-role apiKey query parameter. Each entry pairs a language with the number of jobs requiring it. An invalid apiKey returns 401. Useful for building language filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON
{
}
List locations with counts
GET
/api/nova/public/jobs/locations
Returns aggregated job statistics grouped by location for the tenant identified by the PUBLIC-role apiKey query parameter. Each entry pairs a location with the number of jobs there. An invalid apiKey returns 401. Useful for building location filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON
{
}
List sectors with counts
GET
/api/nova/public/jobs/sectors
Returns the tenant's configured sectors, each with the number of jobs currently assigned to that sector. Sectors are read in their configured position order and returned as name/count pairs. Authenticated by a PUBLIC-role apiKey query parameter; an invalid key returns 401. Useful for building sector filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON { "count": 0, "name": "string", "value": 0 }
[
]
List skills with counts
GET
/api/nova/public/jobs/skills
Returns aggregated job statistics grouped by skill for the tenant identified by the PUBLIC-role apiKey query parameter. Each entry pairs a skill with the number of jobs requiring it. An invalid apiKey returns 401. Useful for building skill filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON
{
}
List job types with counts
GET
/api/nova/public/jobs/types
Returns the tenant's configured employment types (e.g. permanent, contract), each with the number of jobs of that type. Types are read in their configured position order and returned as name/count pairs. Authenticated by a PUBLIC-role apiKey query parameter; an invalid key returns 401. Useful for building job type filter facets on a public job board.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON { "count": 0, "name": "string", "value": 0 }
[
]
Get a published job
GET
/api/nova/public/jobs/{jobId}
Fetches a single job for the tenant identified by the PUBLIC-role apiKey query parameter. The jobId path variable accepts either the job's internal id or, when it starts with JB-, the job's reference (e.g. JB-123). Returns the job as a JobModel including owner details and a public apply URL. Responds with 404 if no matching job exists and 401 if the apiKey is invalid.
Authorizations
publicApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
jobId*
jobId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "aiInstruction": "string", "applyEmail": "string", "applyUrl": "string", "archived": true, "bannerImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "benefits": [ "string" ], "clientBrief": "string", "companyName": "string", "cutOffDate": "dd/MM/yyyy", "description": "string", "employmentType": "string", "estClosingDate": "dd/MM/yyyy", "experience": "string", "hot": true, "id": "string", "industries": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "industry": "string", "internalDescription": "string", "jobDetailImage": { "bucket": "string", "category": "string", "categoryId": "string", "categoryName": "string", "contentType": "string", "createdOn": "string", "defaultDisplayFileInPortal": true, "docType": true, "expiresOn": "dd/MM/yyyy", "fileSize": 0, "id": "string", "imageType": true, "key": "string", "modifiedOn": "string", "name": "string", "owner": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "alternateEmail": "string", "cvId": "string", "doNotContact": true, "email": "string", "employerName": "string", "hasCv": true, "headline": "string", "homePhone": "string", "id": "string", "inSpecificJob": true, "initials": "string", "jobPipelines": [ { "jobId": "string", "jobReference": "string", "pipelineStatus": "string", "placed": true, "rejected": true, "subStatus": "string" } ], "label": "string", "labels": [ { "bgColor": "string", "filterId": "string", "id": "string", "message": "string", "name": "string", "ownerId": "string", "parentLabelId": "string", "parentLabelName": "string", "position": 0, "shared": true, "sharedSelectedUsers": true, "sharedWith": [ { "email": "string", "id": "string", "name": "string", "profileImageUrl": "string", "recordId": "string", "reference": "string", "tenantId": "string", "type": "string" } ], "success": true, "textColor": "string", "type": "string" } ], "linkedIn": "string", "mobile": "string", "ownerId": "string", "ownerName": "string", "params": { "additionalProperties": "string" }, "profileImageUrl": "string", "rating": 0, "recordType": "string", "reference": "string", "tenantId": "string", "tenantName": "string", "website": "string", "workPhone": "string" }, "reference": "string", "shared": true, "showInClientPortal": true, "signed": { "expiresOn": 0, "signedUrl": "string" }, "url": "string", "visibleToRecord": true }, "jobType": "string", "languages": [ { "code": "string", "level": { "code": "string", "name": "string", "orderNumber": 0 }, "name": "string" } ], "location": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityNameLower": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryCodeLower": "string", "countryName": "string", "fullAddressLine": "string", "geoCodingLine": "string", "hasAddressLine": true, "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasCountryCode": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string", "shortAddressLine": "string" }, "openings": 0, "ownerId": "string", "ownerName": "string", "packageOverview": "string", "pay": { "candidateRate": 0, "currency": { "code": "string", "id": "string", "name": "string", "symbol": "string" }, "daysPerWeek": 0, "endDate": "yyyy-MM-dd", "endTime": "string", "hoursPerDay": 0, "jobEndDate": "string", "jobPayLabel": "string", "jobStartDate": "string", "label": "string", "maxPay": 0, "minPay": 0, "onCosts": 0, "payLabel": "string", "payRate": 0, "range": true, "startDate": "yyyy-MM-dd", "startTime": "string", "tenure": { "code": "string", "id": "string", "name": "string" } }, "postedOn": "dd/MM/yyyy", "publishToWebsite": true, "recruiter": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "aiAgent": true, "archived": true, "calendarColor": "string", "createdOn": "string", "disabled": true, "email": "string", "emailConnected": true, "fullName": "string", "headline": "string", "id": "string", "initials": "string", "languages": [ "string" ], "linkedIn": "string", "masterDataPrivileges": [ "string" ], "mobile": "string", "modifiedOn": "string", "modules": [ "string" ], "nickname": "string", "office": { "address": { "addressLabel": "string", "addressLine": "string", "addressLine2": "string", "cityName": "string", "cityOrRegionAndPostCode": "string", "cityRegion": "string", "country": "string", "countryCode": "string", "countryName": "string", "hasCity": true, "hasCityOrRegion": true, "hasCountry": true, "hasPostcode": true, "hasRegion": true, "hasValidGeo": true, "latitude": 0, "longitude": 0, "postCode": "string", "regionName": "string" }, "id": "string", "name": "string", "phone": "string" }, "privileges": { "anonymise": true, "bulkEmail": true, "bulkSms": true, "deleteData": true, "deleteEmails": true, "exportData": true, "invoiceReconciliation": true }, "profilePicUrl": "string", "role": "string", "teamId": "string", "teamName": "string", "timeZone": "string", "twoFactorEnforced": true, "uniqueId": 0, "workPhone": "string" }, "recruitingTeam": { "members": [ { "email": "string", "id": "string", "initials": "string", "name": "string", "owner": true, "profileImageUrl": "string", "role": "string" } ] }, "reference": "string", "remoteWorking": true, "scorecardTemplate": { "createdOn": "string", "generatedFrom": "string", "groups": [ { "attributes": [ { "id": "string", "label": "string" } ], "category": "string", "name": "string" } ], "modifiedByUserEmail": "string", "modifiedOn": "string" }, "sector": "string", "sectors": [ { "category": "string", "color": "string", "createdBy": "string", "id": "string", "masterDataType": "string", "message": "string", "name": "string", "position": 0, "reasons": [ { "defaultReason": true, "id": "string", "name": "string", "orderNumber": 0, "statusId": "string" } ], "success": true, "synonyms": [ "string" ], "tenantId": "string", "type": { "code": "string", "id": "string", "name": "string" }, "userName": "string", "values": [ "string" ] } ], "shortDescription": "string", "skills": [ "string" ], "status": "string", "tags": [ { "key": "string", "value": "string" } ], "tenantId": "string", "title": "string", "uniqueId": 0, "webAdvert": { "coreSkills": "string", "keyLanguages": "string", "mainResponsibilities": "string", "recruitmentProcess": "string", "whatWillYouLearn": "string", "whatsOnOffer": "string" }
{
}
Get record by ID
GET
/api/nova/records/{recordId}
Looks up any system record (candidate, contact, company, job and other record types) by the recordId path parameter and returns a lightweight summary regardless of type. The response contains the record's id, type, label (display name), email, mobile and reference. Useful for resolving an unknown record id to its type before calling the type-specific endpoints. Returns 404 if the record is not found, and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
recordId*
recordId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List open tasks
GET
/api/nova/tasks/list
Returns the authenticated user's open (not yet completed) tasks. Accepts page and size query parameters (size defaults to 20 and is capped at 100), which are echoed back in the pagination metadata. Each task includes id, title, note, type, dueDate, completed, createdOn, the first assignee (assignedToId, assignedToName) and the first linked record (linkedToId, linkedToName) where present. Returns 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
page
page
Type
integer
Format
"int32"Default
0size
size
Type
integer
Format
"int32"Default
20Responses
OK
application/json
JSON "data": [ { "additionalProperties": { } } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get task by ID
GET
/api/nova/tasks/{taskId}
Fetches a single task by the taskId path parameter, scoped to the authenticated API user's account. The response includes id, title, note, type, dueDate, completed, createdOn, the first assignee (assignedToId, assignedToName) and the first linked record (linkedToId, linkedToName) where present. Returns 404 if the task is not found, and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
taskId*
taskId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
List users
GET
/api/nova/users/list
Returns all users on the account that are visible to the authenticated API user, in a single unpaginated list. Each item contains the user's id, firstName, lastName, email, mobile, role, jobTitle and active flag. The only required parameter is the apiKey. Returns 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": [ { "active": true, "email": "string", "firstName": "string", "id": "string", "jobTitle": "string", "lastName": "string", "mobile": "string", "role": "string" } ], "error": "string", "message": "string", "page": 0, "requestId": "string", "size": 0, "success": true, "total": 0
{
}
Get current user
GET
/api/nova/users/me
Resolves the supplied API key and returns the profile of the user the key belongs to. The response contains the user's id, firstName, lastName, email, mobile, role, jobTitle and active flag. Use this to identify the authenticated user before making other calls. Returns 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "active": true, "email": "string", "firstName": "string", "id": "string", "jobTitle": "string", "lastName": "string", "mobile": "string", "role": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}
Get user by ID
GET
/api/nova/users/{userId}
Fetches a single user by the userId path parameter, scoped to the authenticated API user's account. The response contains the user's id, firstName, lastName, email, mobile, role, jobTitle and active flag. Returns 404 if no matching user is found, and 401 if the API key is invalid.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Path Parameters
userId*
userId
Type
Requiredstring
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Responses
OK
application/json
JSON "data": { "active": true, "email": "string", "firstName": "string", "id": "string", "jobTitle": "string", "lastName": "string", "mobile": "string", "role": "string" }, "error": "string", "message": "string", "requestId": "string", "success": true
{
}