ISO 8601 Date Format

ISO 8601 is the international standard for representing dates and times, maintained by the International Organization for Standardization. The Enrich Layer API uses ISO 8601 partial dates — string representations where the precision varies depending on the data source.

Many data sources only capture month and year for employment and education dates. The API preserves the original precision rather than fabricating missing day or month values.

Precision levels

The API returns dates at three levels of precision:

Why precision varies

Date precision depends on what the original data source provides:

The API never pads missing components with defaults. A date of 2023-06 means "June 2023" — not "June 1, 2023".

Where this format appears

This date format is used across the API wherever a date does not require time-of-day precision. Common examples include:

• Employment dates — start and end dates for work positions
• Education dates — enrollment and graduation periods
• Volunteer experience — activity date ranges
• Certifications and publications — issue and expiration dates

A null value for an end date typically means the activity is ongoing (e.g. a current job).

Example response

A typical API response contains dates at different precision levels:

{
  "experience": [
    {
      "title": "Senior Engineer",
      "company": "Acme Corp",
      "start_date": "2021-06",
      "end_date": null
    },
    {
      "title": "Engineer",
      "company": "Startup Inc",
      "start_date": "2018-09-01",
      "end_date": "2021-05"
    }
  ],
  "education": [
    {
      "school": "MIT",
      "start_date": "2014",
      "end_date": "2018"
    }
  ]
}

Formatting for display

Convert a partial date string into a human-readable label that matches the original precision:

function formatPartialDate(value) {
  if (!value) return "";
  const parts = value.split("-");

  if (parts.length === 3) {
    // "2024-03-15" → "March 15, 2024"
    const date = new Date(parts[0], parts[1] - 1, parts[2]);
    return new Intl.DateTimeFormat("en", {
      year: "numeric",
      month: "long",
      day: "numeric",
    }).format(date);
  }

  if (parts.length === 2) {
    // "2024-03" → "March 2024"
    const date = new Date(parts[0], parts[1] - 1);
    return new Intl.DateTimeFormat("en", {
      year: "numeric",
      month: "long",
    }).format(date);
  }

  // "2024" → "2024"
  return value;
}

Tips

• Do not pass partial dates directly to date parsing libraries — many assume missing components and produce incorrect results. Parse the string manually instead.
• When sorting by date, treat YYYY as January 1 and YYYY-MM as the first of that month for comparison purposes only.
• A null end date typically means the activity is still ongoing.
• When displaying partial dates to users, match the precision: show "March 2024" for 2024-03, not "March 1, 2024".