Initialize

Warning: OAuth 1.0 has been deprecated in favor of OAuth 2.0.

Warning: Web applications may not use this service. They should use OAuth.

The Initialize service creates a session that is unauthenticated. This call is normally followed by an Authenticate call. The two calls together have the same affect as the Login, but allows performing the actions separately.

URI

https://api.familysearch.org/identity/v2/initialize

HTTP Method

GET, POST

Parameters

&agent=: The name and version of the product calling the API, such as XYZ/2.02. You can pass this either as a parameter on a POST or GET request or in the HTTP header with the User-Agent value.
&key=: The developer key.

Developer Key

This key is required. For example:

https://api.familysearch.org/identity/v2/initialize?key=MMMM-MMMM-MMMM-MMMM-MMMM-MMMM-MMMM-MMMM

Response

After a user has signed in successfully, the family tree will return the session id in the body of the response.

Errors

Error	Possible Causes	API-Specific Examples	Implemented
310	The user needs to go to the family tree and perform some action, such as read a new version of the conditions of use.	A previously registered user needs to agree to new conditions of use before using API services.	Yes
400	Bad Request. Generic client error or multiple client errors.	Invalid agent Invalid payload or Basic Authorization header User name or password included in a GET request	Yes
401	Unauthorized. The user has invalid credentials or the session ID is missing, invalid, or has expired. This error also appears if the query string contains multiple question marks or the the session parameter contains letters in an incorrect case.	Wrong user name or password.	Yes
415	Unsupported data format, unsupported media type, invalid content-type in header, or invalid character encoding.	Post method uses wrong file format	No
431	Invalid developer key.		Yes
500	Server Error. A generic server error or multiple server errors occurred. If you get this error, please report it through devsupport@familysearch.org. You can also post it to the FamilySearch Developer Network (FSDN).		Yes
503	Service Unavailable. FamilySearch or the service that you are using is not currently available. Or you are being throttled.		Yes

Example 1: Using the GET Method

Request

GET https://api.familysearch.org/identity/v2/initialize?{key=}
  HTTP/1.1
  User-Agent: XYZ/5.0

Response

HTTP/1.0 200 OK
  Content-Type: text/xml;charset=UTF-8
  Set-Cookie: fssessionid=USYS3A4F6A6318EFA1F96AF16E1CB46D1214_ses001.app.prod.id;
   Domain=.familysearch.org; Path=/; Secure

  <?xml version="1.0" encoding="UTF-8"?>
  <identity xmlns="http://api.familysearch.org/identity/v2" version="2.7.20100604.5944" statusMessage="OK" statusCode="200">
    <session id="USYS3A4F6A6318EFA1F96AF16E1CB46D1214_ses001.app.prod.id"/>
  </identity>