Documentation

A. Why Use First American Mortgage Solutions APIs

1. Trusted Data and Service Provider
   1. There are 4 featured Data Services powered by our vast data sets
      • Property
      • Identity
      • Ownership
      • Liens and Judgements
2. Modern Approach to APIs
3. Comprehensive easy to use Developer Portal
4. Secure Scalable API Gateway

B. Our Approach to APIs:

1. Are organized around REST (Representational state transfer)
2. Are predictable, resource-oriented URLs
3. Are designed to use HTTP response codes to indicate API errors
4. Support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code).
5. JSON is the standard payload, Some APIs may include additional formats such as XML.
6. Commonly rely on HTTP POST methods due to the sensitive nature of most data that is exchanged, where you may have otherwise expected to find either GET or DELETE methods used. The primary purpose is to prevent sensitive search criteria from being used in the Query string, moving it instead to the Body.

C. Full Featured Developer Portal

1. Combining powerful API Management capabilities and scalable APIs, the API Store provides developers with the ideal platform to build innovative solutions.
2. Self-Provision Access to API documentation, Test UI, SandBox and Production Endpoints
3. Click on an endpoint to find out how to use it, All of the API endpoints include dynamic documentation and UI test Consoles
4. To test the endpoint, follow the instructions to fill out the path and query parameters as necessary and click "Try It Out!".

D. Secure Scalable API Gateway

1. Scalable / Resilient
2. Secure / Authentication
3. Encryption
4. Mediation
5. Quality of Service
6. Paging/Caching
7. Orchestration
8. Quota Management
9. Monitoring & Alerts

A. Sign Up

1. Sign up for an account if you don't already have one. From the homepage, click Sign Up
2. We employ two-factor authentication on sign in, so you will need access to your email to confirm your identity
3. Check the e-mail that you just registered your account under. You will have a new e-mail from DigitalGateway@firstam.io.
4. Upon Signing Up, your account will be reviewed by our site Admin and access will be granted within 1-2 business days

B. How do I log in?

1. The top navigation includes a Sign In section that is used to log into the site.
2. How do I log in if the platform Terms and Conditions change?
3. If the platform Terms of Use you signed to change, you will be required to review and agree to the new copy when you next log in.

C. Forgot password. How do I get a new password?

1. Just click on the Forgot password link and follow the simple steps.

A. Explore an API

1. Search or browse to find the API you want to use, and click to open
2. Each API specification contains
   1. An Overview of the service
   2. Dynamic Documentation including ability to test mock service, Sandbox, and Production Endpoints

B. Test an API via Mock Up Test (static request and response) without creating an APP

1. From the Dynamic Documents menu item
   1. Select the API Operation you want to test
      1. Click on “Try Me”
      2. Complete required Fields, most will be prepopulated for the Mock Test
      3. Click on “Execute”

C. Request Access and/or Test an APIs Sandbox or Production endpoints

1. An APP must first be created. See “Create an App”

A. What is an APP

1. An App describes the application that a Developer plans to integrate with one or more APIs.
2. It is not a software application running on a device, it just describes one or more of these software applications.
3. Developers use the App construct to request and manage access from their Apps to the APIs they consume, so that any software application that is using the credentials defined in the App construct will have access to APIs as negotiated.
4. The APP construct manages its identity and credentials.

B. Adding an App

1. Select from the API menu or API page, click on the “Get Access” Button to request access to a new App and provide the information the system requests.
2. Upon approval, the Credentials section is where you will be assigned the APPs ID and Key.

Find an API and Request Access

1. From within an API click on the “Get Access” Button.
2. Select the API’s you would like access to.
3. Some APIs my require you to accept our terms and conditions for SandBox Access
4. Depending on the approval settings for the endpoint, your request may be automatically approved, or may require administrator approval. You can check the status of your access request using the APIs section of your App’s navigation

Test an API End Point

1. From the APP Menu, select the API to test. Unlock icon will be displayed to the API’s you are approved to access.
2. From the API page click on the “Explore” Button
3. Select the specific API Endpoint you want to test from the “Post” button
4. Complete required Fields detailed in the “Instructions , for the request Mock Test
5. Click on “Try Me”

What are some sample REST clients I can use to test an API?

1. Examples of test clients you can use to send REST requests include: Postman, and Fiddler.
   1. Note however that many of our APIs require certain headers and API Tokens to be populated for our security schemes to work.
   2. This may make it difficult to use off the shelf clients, instead pointing more towards writing your own App in which you can implement these correctly.

A. How to get access to the Live APIs?

1. The Portal Process for Production Access is the same as Sandbox access
2. You will need to contact your First American relationship team and complete the process for gaining access to the Live environment.
3. Once the Access request has been review and approved, which may include formal Contract and/or SOW then access will be granted

B. How do I use the Live API in my application?

