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/dead 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. This automatic normalization can be disabled by passing in the skipDateNormalization=true parameter. However, 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 must be declared dead or living. To declare a person as deceased, you must either set the living property to false, or provide a death event. Death events are death, burial, stillborn, or cremation.


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

OPERATION Name Gender Living Death Event Explanation
Create a Living Person X X True None
Create a Deceased Person X X False Optional
Update a Living Person to Deceased X X False X
Update a Deceased Person to Living X X True None X
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.
  1. A person is deceased and has a cremation conclusion.
  2. A write is sent to make the person living. The back-end fails because a cremation conclusion exists.
x

Select a language