Create Job Application

The Create Job Application endpoint lets an external integration submit a candidate’s application to a specific Nextal job. It accepts a single canonical application payload, so any integration source can post the same body shape.

Resource Path

Property	Value
url	v2/applications/{source}/{jobId}
method	POST

Headers

Field	Description
Content-Type	Media type of the request body. Must be application/json.
Accept-Language	Language of the result; if none (or an unconfigured one) is provided, the default language will be provided

Authentication

Every request must be authenticated with the tenant’s API key and domain key. Supply them either as HTTP headers:

• X-APIKey: <apiKey>
• X-Tenant: <tenant domain>

or as URL query parameters:

• napikey=<apiKey>
• ntenant=<tenant domain>

If both are provided, the HTTP headers take precedence. The tenant is derived from the domain key, which is why it is no longer a path segment. See the API Reference for details.

Parameters

Field	Description
source	the integration source/provider key assigned to your integration; it identifies where the application originates and does not change the request body schema
jobId	the target job; the server injects this value into the application’s job.jobId, overwriting any jobId placed in the body

How source works

The source path segment only identifies the integration that is submitting the application — it is recorded for tracking and routing. It does not alter the request body schema: every source posts the same canonical payload described below. Pass the provider key your integration was assigned and the jobId of the job being applied to; the tenant is derived from your domain key (see Authentication).

Caution

Your source key must be provisioned by Nextal before you can submit. Contact Nextal to have your integration source created and authorized — requests using an unknown or unauthorized source are rejected. Every request must also carry a valid API key and domain key (see Authentication).

Note

Because the server sets job.jobId from the jobId path parameter, you do not need to populate job.jobId in the body. If you do, it is ignored and replaced.

Applicant consent and personal information

A job application carries the candidate’s personal information — name, contact details, résumé, and screening answers. Before submitting an application, you must have obtained the candidate’s informed consent to collect this information and transmit it to the employer through Nextal, in accordance with applicable privacy laws, including Québec’s Law 25.

Send only the personal information needed for the application, and keep your own consent records. The receiving employer (the tenant) is responsible for the personal information once the application is submitted.

Request body

The body is a single canonical application object. All fields are optional unless noted; unknown or null fields are omitted. The top-level structure is:

Field	Type	Required	Description
locale	String	No	Locale of the application (for example en, fr_CA).
appliedOnMillis	Long	No	Epoch timestamp (milliseconds) of when the application was submitted.
job	Object (Job)	No	The job the candidate applied to. See Job object.
applicant	Object (Applicant)	Yes	The candidate and their resume. See Applicant object.
screenerQuestionsAndAnswers	Object (QuestionsAndAnswers)	No	Screener questions and the candidate’s answers. See QuestionsAndAnswers object.
demographicQuestionsAndAnswers	Object (QuestionsAndAnswers)	No	Demographic questions and answers (same shape as screener). See QuestionsAndAnswers object.
analytics	Object (Analytics)	No	Source/device analytics for the application. See Analytics object.

Job object

The jobId here is overwritten by the jobId path parameter.

Field	Type	Required	Description
jobId	String	No	Target job id. Overwritten by the path jobId.
jobTitle	String	No	Job title at the source.
jobCompany	String	No	Company name at the source.
jobLocation	String	No	Job location at the source.
jobUrl	String	No	URL of the job posting at the source.
jobMeta	String	No	Opaque source metadata.

Applicant object

Field	Type	Required	Description
id	String	No	Applicant id at the source.
fullName	String	No	Candidate full name.
email	String	No	Candidate email address.
phoneNumber	String	No	Candidate phone number.
coverletter	String	No	Cover letter text.
resume	Object (Resume)	No	The candidate resume. See Resume object.

Resume object

Provide the resume in one or more representations; a binary file plus structured json is the most complete.

Field	Type	Required	Description
text	String	No	Plain-text resume.
json	Object (Json)	No	Structured resume. See Resume json object.
file	Object (File)	No	Binary resume file. See File object.

File object

Field	Type	Required	Description
contentType	String	No	MIME type of the file (for example application/pdf).
data	String	No	Base64-encoded file content.
fileName	String	No	Original file name.

Resume json object

Structured resume data.

