Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Overview

Welcome to the Flo HRIS API! This guide explains how customers can programmatically sync candidate and job application data from Flo into their HRIS platforms. It outlines authentication, schema, examples, and the proposed solution design. Customers can use this API to retrieve the data that will be directly imported into their HRIS system.

GET /v1/job-applications

Filtering via Query Parameters

job_application_status (string, optional) – filters by pipeline stage (Application Extended, Offer Accepted, etc.)

  • This field is a set of custom statuses defined by each customer

  • The value needs to be a step in an Active Pipeline Template

  • The value is case insensitive

  • When included, only Statuses of that value are returned.

  • When omitted, all Statuses within the timeframe are returned.

  • Use Case Examples

    • Viewing data on job applications in the “Hired” Status

    • Viewing only job applications that have “Offer Rejected”

job_application_status_bucket (string, optional) – filters by pipeline status bucket (Applied, Offered, Hired etc.)

  • This represents the group of statues steps used by your organization

  • The value needs to correspond to a Bucket in the pipelines you use for jobs

  • The value is case insensitive (i.e. “HIRED” and “hired” are treated the same)

  • When included, all of the statuses with the corresponding “statusBucketName” are included in the response.

  • Use Case Examples

    • Viewing all job applications that have been in the “Offered” Status bucket

This Flo article can help with more concepts around Pipeline Building: https://help.florecruit.com/en/articles/6552344-ats-creating-and-editing-pipeline-templates

job_application_status_start (datetime with timezone, optional) – Returns job applications that had at least one status change within the specified date range. The jobApplicationStatuses array shows only status changes within that range.

Note: jobApplicationLastStatusUpdate always shows the candidate's most recent status timestamp, which may be outside your query range.

  • Default value is 30 days in the past

  • Not including a time, will default the start time to midnight of the date provided

job_application_status_end (datetime with timezone, optional) – filter candidates by last status update.

  • Not including a time will set the date to midnight of the date provided

Note on Timezones:

  • We store DateTime data in the UTC timezone

  • For the parameters above, you have the following options:

    • If you include your local timezone, we will parse that and convert to UTC time.

    • If you include a DateTime with no timezone, we will assume it is UTC time.

    • If you include a Date with no time, we will default to midnight UTC of that date.

Using these query parameters if you wanted all job applications that were in a “Hired” status in October of 2025, you would request like this:

Response Data Schema

Candidate Fields

Field Name
Data Type
Description

firstName

string

Candidate's first name

lastName

string

Candidate’s last name

email

string | null

If the user is not created with an email, value will be null

phone

string | null

Candidate phone number

candidateId

UUID string

Unique ID per candidate

candidateUrl

string

Flo URL that navigates to the Candidate's Profile in your ATS.

Job / Job Application Fields

Field Name
Data Type
Description

applicationId

UUID string

Unique ID per job application

jobTitle

string

Title of the job

jobId

UUID string

Unique ID per job

department

string

Department from job record

officeLocation

string

Office location from job record

employmentType

string

Employment type (Full-time, Intern, etc.)

hiringType

string

Hiring type (Lateral, Student Hiring, etc.)

jobApplicationLastStatusUpdate

datetime

Timestamp of the latest job application status change – note that this can be later than your filtered end time

position

string

Job position type

requisitionId

string | null

Job requisition id

startDate

date | null

Offer Details Start Date

salary

int | null

Offer Details Salary

addressLine1

string

Candidate address per job app

addressLine2

string

Candidate address per job app

city

string

Candidate address per job app

state

string

Candidate address per job app

zipCode

string

Candidate address per job app

jobApplicationStatuses

See Below (List of JSON)

List of job application status changes

educationHistory

See Below (List of JSON) | null

Education entries provided on the application, most recent first. When no entries exist, the field may be omitted or null; it is never an empty array.

Job Application Status Fields

Field Name
Data Type
Description

statusName

string

Name of status

statusBucketName

string

Name of status bucket

statusUpdatedAt

datetime

Time the job application entered the status

Job Application Eduction History Fields

Field Name
Data Type
Description

university

string

Name of the school as the candidate entered it. Free text, not a fixed list

degree

string | null

Degree name in readable form, for example Juris Doctor

startDate

date | null

Start date of study at the university

endDate

date | null

Graduation date, or expected graduation date for study in progress.

Job Application Custom Fields

Field Name
Data Type
Description

customFieldTitle

string

The title/question text of the custom field

customFieldAnswer

array of strings | null

Array of answer values.

  • For single-select, free text, date, numerical, monetary, and boolean questions: contains a single value

  • For multi-select questions: contains multiple values

  • If no answer exists for the question: null or empty array []

JSON Format:

Filtering Examples with Sample Data

If you would like to get the Job Applications that were moved to the “Hired” Status on October 6th, 2025 – you would structure your request like this:

The result would be the following. For simplicity, assume there is only one result in the response.

