Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

Ordinances and Reservations

Note: This information is only intended for partnering organizations who have signed the ordinance access addendum with FamilySearch.

The FamilySearch API provides resources to reserve ordinances, read completed ordinances, see the status of ordinances, and print cards that can be taken to the temple for ordinance work to be done.

Only certain users have access to ordinances and reservations. The Ordinances resource can be used to determine if the current user has access to ordinances and reservations. An attempt to GET the Ordinances resource by a user who does not have access will be forbidden.

Changes to Ordinance Reservation status codes will be released in 2020 - Q3 release in August. Please refer to the Shared Ready Migration Guide for the August 2020 status code changes.

Object Model

An "ordinance" is a sacred, formal act performed by the authority of the priesthood of the Church of Jesus Christ of Latter-day Saints. For each person, each type of ordinance has a "status" denoting whether the ordinance is ready to be performed, is in progress, has been completed, etc. A "reservation" is an ordinance that has not yet been completed. For additional details regarding this Model, please refer to the following resource pages:

  • Ordinance (JSON, XML)
    • type: (enum) OrdinanceType (Documentation)
    • status: (enum) OrdinanceStatus (Documentation)
    • statusReasons: (enum) OrdinanceStatusReason (Documentation)
    • actions: OrdinanceActions (JSON, XML)
    • sexType: (enum) OrdinanceSexType (Documentation)
    • participants: (array) OrdinanceParticipant (JSON, XML)
    • reservation: OrdinanceReservation (JSON, XML)
      • owner: ResourceReference (XML, JSON)
      • assigneeType: (enum) OrdinanceReservationAssigneeType (Documentation)
      • reserveDate
      • updateDate
      • expirationDate
    • secondaryReservation: OrdinanceReservation
    • callerReservation: OrdinanceReservation
    • OrdinanceRollup (JSON, XML)

Please note the following:

  1. The namespaces for the enum values may be churchofjesuschrist.org or familysearch.org, depending on whether it is related to a religious-related enumeration or an application-related enumeration.
  2. The participants object is only present when documenting the relationship of the focused person with their parents or spouse.

Ordinances

The Ordinances resource allows you to read all ordinances for a person or multiple persons. Ordinance information can be requested for multiple persons by including multiple pid parameters in the query string.

Each ordinance may be in a different state (ready, reserved, in progress, completed, etc.), which is provided by the ordinance status. Completed ordinances include a location and date they were performed.

The Ordinances Rollup Status resource provides a calculation of a summary of the status of all ordinances for a person or a family. This resource can be used to provide functionality similar to the "temple icon" used by the FamilySearch Family Tree. Please note that the OrdinanceRollupStatus enumeration provides different status values from the standard OrdinanceStatus enumeration.

Reservations

Multiple reservations may exist for an Ordinance. These are tracked using the ordinance reservation, secondaryReservation, and callerReservation. Normally only a single ordinance reservation will exist, but when reservations are shared or multiple person records with reservations are merged, these other reservation attributes are set.

Viewing Reserved Ordinances

The Ordinance Reservations resource provides the list of ordinance reservations owned by the current user. Ordinance reservations are listed and grouped by the persons to which the ordinances apply.

Reserved Ordinances have an ordinance type and an OrdinanceReservation object named reservation. The OrdinanceReservation contains information regarding the owner of the reservation; timestamps for when the reservation was made, modified, and when it will expire; and an assigneeType which indicates whether the ordinance has been assigned to the Church.

Ordinance Actions

The list of boolean ordinance actions specifies the actions that are available for this Ordinance. Requesting actions not available results in an error. Here is an example of actions for an ordinance:

"actions": {
   "reservable": false,
   "unReservable": true,
   "shareable": true,
   "unShareable": false,
   "printable": true
}

Reserving Ordinances

An ordinance may be reserved by the current user if the ordinance's reservable action is true.

Before ordinances can be reserved, FamilySearch requires that each user views and acknowledges the current ordinance policy. The Ordinances Policy resource can be used to get the current ordinance policy in the language of the current user in plain text, HTML, or PDF format.

To reserve an ordinance, perform a POST request to the Ordinance Reservations resource with a payload containing information on the person and the ordinance(s) to be reserved. To view an example, see the Create Ordinance Reservations documentation.

Shared Ordinances

Beginning with the availability of the "Shared Ready" functionality, ordinances which have been shared with the temple and which have not been printed may also be reserved by the current user. In these cases, the reservable action will be true and the ordinance status will be http://familysearch.org/v1/ReservedSharedReady. In this state, the primary ordinance reservation remains set but the secondaryReservation is not set.

To reserve an ordinance in this state, perform the same POST request as would be done if it were not in a shared state. The state of the reservation will determine which type of reservation created.

When a user reserves a shared ordinance, the expiration date will be 90 days. The user who has now reserved the shared ordinance will show up as the owner of the secondaryReservation.

You may occasionally see a callerReservation on an ordinance. The ordinance callerReservation is used to track previous reservations in the case that the person record is merged or deleted. It is possible that the current user may have held a primary or secondary reservation for an ordinance, but a person merge has now overtaken the user's reservation. If the user becomes the owner of a callerReservation, the reservation will continue to show up on their reserved ordinances list, but the user may not be able to take actions such as printing or sharing.

Un-reserving Ordinances

An ordinance may be un-reserved by the current user if the ordinance's unReservable action is true.

Ordinance reservations can be unreserved by invoking the DELETE operation on the Ordinance Reservations resource with the pid parameter set to the appropriate person ID. This will unreserve all ordinances that were reserved for that person by the current user. There is no way to delete an ordinance reservation for a single ordinance type. To view an example request, see the Delete Ordinance Reservations for Current User documentation.

Sharing Ordinances

An ordinance may be shared by the current user if the ordinance's shareable action is true.

Ordinance reservations are assigned to the Church by performing a POST request to the Ordinance Reservations resource with the payload containing information on the person, the ordinance to be assigned, and a reservation object containing the assigneeType of http://churchofjesuschrist.org/Church. This is equivalent to the FamilySearch.org "Share With Temple" action. To see an example request, see the Assigning Ordinance Reservation to Temple documentation.

When this request has been processed, the ordinance status as viewed by the user who shared the reservation will be set to http://familysearch.org/v1/ReservedShared. Other users may see a status of http://familysearch.org/v1/ReservedSharedReady and would be able to reserve the ordinance if the reservable action is set to true.

Un-sharing Ordinances

An ordinance may be un-shared by the current user if the ordinance's unShareable action is true.

The request will be the same for assigning to the Church, but with the assigneeType being set to http://churchofjesuschrist.org/Personal.

Printing Temple Ordinance Family Name Cards

An ordinance may be printed by the current user if the ordinance's printable action is true.

To receive a PDF document of temple ordinance reservations that can be printed and taken to the temple, perform a POST request to the Temple Ordinances Family Name Cards resource.

The body of the POST should contain the ordinances that are to be printed to cards. Ordinances are specified by the ordinance type and a reference to the person(s) to whom the ordinance is applicable. Ordinances of type http://churchofjesuschrist.org/SealingToSpouse require a reference to spouse. Ordinances of type http://churchofjesuschrist.org/SealingChildToParents require a reference to the parents. To view an example of these requests, see the Create a PDF file with Family Name Cards documentation.

The response of the POST will include the URI to the family name cards document. These URIs have a limited lifetime and will be removed after 24 hours. To read the family name cards PDF, perform a GET on family name card URI. This URI will be a representation of the Temple Ordinances Family Name Card resource. Please remember to set the Accept header to application/pdf or your request will fail. To view an example, see the Read a PDF file with Family Name Cards example.

Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.