Linking to FamilySearch Pages

FamilySearch.org is a dynamic website that changes frequently. It is possible that URLs for most website experiences could change at any given time.

Some resources such as Family Tree Persons, Record Images, Records, and Genealogy Persons need a way to be referenced in a persistent way. To address this need, Persistent Identifiers have been established for these resources. Persistent Identifiers are URIs containing a path beginning with /ark:/. Sometimes these are referred to as ARK URLs because they follow the ARK specification.

Solution Providers can connect features of FamilySearch to their app by directing users to a FamilySearch Web page. Opening a window, a tab, or a frame shows the full page.

Supported Web pages

Only two categories of links are guaranteed to remain stable over time:

1. Persistent Identifiers (ARK URLs)
2. Destination Pages (currently just the Source Create Page)

Linking to any other FamilySearch.org page is possible, but the URL is not guaranteed to remain valid - FamilySearch may change it without notice. There are currently no supported pages at all for Possible Duplicates, Discussions or Notes; don't link to these.

Persistent Identifiers (ARK URLs)

A solution provider can redirect to FamilySearch URLs that use an Archival Resource Key (ARK). ARK is a standard used by FamilySearch for long-lived “persistent identifiers” of resources.

The currently supported ARK-based addresses use a context parameter for recordHints, sourceLinker, person details, changes, memories, and person ordinances. For information on how to link to these specific experiences, see the FamilySearch ARK Decorations section of the Persistent Identifiers guide.

Note: The Platform API's tree/record persona matches endpoints (/tree/persons/{pid}/matches, /records/personas/{pid}/matches) also return ready-to-use record-hints and source-linker links directly in the response. If you're consuming those endpoints, use the links as returned rather than constructing your own — see the Campaign Identifiers section below for why this matters.

Destination Pages

Source Create Page

The purpose of this page is to make it easier for users to cite sources from non-FamilySearch locations. If your solution provides records for users to cite on FamilySearch, you may wish to integrate with this page. For information on how to use this page, see the Source Create Page guide.

Campaign Identifiers

A Campaign ID lets FamilySearch identify and report which app (App Key) sent a user to a given FamilySearch page. It's the string partner- followed by the client_id (app key) used in your OAuth2 authentication:

&cid=partner-{client_id}

Whether you need to add this yourself depends on how you got the link:

• ARK-based URLs: No Campaign ID needed. Proper calls to ARK pages are trackable automatically as long as an access token is passed appropriately.
• The Source Create Page: Requires a Campaign ID. Since you construct this link yourself, you must append cid=partner-{client_id} to it.
• Any other FamilySearch page you link to directly (not an ARK URL, not the Source Create Page): Strongly recommended you add a Campaign ID yourself. Remember that these links aren't officially supported and may break at any time — see "Supported Web Pages" above.
• Links returned directly by a Platform API response (for example, the record-hints / source-linker links from the matches endpoints): Already tagged with your Campaign ID automatically, using the client_id tied to your session. There's nothing for you to add — just use the link as returned.

Example: Building a Link Yourself vs. Using an API-Provided Link

Source Create Page (you construct this link) — you build this URL yourself using data you already have (e.g., an ARK for the record you want cited), so you're responsible for adding the Campaign ID.

Before — missing Campaign ID, not attributable to your app:
https://www.familysearch.org/source/create?ark=ark:/61903/1:1:XXXX-XXX

After — tagged with your client_id:
https://www.familysearch.org/source/create?ark=ark:/61903/1:1:XXXX-XXX&cid=partner-a1B2c3D4

Record Hints Link (returned by the Platform API) — when you call GET /platform/tree/persons/{pid}/matches, the response already includes a record-hints link with your Campaign ID attached. You never construct this URL, and it's already tagged before you see it:

{
  "rel": "record-hints",
  "href": "https://www.familysearch.org/tree/person/research-help/KWCG-65S?cid=partner-a1B2c3D4"
}

Just follow href as returned. Don't append your own cid to it — the API has already done that for you using your session's client_id, and adding a second one would just duplicate the parameter.

How to tell which case you're in: if you're the one assembling the query string from scratch, you need to add cid yourself. If the URL arrived as a href value in an API JSON response, it's already tagged — just use it.

The bottom line: if you're building the URL yourself, you're responsible for tagging it. If the API handed you the URL already built, check whether it's already tagged before adding your own.