Authentication and Authorization

How to get access to the FOTO Open API

API Key

In order to interoperate with the API you must provide a valid API key. Since we support multiple protocols there are two distinct ways to provide this key.

RESTful Access

REST XML REST json

Simply provide the API Key in the URL being called as a query string parameter named "Api-Key"

http://devs.patient-inquiry.com/patient2/?Api-Key=a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a

You can optionally supply a pass phrase in the URL being called as a query string parameter named "Api-PassPhrase"

http://devs.patient-inquiry.com/patient2/?Api-Key=a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a&Api-PassPhrase=Secret%20Pass%20Phrase

The FOTO API can also restrict access by ip address. A range of accepted ip addresses can be specified by organization in the API section of the organization settings.

SOAP Access

SOAP 1.1 SOAP 1.2

Since query strings are not supported in SOAP we have added an additional header item "Api-Key" that should contain your API Key.

Sample SOAP 1.1 Header

Connection: Keep-Alive
Content-Length: 138
Content-Type: text/xml; charset=utf-8
Accept-Encoding: gzip, deflate
Host: devs.patient-inquiry.com
Api-Key: a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a
SOAPAction: "http://tempuri.org/Patient2/GetCollection"

Sample SOAP 1.1 Header with Pass Phrase

Connection: Keep-Alive
Content-Length: 138
Content-Type: text/xml; charset=utf-8
Accept-Encoding: gzip, deflate
Host: devs.patient-inquiry.com
Api-Key: a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a            
Api-PassPhrase: Secret%20Pass%20Phrase
SOAPAction: "http://tempuri.org/Patient2/GetCollection"

Sample SOAP 1.2 Header

Content-Length: 7022
Content-Type: application/soap+xml; charset=utf-8
Accept-Encoding: gzip, deflate
Host: devs.patient-inquiry.com 
Api-Key: a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a

Sample SOAP 1.2 Header with Pass Phrase

Content-Length: 7022
Content-Type: application/soap+xml; charset=utf-8
Accept-Encoding: gzip, deflate
Host: devs.patient-inquiry.com 
Api-Key: a8e09fcb-76d4-4912-be4c-6ed3bcd1e93a
Api-PassPhrase: Secret%20Pass%20Phrase

Invalid or missing API Key responses

The invalid or missing API Key response will be appropriate to the protocol used.

RESTful Access

REST XML REST json

A 401 Unauthorized will be returned with the following body

<html>
  <head>
    <title>Request Error - No API Key</title>
    <style type="text/css">
      body
      {
        font-family: Verdana;
        font-size: x-large;
      }
    </style>
</head>
  <body>
    <h1>Request Error</h1>
    <p>A valid API key needs to be included using the Api-Key query string parameter</p>
  </body>
</html>

SOAP Access

SOAP 1.1 SOAP 1.2

Returns an error via SOAP protocol with the one of the following exception texts:
"Unable to proceed without valid API Key"
"Unable to proceed without correct PassPhrase"

What is the scope of the API Key?

As a vendor you will need a unique API Key for each organization you will be submitting data for. An organization is defined in the Patient Inquiry web application as a group having a unique prefix to their login.

How do I get an API Key to use for testing?

Send an email to support@fotoinc.com with general contact information for your company along with the contact information of any additional individuals you would like included on future API emails. For testing purposes a testing organization will be created for each API Key distributed. The servers your API Key will work on will be http://devs.patient-inquiry.com and are meant for development and testing only. NO REAL PATIENT SHOULD BE USED WHEN COMMUNICATING WITH THIS ADDRESS.