Persons

The FamilySearch Person resource is used to manage information and content about individual people.

Persons have three key attributes: gender, names, and facts.

Gender is a required attribute. Three gender types are supported:

• http://gedcomx.org/Male
• http://gedcomx.org/Female
• http://gedcomx.org/Unknown

Names and Facts are discussed at length in other documents. Refer to those documents for details about the behavior of both names and facts.

Minimum Requirements for Creating a Person

All that is required to create a person is a name, a gender, and a living/deceased declaration.

{
  "persons": [
    {
      "living": true,
      "gender": {
        "type": "http://gedcomx.org/Male"
      },
      "names": [
        {
          "type": "http://gedcomx.org/BirthName",
          "preferred": true,
          "nameForms": [
            {
              "fullText": "Jacob",
              "parts": [
                {
                  "value": "Jacob",
                  "type": "http://gedcomx.org/Given"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Updating a Person

When updating a person, send information only about what is new; the entire person resource is not needed. For example, to add a birth event to someone, send this:

{
  "persons": [
    {
      "facts": [
        {
          "type": "http://gedcomx.org/Birth",
          "date": {
            "original": "3 Apr 1836",
            "formal": "+1836"
          },
          "place": {
            "original": "Kirtland, Geauga, Ohio"
          }
        }
      ]
    }
  ]
}

Normalized and Standardized Dates and Places

When creating or updating a person, dates and places for the facts of that person's life are often provided. For both dates and places, there are three different types of values: orginal, normalized and standardized.

Original: What the user or indexer typed in.

Normalized: The result of the process of identifying the meaning of the original value, the human-readable standard format of the date or place.

Standardized: A machine-readable value that is used to reference a date by a date format string (formal) or a place by an ID (description).

FamilySearch encourages you to provide a way for your users to select a date and place. You can use the FamilySearch Dates API and Places API to standardize your dates and places. However, this is not always feasible. If a date is provided to FamilySearch with an original value, and no normalized or standardized value, an attempt will be made to guess the value and fill in the normalized and standardized values automatically. Dates that don't have a normalized or standardized value are not searchable and cannot be used for temple qualification. Note that only the normalized property of the Place reference will be stored.

Living or Deceased?

Persons are declared living or deceased. To declare a person as deceased, you must either set the living property to false or provide a http://gedcomx.org/Death.

For the operations in the following table, the required property values are indicated (X indicates required).

Examples

1. A person is living.

2. A write is sent to add a burial event. The back-end fails because the person is not declared as deceased.

3. A person is deceased and has a cremation conclusion.

4. A write is sent to make the person living. The back-end fails because a cremation conclusion exists.