The same request with a Status of “Interviewing”

Would return

Because there is no Status Update for “Interviewing” within that time frame.

Filtering by the Status Bucket

Would return only the statuses in that bucket

Understanding Custom Fields

Custom Fields are custom questions that your organization can configure to collect additional information on job applications. These fields are returned in the customFields array for each job application.

Key Points:

  1. Visibility: Only custom fields configured with SHOW_ON_JOB_APPLICATION = TRUE are included in the API response

    1. If no Custom Fields are configured the customFields field will be not be present in the response.

  2. Answer Types: Custom fields support various question types:

    • Free Text: Text responses

    • Date: Date values (returned as string in ISO format)

    • Numerical: Numeric values (returned as string)

    • Monetary: Currency values (returned as string)

    • Single-Select: One option selected from a list

    • Multi-Select: Multiple options selected from a list

  3. Answer Format: All answers are returned as strings in the customFieldAnswer array:

    • Single-value questions (free text, date, numerical, monetary, single-select, boolean): array contains one string

    • Multi-select questions: array contains multiple strings

    • Unanswered questions: null

  4. Consistency: All custom fields configured for job applications are returned, even if they have no answer

Example Scenarios (Responses have been abbreviated to focus on Custom Fields):

Scenario 1: Job Application with Multiple Custom Fields

Scenario 2: Job Application with Unanswered Custom Fields

Note: Custom fields are organization-specific. The fields returned will match the custom field questions configured in your Flo organization settings.

Understanding Education History

Education History is the list of schools and degrees a candidate entered on their job application. These entries are returned in the educationHistory array for each job application.

Key Points:

  1. Presence: educationHistory is an array when the application has education entries.

    1. If the application collected none, the field may be absent or null. It is never an empty array.

    2. Check that the field is an array before iterating over it.

  2. Order: Entries are returned most recent first, by endDate descending. Entries with no endDate are returned first, on the basis that study still in progress is the most recent. The order is stable between requests, so repeated syncs will not show entries reordering.

  3. Per application, not per candidate: Education is captured on each job application. A candidate who applies to two jobs can have different education on each, because each application records what they entered at the time. Do not assume one set of education per candidate.

  4. Degree is a fixed set of values, safe to map on: degree returns one of the 27 values listed below, spelled exactly as shown. Map them into your HRIS by exact string match.

    1. Existing values are not renamed, so a mapping you build today keeps working.

    2. New degrees are added from time to time. Handle an unrecognised value by routing it to a default or flagging it for review rather than failing the record, so a new value cannot break a sync.

    3. Other is itself a selectable value, used when a candidate's degree is not in the list.

  5. A missing graduation date has more than one meaning: endDate is null when the candidate is still enrolled, and also when the job's application form does not collect a graduation date. The response does not distinguish between the two.

  6. Jobs that do not collect a graduation date: if the Expected Graduation Date field is turned off on a job's application form, every education entry on that job's applications is returned with endDate: null. The entries themselves are still returned in full — only the dates are withheld, matching what your team sees in Flo.

  7. Dates are entered by candidates: graduation dates are not validated, so an occasional mistyped year does occur. Because entries are ordered most recent first, a mistyped future year will sort to the top of that application's list.

Degree values:

  • Bachelor of Arts

  • Bachelor of Arts and Bachelors of Laws

  • Bachelor of Business Administration (Law) and Bachelor of Laws (Double Degree)

  • Bachelor of Commerce

  • Bachelor of Commerce and Bachelor of Laws

  • Bachelor of Economics and Bachelor of Laws

  • Bachelor of Engineering and Bachelor of Laws

  • Bachelor of Laws

  • Bachelor of Science

  • Bachelor of Sciences and Bachelor of Laws

  • Bachelor of Social Sciences and Bachelor of Laws

  • Doctor of Dentistry

  • Doctor of Medicine

  • Doctor of Osteopathic Medicine

  • Doctor of Pharmacy

  • Doctorate

  • Juris Doctor

  • Master of Arts

  • Master of Business Administration

  • Master of Education

  • Master of Finance

  • Master of Fine Arts

  • Master of Laws

  • Master of Public Administration

  • Master of Science

  • Master of Social Work

  • Other

Example Scenarios (Responses have been abbreviated to focus on Education History):

Scenario 1: Job Application with a completed and an in-progress degree

The Juris Doctor is listed first because its graduation date is the more recent of the two.

Scenario 2: Job Application where the job does not collect a graduation date

All entries are returned, with dates withheld. The order still reflects most recent first.

Scenario 3: Job Application that collected no education

educationHistory may be absent or null when no education exists. Check that it is an array rather than checking for an empty array.

Note: Education History reflects what the candidate entered on the application. It is not verified against the school, and it is separate from any education recorded on a candidate's Flo profile.

PreviousHRIS API
NextAPI Response Codes

Last updated