Field	Type	Required	Description
firstName	String	No	First name.
lastName	String	No	Last name.
headline	String	No	Professional headline.
summary	String	No	Professional summary.
publicProfileUrl	String	No	Public profile URL.
additionalInfo	String	No	Additional free-form information.
phoneNumber	String	No	Phone number.
location	Object (Location)	No	Candidate location. See Location object.
skills	String	No	Skills (free-form string).
positions	Object (Positions)	No	Work history. List wrapper, see List wrappers.
educations	Object (Educations)	No	Education history. List wrapper.
links	Object (Links)	No	External links. List wrapper.
awards	Object (Awards)	No	Awards. List wrapper.
certifications	Object (Certifications)	No	Certifications. List wrapper.
associations	Object (Associations)	No	Professional associations. List wrapper.
patents	Object (Patents)	No	Patents. List wrapper.
publications	Object (Publications)	No	Publications. List wrapper.
militaryServices	Object (MilitaryServices)	No	Military service records. List wrapper.

Location object

Field	Type	Required	Description
city	String	No	City.
country	String	No	Country.
postalCode	String	No	Postal/ZIP code.

List wrappers

Every collection inside resume.json (positions, educations, links, awards, certifications, associations, patents, publications, militaryServices) uses the same wrapper shape:

Field	Type	Required	Description
_total	Long	No	Number of entries in values.
values	List of objects	No	The entries; the element type depends on the collection (see below).

positions[].values[] (PositionValues)

Field	Type	Description
title	String	Job title.
company	String	Employer.
location	String	Location.
startDateMonth	String	Start month.
startDateYear	String	Start year.
endDateMonth	String	End month.
endDateYear	String	End year.
endCurrent	Boolean	true if this is the current position.
description	String	Description.

educations[].values[] (EducationValues)

Field	Type	Description
degree	String	Degree obtained.
field	String	Field of study.
school	String	School name.
location	String	School location.
startDate	String	Start date.
endDate	String	End date.
endCurrent	Boolean	true if currently enrolled.

links[].values[] (LinkValues)

Field	Type	Description
url	String	The link URL.

awards[].values[] (AwardValues)

Field	Type	Description
title	String	Award title.
dateMonth	String	Award month.
dateYear	String	Award year.
description	String	Description.

certifications[].values[] (CertificationValues)

Field	Type	Description
title	String	Certification title.
startDateMonth	String	Start month.
startDateYear	String	Start year.
endDateMonth	String	End month.
endDateYear	String	End year.
endCurrent	Boolean	true if currently valid.
description	String	Description.

associations[].values[] (AssociationValues)

Field	Type	Description
title	String	Association title.
startDateMonth	String	Start month.
startDateYear	String	Start year.
endDateMonth	String	End month.
endDateYear	String	End year.
endCurrent	Boolean	true if currently a member.
description	String	Description.

patents[].values[] (PatentValues)

Field	Type	Description
patentNumber	String	Patent number.
title	String	Patent title.
url	String	Patent URL.
dateMonth	String	Date month.
dateYear	String	Date year.
description	String	Description.

publications[].values[] (PublicationValues)

Field	Type	Description
title	String	Publication title.
url	String	Publication URL.
dateDay	String	Date day.
dateMonth	String	Date month.
dateYear	String	Date year.
description	String	Description.

militaryServices[].values[] (MilitaryServiceValues)

Field	Type	Description
serviceCountry	String	Country of service.
branch	String	Branch of service.
rank	String	Rank attained.
startDateMonth	String	Start month.
startDateYear	String	Start year.
endDateMonth	String	End month.
endDateYear	String	End year.
endCurrent	Boolean	true if currently serving.
commendations	String	Commendations.
description	String	Description.

QuestionsAndAnswers object

Used by both screenerQuestionsAndAnswers and demographicQuestionsAndAnswers.

Field	Type	Required	Description
url	String	No	Source URL where the questions were retrieved.
retrievedOnMillis	Long	No	Epoch timestamp (milliseconds) when the questions were retrieved.
questionsAndAnswers	List of objects (QuestionsAndAnswer)	No	One entry per question/answer pair.

questionsAndAnswers[] (QuestionsAndAnswer)

Field	Type	Required	Description
question	Object (Question)	No	The question metadata. See Question object.
answer	String, Object, or List	No	The candidate’s answer. For free-text/number/date questions it is a string; for a single select it is an object { "label": ..., "value": ... }; for a multi-select it is a list of such objects.

Question object

Field	Type	Required	Description
id	String	No	Question id.
question	String	No	The question text.
type	String	No	Question type (for example text, number, date, select, multiselect).
required	Boolean	No	Whether an answer is required.
format	String	No	Expected answer format.
min	String	No	Minimum value/length constraint.
max	String	No	Maximum value/length constraint.
limit	String	No	Answer limit.
options	List of objects (Option)	No	Selectable options, each { "label": ..., "value": ... }.
hierarchicalOptions	List	No	Hierarchical options, when applicable.

