HTTP

All HTTP operations are applicable to the following methods: GET, PUT, POST, DELETE, HEAD, etc. However, for a given endpoint, the FamilySearch API may not support a particular HTTP operation, in which case a 405 Method Not Allowed response is provided. For example, POST is the only accepted HTTP operation on the Relationships resource.

The documentation for each endpoint includes the valid HTTP methods. To retrieve information about other supported HTTP methods, use the HTTP OPTIONS method at runtime.

If your system is capable only of making GET or POST requests, you can use the "X-HTTP-Method-Override" header. This allows you to make a POST request, but indicates that you really mean to make a PUT. Example:

POST /tree/persons/12345
X-HTTP-Method-Override: PUT

Request Header

The User-Agent request header contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent. The minimum required User-Agent information is the current version. More information is available at Mozilla.org

Common format for web browsers

User-Agent: Mozilla/ () ()

Directives
product:
A product identifier
product-version:
A version number of the product
comment:
Zero or more comments containing sub product information

Accept Header

Each resource can be represented with different data formats. The Accept header is used to request a specific format. The following examples show how to get the XML representation of a Person resource:

GET /tree/persons/12345
Accept: application/x-gedcomx-v1+xml

Or, to get the JSON representation:

GET /tree/persons/12345 Accept: application/x-gedcomx-v1+json

The value "application/x-gedcomx-v1+json" identifies the data format (a.k.a. "media type") to be returned. The documentation for each endpoint includes a list of the valid data formats.

The media types application/xml and application/json are also valid, but if a new version of the resource (e.g. x-gedcomx-v2+xml) is provided at the same URI, the system will have to guess which version you want.

If you are unable to use the Accept header, the FamilySearch API provides a convenient alternative: you can append .xml or .json to the URI for each resource, as follows:

GET /platform/collections/tree.xml

GET /platform/collections/tree.json

Authorization Header

Rather than putting the access token on the URI, the preferred way to provide the credentials is to include it on an HTTP header named Authorization. The value for the Authorization header is the string Bearer plus the access token returned when logging in to the system.

Authorization: Bearer {Token}

Expect Header

Some API resources, such as the Current Tree Person resource, return redirects. There may be some circumstances where your code can't deal with redirects. In these cases, use the X-Expect-Override header to change the HTTP response code. For example:

X-Expect-Override: 200-ok

CORS

The CORS spec defines a mechanism to enable client-side cross-origin requests. This allows restricted resources on a Web site to be requested from another domain. Sometimes a browser is required to make "preflight" requests, which doubles the latency by doubling the number of HTTP requests. The FamilySearch API recommends that the access token be put in the Authorization header, but in Web applications this forces the browser to issue preflight CORS requests because Authorization is not a "simple header." To prevent this, the access token may be included in a query parameter: accessToken=token. This workaround is only available for GET requests; POST requests without preflight requests are not allowed because the FamilySearch API requires a non-simple value in the Content-Type header for POST. Note that CORS only affects requests made on the front end from a user's browser.