Dates & Precision

A date carries only the precision we actually know. Career history is often recorded to the month, sometimes only to the year. Rather than invent a day, the API returns a partial date, and date filters read a partial date as the whole period it names.

Dates in responses#

Work-experience startDate and endDate — and the startDate / endDate on person vendorgraphics product associations — are strings in one of two shapes:

Format	Example	Meaning
`YYYY-MM`	`"2021-03"`	Year and month are known.
`YYYY`	`"2019"`	Only the year is known.

A null endDate means the role is current. Neither shape ever carries a day.

Warning: Don’t parse these with a fixed-format date parser. "2019" fails a YYYY-MM pattern, and a full-date parser silently fills in a month and day that were never recorded. Split on - and keep the month nullable.

JavaScript — parse a partial date

function parsePartialDate(value) {
  if (value == null) return null;
  const [year, month] = value.split("-").map((part) => parseInt(part, 10));
  return { year, month: month ?? null };
}

parsePartialDate("2021-03"); // { year: 2021, month: 3 }
parsePartialDate("2019");    // { year: 2019, month: null }

Ordering: comparing the strings lexically gives the same order the API uses — a year-only date sorts before every month of that year ("2020" before "2020-01").

Dates in filters#

Date filters accept YYYY, YYYY-MM, or YYYY-MM-DD. Each bound is widened to the full period it names: gte starts at the first day of that month or year, lte ends at the last.

Value	As `gte`	As `lte`
`"2026"`	2026-01-01	2026-12-31
`"2026-03"`	2026-03-01	2026-03-31
`"2026-03-15"`	2026-03-01	2026-03-31

Watch out: the day is accepted but ignored, so no filter is finer than a month. "lte": "2026-03-15" still matches the whole of March.

Because lte is inclusive of its whole period, the natural way to write a range is with the period you mean. People who started in the first quarter of 2026:

Request body (excerpt)

{
  "workExperience": {
    "startDate": { "gte": "2026-01", "lte": "2026-03" }
  }
}

This applies to every date filter: workExperience.startDate, workExperience.endDate, currentStartDateAtCompany, originalStartDateAtCompany, company.latestFundingDate, and on v2 the flat earliestStartDate / latestStartDate / earliestEndDate / latestEndDate.