Analytics object

Field	Type	Required	Description
device	String	No	Device used to apply.
ip	String	No	Applicant IP address.
referer	String	No	Referer URL.
userAgent	String	No	Browser user agent.
sponsored	String	No	Whether the application came from a sponsored listing.
targetedApplyAd	String	No	Targeted apply ad identifier.

Examples

A complete request example:

{
  "locale": "en",
  "appliedOnMillis": 1718380800000,
  "job": {
    "jobTitle": "Senior Software Engineer",
    "jobCompany": "Acme Corp",
    "jobLocation": "Montréal, QC",
    "jobUrl": "https://example.com/jobs/123",
    "jobMeta": "src=partner"
  },
  "applicant": {
    "id": "appl_1029",
    "fullName": "Jane Doe",
    "email": "jane.doe@example.com",
    "phoneNumber": "+1-514-555-0142",
    "coverletter": "I am excited to apply for this role...",
    "resume": {
      "text": "Jane Doe — Senior Software Engineer ...",
      "json": {
        "firstName": "Jane",
        "lastName": "Doe",
        "headline": "Senior Software Engineer",
        "summary": "10+ years building distributed systems.",
        "publicProfileUrl": "https://example.com/in/janedoe",
        "phoneNumber": "+1-514-555-0142",
        "location": {
          "city": "Montréal",
          "country": "CA",
          "postalCode": "H2X 1Y4"
        },
        "skills": "Java, Spring Boot, MongoDB, Kubernetes",
        "positions": {
          "_total": 1,
          "values": [
            {
              "title": "Senior Software Engineer",
              "company": "Globex",
              "location": "Montréal, QC",
              "startDateMonth": "01",
              "startDateYear": "2019",
              "endCurrent": true,
              "description": "Lead backend engineer."
            }
          ]
        },
        "educations": {
          "_total": 1,
          "values": [
            {
              "degree": "B.Sc. Computer Science",
              "field": "Computer Science",
              "school": "McGill University",
              "location": "Montréal, QC",
              "startDate": "2011",
              "endDate": "2015",
              "endCurrent": false
            }
          ]
        },
        "links": {
          "_total": 1,
          "values": [
            { "url": "https://github.com/janedoe" }
          ]
        }
      },
      "file": {
        "contentType": "application/pdf",
        "fileName": "jane-doe-resume.pdf",
        "data": "JVBERi0xLjQKJ..."
      }
    }
  },
  "screenerQuestionsAndAnswers": {
    "url": "https://example.com/jobs/123/questions",
    "retrievedOnMillis": 1718380000000,
    "questionsAndAnswers": [
      {
        "question": {
          "id": "q1",
          "question": "Are you legally authorized to work in Canada?",
          "type": "select",
          "required": true,
          "options": [
            { "label": "Yes", "value": "yes" },
            { "label": "No", "value": "no" }
          ]
        },
        "answer": { "label": "Yes", "value": "yes" }
      },
      {
        "question": {
          "id": "q2",
          "question": "Years of experience with Java?",
          "type": "number",
          "required": true
        },
        "answer": "10"
      }
    ]
  },
  "demographicQuestionsAndAnswers": {
    "questionsAndAnswers": [
      {
        "question": {
          "id": "d1",
          "question": "How did you hear about us?",
          "type": "text",
          "required": false
        },
        "answer": "Online job board"
      }
    ]
  },
  "analytics": {
    "device": "desktop",
    "ip": "203.0.113.7",
    "referer": "https://www.example.com",
    "userAgent": "Mozilla/5.0",
    "sponsored": "false",
    "targetedApplyAd": "ad_55"
  }
}

Responses & errors

On success the endpoint returns HTTP 200 OK with an empty body — the application is accepted and queued for processing into the target tenant. There is no response payload.

Status	Meaning
200 OK	Application accepted.
400 Bad Request	The body is malformed or fails validation (for example missing applicant data, unparseable JSON).
404 Not Found	The source or jobId could not be resolved.
415 Unsupported Media Type	The Content-Type is not application/json.
500 Internal Server Error	Unexpected processing failure.

Error bodies are returned as JSON.

{
  "timestamp": "2026-06-14T12:00:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Malformed application body",
  "path": "/v2/applications/partner/5c875c8b2c17ca56a9806c9f"
}