1. We have documentation including code snippets available for each API that will help you set up the API in your application in just a few minutes. For more information take a look at the instructions outlined on the API documentation page. However this all should be straightforward if you've worked through the Sandbox experience.

A. We use conventional HTTP response codes to indicate the success or failure of an API request.

Error Code	Error Description	Meaning
200	Success	Successful request
400	Invalid Request	Output detail is provided in response as to why the request is invalid. Required field is missing or the data is invalid. Example: "Bad Request – SSN is a required field"
401	Invalid App ID or App Key	Invalid app id or key.
500	System Error	An unexpected error has occurred. Please try again. If the problem persists, please contact Customer Service
503	Exceed usage limit	Maximum amount of usage limit has been reached for API calls.

A. What browser versions does the platform support?

1. Supported browsers and versions are:
   1. Firefox 25 and later
   2. Chrome 31 and later
   3. Internet Explorer 9 and later

B. Review Platform Term & Conditions

1. You can find the Platform Term & Conditions here

C. I can’t find the information I am looking for?

1. If you are unable to find an answer to your question, you can reach us at DigitalGateway@firstam.io

API

• An API provides a business with a way of using the Internet to extend business capabilities to connect with new customers in new ways. In this context an API is a Web service exposed outside the enterprise, typically using RESTful design principles, and often with JSON content.

API access request

• A specific type of Connection Request; a request, initiated by an app team member, to establish a contract between the app and an API. An API access request governs the relationship between an app and an API for the life of the connection. When an app team member requests a connection to an API on behalf of the app, the API administrator is notified of the pending request and can approve or deny the request.

App

• An App as seen on the Digital Gateway platform represents a piece of software that you own and operate, and that you wish to consume one or more APIs. Any credentials etc we supply for that App within Digital Gateway you will need to reflect down into your software.

App Id

• An App Id is a unique identifier assigned to each App, and defines the relationship between the App and Digital Gateway. You as a client may have more than one App on Digital Gateway. All API calls include the App Id

App team member

• Each App must have at least one team member and can have more. The app team member can view performance and usage data for the app's API usage, and can invite others to be team members for the same app. All app team members have the same rights.

Client Id

• Client Id is a unique identifier assigned to each client by your Relationship Manager and defines the relationship between your company and First American Mortgage Sulutions.

Contract

• A specific type of connection defines a consumption relationship between an app and an API. When an app admin (app team member) wants the app to be able to consume an API, he/she initiates a request for API access. The API access relationship is a contract, and is subject to an approval workflow. The contract is requested by the app team member and is approved or rejected by the API admin; it can then be cancelled or suspended by the API admin or cancelled by an app team member. The contract governs access rights and QoS (Quality of Service) policies for all transactions between the app and the API. It also provides a convenient way of collecting and presenting metrics and usage data.

Contract Request

• A request for a contract.

Dashboard

• The user's Dashboard, also called home page or feed, is the first page the user sees after logging in. The Dashboard includes information relating to apps and APIs the user is associated with. An individual user's Dashboard is an aggregation of all the Board items from all the resources that the user is following. An individual user can modify the types of information that are displayed on his/her Dashboard.

Dashboard Entry

• An informational item that appears on a user's Dashboard. The entries on a specific user's Dashboard are Board items for resources the user is following.

Developer

• A developer of an app that will consume an API.

Environment

• An API contract can apply either to the Sandbox environment, which is a testing area, or the Production environment.

Invitation Code

• A unique code generated and sent to a specific user in an email if a platform member invites the user to a platform group, such as an app team, API Admin group, or independent group. This is one of the several types of codes use to manage user signup and login.

Invitation required

• Here an invite must be issued before you can gain any type of access beyond that granted to an anonymous user. It is possible to be a self-registered user and be invited to have further access. Invitation may mean a step-up is required in terms of validating your stated identity

Invitation Status

• A value that shows a group member's relationship with the group. When a new member is invited to a group, the member has an initial status of Pending. Depending on the user's response, the status can change to Accepted or Rejected. Other possible status values are: Cancelled, Removed, or Deleted.

JSON

• An acronym for JavaScript Object Notation, JSON uses a subset of the JavaScript syntax to describe an object clearly and succinctly. One of the advantages of JSON over XML for API messages is that message content conveyed in the JSON format is much more concise than the same content conveyed in XML, consuming less bandwidth.

Leader

• In the context of a Private API Group, a leader is a senior group member. A leader can invite additional members to the group and can change another member's status, from member to leader or vice versa.

Legal Agreement (API)

• The platform allows the API Admin or Business Admin to upload one or more legal agreements associated with an API. When a legal agreement is active for an API, an app developer must accept the legal agreement in order to request a contract with the API.

License

• A License is a tailored API access package designed by the API Admin and offered to the App developer. A license includes one or more license terms, giving access to specifically designated operations, and multiple quality of service (QoS) policies, and also one or more legal agreements applicable to the license.

