General
General minimum capabilities applies to all apps that access FamilySearch resources.
The following checkbox items will be reviewed for any solution to obtain Compatible status.
Requirements for All Apps
[ ] Apply to become a Solutions Provider
[ ] Obtain acceptance in the Solutions Program
Authentication
Authentication Compatible Checklist
Authentication compatible applies to all solutions that access FamilySearch resources.
The following checkbox items will be reviewed for your solution to obtain Authentication Compatible.
All Solution Minimum Capabilities
[ ] Each user must obtain a FamilySearch access token in order to read or write to the Family Tree.
[ ] Access tokens must be protected. If a user access token is passed to a web browser in a cookie, that cookie must be a secure cookie. All cookies that give a user the ability to use an access token must also be secure cookies.
[ ] Network traffic is encrypted with SSL from the end user to the FamilySearch API.
[ ] User authentication is completed by directly calling the FamilySearch Third-Party User Authentication web page using OAuth 2 as specified by the Identity documentation as follows.
- [ ] No storage of FamilySearch usernames or passwords is permitted with web solutions.
- [ ] FamilySearch Person ID numbers can be stored by the solution.
- [ ] The FamilySearch session cookie must be a secure cookie.
- [ ] No permanent storage of FamilySearch API Session ID is permitted.
[ ] Refresh tokens can be used for selected confidential clients as determined case by case. This capability is implemented through the use of a service account.
[ ] Have a documented security policy, which is periodically reviewed, is approved by management, and is communicated to all employees.
Read Implementation Guide
Desktop and Mobile Solution Minimum Capabilities
[ ] An embedded web browser can be used to call the FamilySearch Third-Party User Authentication web page if the URL being called is clearly visible.
[ ] Native Apps must request acceptance to the following information:
[Product Name] would like to know your basic FamilySearch profile information and access data about your ancestors from the FamilySearch family tree.
[Product Name] will use this information in accordance with their respective terms of service and privacy policies.
[ ] Desktop apps may store passwords locally using 128 AES encryption. On iOS, Apple Keychain is acceptable.
Read
Read Compatible Checklist
Read compatible applies to applications that access FamilySearch resources in order to analyze, visualize, share, and publish the information. This includes reading information about persons, relationships, memories, photos, stories, documents, sources, discussions, and change history.
The following checkbox items will be reviewed for your solution to obtain Read Compatibile status.
[ ] Authentication Compatible
[ ] Demonstrate proper implementation of one or more of the following types of read operations.
Important! Each type of read operation listed below must be reviewed independently. Read compatibility for one type of read operation does not qualify your app for any other type of read operation.
- Read Changes
- Read Discussions
- Read Genealogies (prototype)
- Read Hints
- Read Memories (by person, by user, personas, comments)
- Read Person (details, pedigree, portraits, or search)
- Read Places
- Read Sources (by user, or by person)
- Read User
[ ] Demonstrate proper handling of cache. If the data you read is cached, do not store it in local memory, purge the cache if the back button is used and at the end of your user session.
[ ] Abide by the Data Security Practices specified in the Data Management section of the Compatibility Overview.
Read Implementation Guide
Record Hinting Compatible Checklist
Record Hinting helps users find sources and evidence that can be added to FamilySearch Family Tree to substantiate conclusions. Record Hinting applications can read persons, request hints, and redirect users to FamilySearch in order to examine possible matches and attach records that support conclusions.
The user must be directed to FamilySearch to analyze and attach possible matches because third-party applications do not have adequate access privileges to the FamilySearch historical records collection. This is primarily due to legal issues on what data third-party applications are allowed to show versus what FamilySearch is allowed to show. Therefore, FamilySearch.org provides pages that present the detailed information of the hinted possible matches to the user.
The following checkbox items will be reviewwed for your solution to obtain Record Hinting Compatible status.
[ ] Authentication Compatible
[ ] Read Compatible
[ ] Use the Person Match FamilySearch API resource to retrieve from FamilySearch or another collection a summary of hints of possible record matches for a Person ID. The application can show the summary and ratings of the possible matches but no additional information is provided by this API resource.
[ ] Provide a User Interface flow substantially similar to that shown in the Record Hinting document.
- The redirect to FamilySearch can open in the existing browser window, a new browser window, or a new browser tab.
- It is preferred that the solution redirects to the Possible Matches page. However, the solution can redirect to the Attach Historical Records to Family Tree page for analysis of a specific hinted record.
Tips
- If the solution remembers redirect requests to FamilySearch, when program flow is returned to the solution the solution might choose to check for and update changes to sources that have occurred at FamilySearch.
See Also
Read Genealogies Compatible Checklist
The data submitted to FamilySearch Genealogies is separate from the data in FamilySearch Family Tree. With the exception of living persons, genealogies data will be publicly visible and searchable
The following checkbox items will be reviewed for your solution to obtain Genealogies Read Compatible status.
[ ] Authentication Compatible
[ ] Read Genealogies Tree
Options
Add Persons
The FamilySearch Family Tree is essential to the purpose of FamilySearch. The growth and quality of the Family Tree are dependent on proper engagement of users. Tools, resources, and services must operate consistently and follow good practices in order to facilitate progressive contributions. Applications should encourage conformance to standards before, during, and after viewing, adding, or editing the Family Tree. All contributions should be supported by proper evidence and linked to online images of the source if possible.
A single new person or group of new persons must be added to the FamilySearch Family Tree with a relationship to someone who is already in Family Tree. Supply each new person's name, gender, birth date, birth place, christening, death date, or living flag, and if applicable death place, burial date, and burial place.
Person Add Compatible Checklist
The following checkbox items will be reviewed for your solution to obtain Person Add Compatible status.
[ ] Read Compatible
[ ] Sources Write Compatible for create and attach sources
[ ] Search for Matches returns no possible duplicates
NOTE: If possible duplicates are found, you must perform merge and not-a-match maintenance. You may optionally redirect users to the FamilySearch Possible Duplicates page to handle merging and not-a-match maintenance.
[ ] The user can add a Person as a Spouse, Parent, or Child and can add sources
[ ] Event information is Standardized
Smart Person Additions Compatible Checklist
Smart Person Additions is a feature that helps build the Family Tree by assisting users in selecting, qualifying, and adding people to the Family Tree. New people can be added to the FamilySearch Family Tree if they are related to someone who is either already in the Family Tree or is to be added to the Family Tree. People should be added only if it is programmatically determined that they are not already in the Family Tree.
When adding a person, supply the new person's name, gender, birth date, birth place, christening, death date, or living flag, and if applicable death place, burial date, and burial place.
The following checkbox items will be reviewed for a solution to obtain Smart Person Additions compatibility.
[ ] Read Compatible
[ ] Identify the people in the list who are related to someone in the FamilySearch Family Tree or to someone who is being added to the FamilySearch Family Tree.
[ ] Identify the people in the list who are already in the FamilySearch Family Tree.
Note: Each search for person matches should include the following parameters:
- First and Last Name
- Related Person(s)
- Gender (default is provided if adding a spouse)
- Date and Place of a vital event (birth, christening, marriage, death, or burial)
[ ] Generate a list of potential people to add to the FamilySearch Family Tree.
[ ] Allow the user to select people in the list to be added to the FamilySearch Family Tree.
Note: Do not allow people to be selected if they are already in the FamilySearch Family Tree or if they are not related to someone in the Family Tree.
[ ] Add the selected people to the FamilySearch Family Tree as a Spouse, Parent, or Child.
[ ] Link each newly added FamilySearch Family Tree person with the partner app person by saving the FamilySearch Family Tree Person ID with the app person data.
Plug-ins can also be used to customize web pages. Intelligent insertion of HTML and JavaScript code into specific website pages can be used by plug-ins to add different functionality or customize the rendition of those pages. This document explains how plug-ins can add features to the FamilySearch web application. These custom features may add new functionality and change the look of the FamilySearch web application.
Complimentary Plug-ins
Plug-ins that add value for FamilySearch.org customers and are friendly to FamilySearch are considered complimentary. The following are guidelines for creating and deploying plug-ins that are complimentary.
- The installation and use of the plug-in should clearly communicate the product function and company name.
- Isolate the launching and use of the third-party plug-in from FamilySearch navigation, buttons, and links. There should be no confusion about when the user is using FamilySearch features and when the user is using the third-party plug-in features.
- If the plug-in temporarily captures, analyzes, and presents data from FamilySearch, the user must first be informed and agree to allow the plug-in to use FamilySearch data.
- Temporarily stored FamilySearch data should be eliminated when the browser is closed.
- The plug-in should be “read-only”.
- If the plug-in redirects to a FamilySearch page by opening a browser window or tab, before redirection the plug-in should inform the user of what is going to happen and explain any responsibility the user has for the results obtained. For example, the plug-in should inform the user it will check for duplicates before acting on possible ordinance opportunities.
- Obtain and properly use a FamilySearch Campaign ID (CID) when calling a FamilySearch page (See “Linking to FamilySearch Pages” from your plug-in. Only use the CID assigned by FamilySearch for you specific plug-in.
Compromising Plug-ins
Plug-ins that do not add value for FamilySearch.org customers and are unfriendly to FamilySearch are considered compromising. The following are items to avoid in implementing and deploying plug-ins.
- The plug-in creates greater potential for security problems.
- User privacy could be compromised.
- FamilySearch data is usable by someone other than the authenticated user browsing FamilySearch.org.
- The added third-party features appear to be FamilySearch features.
- The plug-in is intentionally working around messaging and process requirements of the FamilySearch web application.
- The plug-in performs “screen-pushing” enabling writing to FamilySearch.org.
Preliminary Compatible Checklist
FamilySearch will not certify or reference plug-ins that do not use the FamilySearch API. The following is a simple list for plug-ins to be considered as compatible.
[ ] FamilySearch finds that the plug-in is complimentary and not compromising.
[ ] The plug-in launches a separate application that reads or writes to the FamilySearch API.
[ ] The plug-in does not insert any HTML or JavaScript code into FamilySearch web pages.
[ ] The developer intends to work with FamilySearch to improve FamilySearch features for users.
Tree Write
Tree Write Compatible Checklist
The FamilySearch Family Tree is essential to the purpose of FamilySearch. The growth and quality of the Family Tree are dependent on proper engagement of users. Tools, resources, and services must operate consistently and follow good practices in order to facilitate progressive contributions. Solutions should encourage conformance to standards before, during, and after viewing, adding, or editing the Family Tree. All contributions should be supported by proper evidence and linked to online images of the source if possible.
Tree Write compatible solutions write conclusions and make updates to the Family Tree so they must implement the principles of a source centric model in programming and user interface.
The following checkbox items are minimum capabilities for your solution to obtain Tree Write Compatible status.
[ ] Event information is standardized using normalized values from FamilySearch or the company's place authority.
[ ] Modify a Person in FamilySearch
[ ] Delete a Person or prevent deletion of Persons on FamilySearch
[ ] Person Compare and Transfer of Solution Data with FamilySearch Data
[ ] Change History and Person Restore or Redirect Users to the FamilySearch Change History ARK Page for changes and restores.
[ ] Delete and add Spousal Relationships in FamilySearch
[ ] Add, change, and delete Parent-Child Relationships in FamilySearch
[ ] Merge Persons and Perform Not-a-Match Maintenance, or Redirect Users to the FamilySearch Possible Duplicates ARK Page for merges and not-a-match maintenance
NOTE: Merging must provide the ability to reconcile sources for the person being merged in addition to comparing vital, family, and other information.
Options
- Add, Change, or Delete Person Notes in Family Tree
- Restore Merged Persons in Family Tree
- Comparisons of companyM and FamilySearch data may include notes and life sketches
- Notify of Person Changes and Other Activities
- Redirecting to FamilySearch Pages
Tree Write Implementation Guide
Genealogies Write
Genealogies Write Compatible Checklist
Prototype: This resource is currently in a prototype development state. It may or may not be operational and the interface may change prior to release. Feedback is welcome.
The simplest way to implement Genealogies is to give the user the ability to create a full tree by uploading A genealogy file that has been converted to the GEDCOMX format. Similarly the easiest way to update a tree is to replace it with a copy of a modified tree. There are options in the Genealogies Resource to actually create and maintain individual persons, facts, and relationships. Person level maintains has an extreme overhead in keeping the person data in the solution in sync with the person data in Genealogies. Genealogies Write solutions give users the following minimum capabilities.
The following features will be reviewed for your solution to obtain Genealogies Write compatible status.
Genealogies Tree Compatibility
[ ] Authenticate Compatible
Sources Write
Sources Write Compatible Checklist
Sources Write solutions give users the following capabilities.
- Create new sources
- Attach Sources to Persons
- Update Sources (Edit, Delete, Detach and Compare)
The following features will be reviewed for your solution to obtain each of the three Source Write compatible statuses
[ ] Read Compatible
[ ] Create Source
Using the Sources API Resource create sources for persons
OR
Redirect to the Create and Attach Source destination page.
[ ] When creating a source, give the user the option to enter the following information. Only the Title is required for the source to be saved.
- Title (required)
- URL
- Citation
- Notes
Attach Sources Compatible
[ ] Create Sources Compatible
Using the Sources API Resource attach sources for persons
OR
Redirect to the Create and Attach Source destination page.
[ ] When attaching a source to a person, allow the user the following options.
- Enter search parameters or person ID to find and select the person to attach sources to.
- View the person Name, person ID, birth date, birthplace, death date, death place, parents names, and spouses names if available in the results of the search.
- Set event tags such as name, gender, birth, christening, death, and burial for the source.
- Enter a reason that the source is valid. Reasons are not to be used to promote the partner or partner products.
[ ] User Interface Requirements are to make interfaces substantially similar to the following:
- Search for Family Tree persons ID
- Associate a Person or Artifact in a Third-Party Application with a Person in FamilySearch Family Tree
- Read and View Sources Contributed by the Authenticated User
- View Sources through FamilySearch Family Tree Person Page
- Create a Source
- Attach an Existing Source to a Person
Update Source Compatible
[ ] Attach Sources Compatible
[ ] Edit Sources including:
- Tree Write Compatible or message on how to avoid duplicate sources
[ ] Detach Sources or message the proper redirect to FamilySearch.org for detaching sources
[ ] Delete Sources or message the proper redirect to FamilySearch.or for deleting sources
[ ] Tree Write Compatible plus:
- Compare Sources
- Mechanisms in place to prevent duplication and preserve data integrity
- Prevent duplication of a Source on the same partner-FT connected Persons - The Partner tracks the SrcID while on this Partner person. The partner app should capture the SrcID when they copy an FT Source or Create a Source
- Preserve the Source data integrity - Capture Source conclusions and SrcRef Reason and tags.
- Maintain connected Person/Source integrity - So before a partner user can edit a Source that came from FT on that connected Person, the user must see the current FT Source values.
- When a Partner creates a new FT Person - any Sources created are attached to that FT Person. Those Sources have no dup issues on a new Person.
- At the point of connecting Person between FT and Partner (not from an Add Person workflow) no Sources flow across to FT. The user can push-pull to attach specific Sources. A connected Person that has a subsequent Source attached/detached on the FT side may or may not show up as the Partner Person side.
Options
- If you pre-populate the reason, make users aware of where and how to explain a reason if they decide to change it.
See the results of additions and attachments in FamilySearch in order to edit, or undo.
- Create, access and otherwise manage source boxes.
- When Creating a Source for a previously created memory, enable the following:
- Search and view all memories that were contributed by the current user.
- Create a source using an uploaded photo or document by using the Memory module API resources. See the how to for [Create Source With Memories] (https://familysearch.org/developers/docs/certification/memories#how2-create-source-from-a-memory) example.
- Allow the user to enter a source title, citation, and note by using the Source Descriptions API resources. See the Create Source Description example.
See Also
- Sources Write Impementation Guide
- Read and View Sources Contributed by the Authenticated User
- Contributing to Family Tree Guide
Memories Write
Memories Write Compatible Checklist
Memories Write solution give users the following minimum capabilities:
- Upload new memories.
- Edit memories and create personas, comments, and sources.
- Delete and detach memories.
The following features will be reviewed for your solution to obtain each of the three Memories Write compatible statuses.
Upload Memories Compatible
[ ] Authentication compatible.
[ ] Users can upload memories (unattached or attached to a person).
Using the Memories API Resource create memories for persons
OR
Redirect to the Memories Upload With Person Attach ARK page.
[ ] The upload agreement initially must be displayed and accepted by the users. If a device being used to upload a memory does not have a web browsing console capable of displaying the upload agreement, one of the following options must be made available:
- Print a copy of the upload agreement if the device has printing capability.
- Post on the device a hard copy of the upload agreement.
- FamilySearch Content Submission Agreement (PDF)
Edit Memories Compatible
[ ] Read compatible using at least one Memories read API.
[ ] Upload Memories certified.
[ ] Edit the titles and descriptions of memories they created.
[ ] Create personas of people in the tree on memories that they created.
[ ] Create comments to memories.
Option
- Edit the story text of a story previously uploaded
Delete Memories Compatible
[ ] Edit Memories compatible.
[ ] Delete memories that they created.
[ ] Delete personas that they created (detach from a person in the tree).
[ ] Delete memory comments.
Options
The following capabilities are not requirements, but you can include them:
- PDF upload.
- Audio upload.
- Create a source from a memory.
File Formats
FamilySearch.org accepts the following file formats or types (note that the maximum file size is 15 MB):
- Image: .bmp, .jpg, .png, .tiff
- PDF: .pdf
- Text: .txt
- Audio: .mp3, .m4a
See Also
- Memories Write Impementation Guide
- Memories guide
- Memories API resources
- Person API resources for memories and portraits
- Programming examples for Memories
Latter Day Saints
Ordinance Read Compatible Checklist
Ordinance Read compliance applies to applications that analyze FamilySearch person information in order to prepare for temple ordinance work. This includes reading information about persons, relationships, memories, photos, stories, documents, sources, discussions, and change history.
In addition to your partner status, you must sign a special addendum in order to acquire access to the FamilySearch Ordinance endpoints.
Please Note: As of June 27, 2017, FamilySearch is suspending the compatibility and approval of new applications that provide functionality for scanning, capturing or reporting (or any combination of the three) ordinance information, including those that are or may be available to take to the temple. As we evaluate the impact of these types of applications on the FamilySearch systems and the end-user experience; this suspension will remain in effect until further notice. Solutions that request limited read-access privileges may be considered based upon need and functionality. If you have any questions, please email devsupport@familysearch.org.
The following checkbox items will be reviewed for your solution to obtain Ordinance Read Compatibility.
[ ] Read Compatible
[ ] Tree Write Compatible (effective June 27, 2017)
[ ] Ordinance Addendum Signed and Approved
[ ] Pricing free for standalone ordinances apps OR no additional charge for apps to include ordinance features
Read More
[ ] Have an FamilySearch account for Latter-day Saints
[ ] Use Standardized Ordinance Icons and Statuses
[ ] Read Person(s) Ordinances
- Read ordinances on an individual
OR - Identify Persons Needing Ordinances
Crawl the tree to gather information and statuses about ancestors in order to identify ordinance opportunities.
Page Redirect Option
[ ] Display the following message at least the first time before redirecting the user to the FamilySearch Ordinance Page.
“[your product name] is provided to help you with family history research. It is not a FamilySearch product. While it can help you find ancestors who need temple ordinances, it does not replace the research that verifies the accuracy of information and that makes sure the ordinances have not already been done. Please check the information you find for accuracy, attach relevant sources, and check for possible duplicates before you reserve ordinances.”
Opportunity List
Optionally you can provide an Opportunity List. Crawl the tree to analyze couples, parents, and children that can be submitted for ordinances with very little or no additional information. Show your results in an Opportunity List indicating the individuals who need ordinances and the actions required to add the names to the user's Temple Reservation List.
Ordinance Read Implementation Guide
Ordinance Write Compatible Checklist
Ordinance Write compliance applies to applications that make temple ordinance reservations for persons in the FamilySearch database.
In addition to your partner status, you must sign a special addendum in order to acquire access to the FamilySearch Ordinance endpoints.
Please Note: As of June 27, 2017, FamilySearch is suspending the certification and approval of new applications that provide functionality for scanning, capturing or reporting (or any combination of the three) ordinance information, including those that are or may be available to take to the temple. As we evaluate the impact of these types of applications on the FamilySearch systems and the end-user experience; this suspension will remain in effect until further notice. Solutions that request limited read-access privileges may be considered based upon need and functionality. If you have any questions, please email devsupport@familysearch.org.
The following checkbox items will be reviewed for your solution to obtain Ordinance Write Compatible status.
[ ] Ordinance Read Compatible
[ ] Check for Duplicate Person Records
[ ] Prepare Persons for Submission
[ ] Query and Display the Temple Policy
[ ] Planning a Temple Visit Includes the Following
- Add persons to the Temple Reservation List.
- Select individuals and ordinances to be reserved.
- Display the Temple Reservation List showing at least the name, ordinances reserved, who the person needs to be sealed to (if applicable), and the date reserved.
[ ] Use the standard Ordinance Reservation icons and statuses. The ordinance icon legend should be easily displayed from this page. The minimum actions that must be available are to Reserve, Unreserve, and Share.
Printing Family Ordinance Requests (FORs) or Temple Cards
Printing Family Ordinance Requests (FORs) or Temple Cards is an option you can provide. Enable your application to receive FORs or Temple Cards in PDF format from FamilySearch.org and launch Adobe Acrobat or other compatible reader. The application should also allow lost or destroyed requests or cards to be reprinted.