Videntity API
From Videntity Documentaion Wiki
Contents |
Brief Introduction
Videntity API is a REST-ful Web service operating over SSL/HTTPS using 2048KB encryption. Each method has its own URL, and methods are invoked by sending a properly formatted HTTP POST to specific method URL. For a detailed explanation of all URLs and POST parameters, please read API Methods. After the HTTP POST is received, Videntity responds with an XML formatted response. (See API Responses). The response contains, as you might have guessed, a status code of SUCCESSFUL, PENDING, or FAIL. If while processing Videntity finds an error, the status code will return the ERROR. The XML may contain additional information on any error. Videntity can also return other HTTP error messages (e.g. 3xx,4xx, 5xx, HTTP errors), any client created must handle these errors gracefully. For a more detailed description of error handling please read the API Errors section. To use the Videntity API, you must first login and establish a session with our server. For a detailed explanation of Videntity's session handling please go to API Sessions.
Videntity 101 - A Background on Communicating with Videntity through HTTP
Details. Communicating with the Videntity API is achieved through the HTTP method POST. Videntity requires you to communicate over HTTPS. All POST data must be URL encoded and in web form format (i.e. Content-Type: application/x-www-form-urlencoded) or multi-part form format for files (Content-Type: multipart/form-data). You can send a raw HTTP POST directly to the server or write your own HTTP connection client. You may also use the Python API Interface, an open source python client which "wraps" the HTTP communication into Python function calls. If you want to implement your own API interface please read this section. To use the open-source Python client interface please view the Python API Interface.
Sessions
Details. Sessions are used to make a secure connection to the Videntity server. For each session a login is required. Once logged in your session will expire in 30 minutes. To keep your session alive before the 30 minute time frame is up you must ping our server to re-establish the session and reset the session timer. To ensure security and stop session hijacking every session key is generated randomly. When you are finished with your session key we recommend that you logout of the session. This keeps unexpired sessions from being used.
Users
Details. Videntity API users will have to create their own user base (population users as well as entities) for use with Videntity's web services. Users can be created, update, and deleted using the Videntity API.
Methods
Details. All of Videntity's web services are invokable via a HTTPS POST to a specific method URL. These methods take in specific request input parameters that are used to trigger Videntity's web services.
The Transaction Method: /transaction/send
Details.Transactions are executed by the /transaction/send. In most cases this will make up the bulk of activity on the Videntity service. This method provides the main functionality of Videntity's web service. Transactions are codified through a Type of Transaction (TOT). Each transaction type (TOT) is identified by a unique name. Each TOT has separate input requirements and behaviors. Types of transactions supported are verify, message, enroll, site_key, object.
Responses
Details. Once the Videntity server receives the URL form POST request it will then return with the response. The response can either be an error code or a specified URL response. Responses of a POST currently only return formatted XML. You can find the Videntity response's XML schema definition (XSD) at http://videntity.com/response.xsd. If the requested URL method returns with a status PENDING then your transaction has yet to be completed (status = COMPLETE). This means that your transaction is waiting on the receiver to perform a specific action (i.e. voice authenticate, login, or respond to a recorded message). To receive the response when the transaction is finished you must setup your response server URL. If the transaction fails to complete (i.e. the receiver never answers the phone) the transaction status will be returned to your response URL as FAIL.
Errors
Details. Error responses from the server can occur for many reasons including not having an active session, incorrect syntax, missing required information, and others. Not including required data, passed as HTTP POST parameters, is one of the most common. All errors are returned in a formatted XML document.
Uploading Audio Messages
Details. Videntity provides a way of customizing specific audio messages that are played to your users when they receive phone calls. Messages that are played as part of a transaction are known as transaction messages. Transaction messages are uploaded or recorded separately and applied to a transaction before it is sent (similar to an email attachment). Each transaction can have zero, one, or multiple transaction messages. Currently transaction messages are played in the sequential order that they are attached. A more thorough explanation of transaction messages can be found in the API Transactions section
