Creating Custom Templates

The /formatter/resume/template endpoint now supports custom templates in DOCX format. This means that users can create a template that will output a CV in any format desired, with whatever data included or excluded.

Getting Started

To start a custom template, open a new Microsoft Word document. Alternatively, you can create your template in Google Drive, Apple Pages, or another app and simply export/save as a Word document. To insert data from a parsed CV into a template, you use 'tags' with the following syntax:

<<[data_to_insert_from_cv]>>

So, to insert the candidate's name, you could do:

<<[resume.ContactInformation.CandidateName.FormattedName]>>

This tag will be replaced by the FormattedName value from the parsed CV.

Formatting Output

The value output in the final document by any given tag will keep the formatting applied to the original tag in the template. Here is an example to demonstrate:

<<var [nameData = resume.ContactInformation.CandidateName]>>
<<[nameData.GivenName]>> <<[nameData.FamilyName]>>

Might result in:

Molly Adams

Also notice in the above example that we introduced a new concept, the var tag. This tag allows you to specify a named variable and assign it some value. The variable can then be used later in the template.

Default Variables

By default, the only 2 variables defined in the template are

• resume - the ResumeData containing parsed data for a given CV.
• custom - any CustomData that you send to the service. This can be non-CV data like candidate ID, date applied, etc.

Supported Tags

Below is a list of supported tags and examples.

Expression Output Tag

Used to output some information from resume or custom, or simply the result of any C# expression.

<<[expression_to_output]:"format">>

• An expression enclosed by brackets
• An optional format string enclosed by double quotes and preceded by :
• If the result of the expression is null or an empty string, then nothing will be output for that tag

Examples

Output a variable/property that is a string:

<<[some_string_var]>>

Output a date or number with formatting. For more information on formatting see the .net documentation on dates and numbers:

<<[date_var]:"yyyy-MM-dd" //outputs a date like 2023-06-02>>

<<[date_var]:"MMM dd, yyyy" //outputs a date like June 2, 2023>>

<<[number_var]:"P1" //outputs a number as a percentage with 1 decimal like 22.5% >>

<<[number_var]:"N" //outputs a number with comma separators if needed>>

Expressions can also contain C# logic as follows:

<<[some_num > 10 ? "larger" : "smaller"]>>

<<[resume.ContactInformation?.CandidateName?.FormattedName ?? "Name Unknown"] //outputs the candidate name or a default value if null>>

Operators

All of the following C# operators are supported in expressions:

Object/Array Access	x.y x?.y a[x] a?[x]
Binary	* / + - < > <= >= == != && || ??
Ternary	?:

LINQ

C# LINQ functions are available to use on any array/list data types. For a full list, see here.

<<[skill_list.Sum(item => item.MonthsExperience.Value)]>>

<<var [all_cur_wh = wh_list.Where(item => item.EndDate.IsCurrentDate)]>>

<<var [top_ten_skills = skill_list.Take(10)]>>

Create Variable Tag

Used to create a common variable that can be referenced later.

<<var [my_var_name = expression]>>

• The var keyword
• A name for the variable
• An expression whose value is assigned to the variable

Examples

<<var [nameData = resume.ContactInformation.CandidateName]>>

<<var [hasCurrentJob = resume.EmploymentHistory?.Positions?.Any(p => p?.EndDate?.IsCurrentDate ?? false) ?? false]>>

<<var [hasEducation = resume.Education?.HighestDegree != null]>>

Conditional Blocks

Used to add conditional sections/text/formatting/etc into templates.

<<if [boolean_expression]>>
Template Option 1
<<elseif [boolean_expression_2]>>
Template Option 2
<<else>>
Default Template Option
<</if>>

• an <<if [condition_expr]>>> block must be closed with an <</if>> closing tag
• the <<else>> tag is optional, and there can be only 1 <<else>> for any <<if>>
• there can be any number of <<elseif [condition_expr]>> blocks inside an if-block

Examples

The below example will format the date range of a resume.EmploymentHistory.Positions array entry called wh. The dates will only include the month if it was found in the original CV. The end date will simply be Current if the job was indicated as ongoing in the original CV.

<<if [wh.StartDate.FoundMonth]>><<[wh.StartDate.Date]:”MM/yyyy”>> <<else>><<[wh.StartDate.Date]:”yyyy”>> <</if>> - <<if [wh.EndDate.IsCurrentDate]>>Current <<elseif [wh.EndDate.FoundMonth]>> <<[wh.EndDate.Date]:”MM/yyyy”>> <<else>><<[wh.EndDate.Date]:”yyyy”>> <</if>>

This could generate any of the following based on the data from the CV:

2021 - 2023
11/2018 - 07/2022
05/2019 - Current

Foreach Loops

Loops can be used to output array/list data from a parsed CV.

<<foreach [variable_name in list_expression]>>
List Item Template
<</foreach>>

• a <<foreach ...>> block must be closed with a <</foreach>> closing tag
• the variable_name is used to reference each list item within the foreach block body
• the list_expression can be any array or list from the CV data or any expression that results in a list or array

Examples

This example would output the 3 most recent work history items in whatever format. Here we omit everything after the normalized profession description.

<<foreach [wh in resume.EmploymentHistory?.Positions.Take(3)]>>
<<[wh.NormalizedProfession?.Profession?.Description]>>
... rest of Work History item template
<</foreach>>

We can expand upon the example above by adding a nested foreach loop to output the job description with bullet points:

<<foreach [wh in resume.EmploymentHistory?.Positions.Take(3)]>>
<<[wh.NormalizedProfession?.Profession?.Description]>>
... other stuff like employer, dates, etc
<<foreach [line in wh.Description?.Replace(“\t”, “”)?.Replace(“*”, “”)?.Split(“\n”)]>>
       • <<[line]>>
<</foreach>>
<</foreach>>

The wh.Description is a single string that is usually formatted with newlines, tabs and asterisks. The above example strips out that 'plain text' formatting and displays each line in a bulleted list that looks much nicer.

Sample Templates

Below are two sample templates that you can work from. Note that for general use, you should test many CVs with these templates before using them in production.

• Sample Template 1 (example output)
• Sample Template 2 (example output)

Anonymized Templates

In many cases, you may want to have a template that has some information about the candidate that is not on the CV, as well as hiding contact information or employer names that are in the CV. Below is an example template and request body for this scenario.

• Anonymized Sample Template (example output)

Sample Request Body

{
  "OutputType": "PDF",
  "ResumeData": {},
  "Template": "...",
  "CustomData":
  {
    "CandidateId": "c13454",
    "TargetPosition": "Senior Software Developer",
    "DesiredLocation": "Amsterdam",
    "Availability": "1 month",
    "Salary": 83000,
    "Recruiter":
    {
      "Name": "Bob Smith",
      "Email": "bob.smith@textkernel.com",
      "Phone": "+1 234-567-8989"
    }
  }
}