Responses
From Videntity Wiki - The API Documentation
Responses
This provides a general overview of responses. To see details of each transaction types specific responses and error codes can be found under our API Methods section
The response schema is quite simple and easy to use. Its power is in its brevity.
Once the Videntity server receives the method POST request it will then return with the response. The response can be either an error code or a specified method 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
The Videntity server should respond with something like the following, sent back through the same socket:
Date: Sun, 02 Nov 2008 18:40:32 GMT Server: WSGIServer/0.1 Python/2.4.3 Content-Type: application/xhtml+xml
with the XML code:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="/session/login">
<status>SUCCESS</status>
<api_tx_number>182737893</api_tx_number>
<timestamp>2008-09-30 15:56:42Z</timestamp>
.
.
.
The above fieleds are always returned, while other optional fields
are returned based on the type and status of the transaction.
These are defined in the response.xsd The Response XSD can be found at:
http://videntity.com/response.xsd
</response>
XML tag: response
<response api_method="/session/login">
.
.
.
</response>
The api_method attribute of the response tag is always set to the requested method that was called. In this case it is /session/login which means that this response was generated after a POST to the session/login method.
XML tag: status
<status>STATUS</status>
The status tag is used to return the api transaction status of the requested method as either PENDING, SUCCESS, FAILURE or ERROR. Note that the status is returned in all uppercase.
- PENDING: If the status is PENDING then the transaction is being processed and is probably waiting for user verification and authorization.
- SUCCESS: If the status is SUCCESS your transaction has completed successfully.
- FAILURE:If the status is FAILURE there was some problem finalizing the transaction. Either the phone call wasn't answered by the user or the user failed to verify their voice, etc.
- ERROR: If the status is ERROR then the Videntity server encountered a problem while processing your request. For more on errors see API Errors
XML tag: api_tx_number
<api_tx_number>API_TRANSACTION_NUMBER</api_tx_number>
The api_tx_number tag gives you the API transaction ID of your requested method call. Do not confuse the API transaction number (api_tx_number) with the transaction ID (tx_id). The api_tx_number is used for each requested method call, whereas, the tx_id is used to send a phone call or text message to a specific account holder.
XML tag: timestamp
<timestamp>UTC_TIMESTAMP</timestamp>
The timestamp tag gives your transaction a time and date of origination. All timestamp tag data is in Coordinated Universal Time (UTC time).
Videntity Server's Response Values: response_name_value
Each Videntity Server method call returns specific response values. These values are returned as child nodes of the response_name_value element. As in the example of the Session Login method response:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="/session/login">
<status>SUCCESS</status>
<api_tx_number>182737893</api_tx_number>
<detail>you logged in successfully</detail>
<response_name_value>
<session_key>De325h3Fsdg76rt</session_key>
</response_name_value>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
The session_key is returned as the child node of the response_name_value element.
<response_name_value>
<session_key>De325h3Fsdg76rt</session_key>
</response_name_value>
Each API method call has a specific set of response_name_value pairs. Each API method and response_name_value is listed below.
Response Name Value: Session Login
Format
<response_name_value>
<session_key>SESSION_KEY</session_key>
</response_name_value>
Example
<response_name_value>
<session_key>De325h3Fsdg76rt</session_key>
</response_name_value>
Response Name Value: Session Logout
Format
<response_name_value>
<session_key>SESSION_KEY</session_key>
</response_name_value>
Example
<response_name_value>
<session_key>De325h3Fsdg76rt</session_key>
</response_name_value>
Response Name Value: Session Ping
Format
<response_name_value>
<session_key>SESSION_KEY</session_key>
</response_name_value>
Example
<response_name_value>
<session_key>De325h3Fsdg76rt</session_key>
</response_name_value>
Response Name Value: User Create
Format
<response_name_value>
<first_name>FIRST_NAME</first_name>
<last_name>LAST_NAME</last_name>
<account_number>ACCOUNT_NUMBER</account_number>
</response_name_value>
Example
<response_name_value>
<first_name>John</first_name>
<last_name>Doe</last_name>
<account_number>130422255565487</account_number>
</response_name_value>
Response Name Value: Static Upload Intro Message
Format
<response_name_value>
<file>FILE_NAME</file>
</response_name_value>
Example
<response_name_value>
<file>my_file.wav</file>
</response_name_value>
Response Name Value: Static Upload Enroll Message
Format
<response_name_value>
<file>FILE_NAME</file>
</response_name_value>
Example
<response_name_value>
<file>my_file.wav</file>
</response_name_value>
Response Name Value: Transaction Upload Notification Message
Format
<response_name_value>
<notification_message_id>NOTIFICATION_MESSAGE_ID</notification_message_id>
</response_name_value>
Example
<response_name_value>
<notification_message_id>22</notification_message_id>
</response_name_value>
Response Name Value: Transaction Upload Inquiry Message
Format
<response_name_value>
<inquiry_message_id>RESPONSE_MESSAGE_ID</inquiry_message_id>
</response_name_value>
Example
<response_name_value>
<inquiry_message_id>RESPONSE_MESSAGE_ID</inquiry_message_id>
</response_name_value>
Response Name Value: Transaction Send
Format
<response_name_value>
<tx_id>TRANSACTION_ID</tx_id>
</response_name_value>
Example
<response_name_value>
<tx_id>467</tx_id>
</response_name_value>