License Term

• A license term defines the access that is being offered in a license and the level of access (QoS policy). Each license term includes optionally, the quality of service limits/policies to be applied to all scopes in the license term. This applies to both visibility and access; policies apply only to access. To have any impact, a license term must include at least one scope.

My APIs

• The My APIs quick filter provides a list of APIs that a member who is an API Provider has added. Each API includes functional and usage documentation, and download files. Navigation: My APIs quick filter

My Apps

• The My Apps quick filter is a dashboard that displays all the apps defined by a member. The dashboard is used to manage your app workflow from setup to a live production site. Navigation: My Apps quick filter

Non-Open API

• Unlike Open APIs these serve content or functionality that requires a step-up in the level of rigor around authentication of the caller

OAuth

• OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service

Open API

• This is an API for which the content or functionality can be accessed with minimal authentication of the caller.

Private API

• Private APIs are visible to members who have been invited to join a Private API Group. Once a member has accepted a Private API invitation, the Private API is displayed with a unique icon. It gets at a minimum Documentation access, and opens a path for Runtime Key access. These APIs will not be visible in any form unless you have an invite.

Production Environment URL

• A unique gateway URL (service endpoint) that provides access to the production endpoint of an API. The production endpoint URL becomes available when you request production access, and go live after production access has been approved. Navigation: My Apps > Apps

Profile

• In the context of the Community Manager user interface, the user profile page allows you to edit your user details (firstname, lastname, username, and avatar) and settings (email, password, and notifications settings). Navigation: Profile (to the right of Logout in the top navigation)

Public API

• Public APIs do not need an invitation to get Documentation or Runtime Key access.

QoS (quality of service) policy

• A QoS policy defines the level of service being offered to an app that is accessing an API; for example, the number of transactions per minute that are allowed for the app. In the platform, QoS policies are tied to license terms.

REST

• An acronym for Representational state transfer (REST) or RESTful web services is a way of providing interoperability between computer systems on the Internet.

Restricted API Access

• Restricted access for an app means that the app's access to the API is restricted to a subset of the API, as defined by scope mapping, or to a specified, agreed-upon quota as defined by a QoS policy. Compare: unrestricted API access.

Resource

• In the Community Platform, a Resource is an item, such as an App or API, which has its own Board and set of activities.

Runtime Key Access

• This type of access allows you to actually call the API, something which requires runtime keys, the type of which depend on the nature of the API.

Sandbox Endpoint URL

• A unique gateway URL (service endpoint) that provides access to an APIs sandbox environment. The Sandbox Endpoint URL becomes available after requesting access an API using the Request API Access Wizard. Navigation: Add APIs in My Apps > API Management, or Request API Access in My Apps.

Self-registration required

• In order to gain privileges beyond that of an anonymous user then you must register. The 'self' part comes from the fact that we do not perform any checks validating your stated identity.

Shared Secret Key

• Depending on the nature of the API you are interested in, a Shared Secret is a text code we may assign you on the Digital Gateway portal, and should only be known by yourselves and Digital Gateway. We use it as part of a symmetric cryptography scheme designed to protect your communications with us at a message level. As such it is vital this secret is protected on your side from possible compromise.

Signup Code

• A unique code generated and sent to a specific user in an email when the user signs up for the platform. The code is only valid for the account that requested it, and expires after seven days. This is one of the several types of codes use to manage user signup and login.

Tag

• A tag is essentially a keyword or key phrase that's added to a piece of content, or information associated with a resource, to assist in search results. Several different types of resources can have tags assigned to them; for example, apps, APIs, groups, and tickets. Multiple tags are separated by commas. For example, if an app is a movie general knowledge game, the app owner might assign tags of movie, game, general knowledge; or an API owner can add a category or product line to the metadata for certain APIs so those APIs will come up in search results for that term.

Transport Level Security (TLS)

• Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL), both of which are frequently referred to as "SSL", are cryptographic protocols that provide communications security over a computer network.

Unrestricted API Access

• Unrestricted API access for an app means that the contract is not limited to a specific license. The app has full access to all operations of the API. Compare: restricted API access.

Version

• Each App or API on the platform much have at least one version, and can have multiple versions. When a user creates an app or API on the platform, the first version is created automatically; when using the API it's important to complete both actions. If there is only one app or API version, deleting that version also deletes the app or API.

Visibility

• A setting that controls the types of users who can see a resource, such as an app, API, group, license, or scope, and any associated items such as discussions and tickets. There are three possible values. The first two are applicable to all resources that have visibility settings; the third is applicable only to apps, APIs, and groups.
  Public: anyone can see the resource, even anonymous users.
  Private: the resource is restricted to those who have been specifically invited to have visibility of the resource, usually by joining a private group that has visibility of the resource. Registered Users: the resource is visible to all users who have logged in, but is not visible to anonymous users.