The Transaction Method: /transaction/send
From Videntity Wiki - The API Documentation
Transactions provide the main functionality of Videntity's web service. Through transactions, the developer can make his or her applications perform day-to-day tasks. These include verifying a user, sending notifications, sending documents, sending faxes, sending inquiry requests, sending authorization requests, and so on.
Contents |
Generating a Transaction
Generating a transaction is usually a three step process that involves uploading a notification message, uploading an inquiry message, and then sending the transaction. These steps are explained in detail in the next section. The transaction can be used to send out a phone call or send a text message.
Sending a Transaction
The final step of your transaction involves compiling all your transaction information and submitting the Transaction Send method.
Messages
In the previous steps you have already created your notification message (phone and text message) and possibly an inquiry message (phone use only). You where given IDs for each of your messages that you created (notification_message_id and inquiry_message_id).
notification_message_id = 32
and
inquiry_message_id = 55
defined as:
notification_message_id (required): preset message for the main message of the phone call inquiry_message_id (required): preset message for the response message of the phone
These IDs are now going to be used as references to your messages in your transaction. Keeping your messages separate from your transaction allows you to mix and match different notification and inquiry messages. It also allows you to keep from having to upload a message with every transaction, which in turn, speeds up our transaction processing.
Additionally there are 5 other form fields that tell the Videntity server how to process your transaction. These fields are as follows
Transaction Type
The transaction type tells the Videntity server what type of transaction to send out over the phone call. The transaction type has optional field parameters: send, request, and verify. Verify is used to simply send a verification phone call such as a login (just like the API web site login) or a notification message. The request option is probably the most commonly used transaction type. The request transaction will request some piece of information from the receiver of the phone call. So make sure to include an authorization message with your request transaction and your authorization response. The send transaction is used to send data and is currently only used for the Videntity fax system.
transaction_type (required): type of transaction to send to the user.
send: transaction used only to send data (i.e. fax).
Send transactions are used to send a specific piece of information to the receiver of the transaction.
Files can be attached to the transaction and sent to the receiver.
Before the receiver can access the files he must first verify his voice with a phone call.
request: transaction used to request data back from the user (i.e. audio response).
Request transactions are used to request a specific piece of information from the receiver of the transaction.
Request transactions can be used to retrieve authorizations from the receiver of the transaction (i.e. request permission to access a record).
They can also be used to retrieve specific information from the user receiver (i.e. request the receiver to record a message).
verify: transaction used to only verify the user (i.e. login).
Verify transactions will instantly call the user and verify them with the receivers voice and pin over the phone.
Security Level
Security levels are used as a way to tell the Videntity server what type of verification a transaction requires. There are 4 form field options for the security levels. Security level options range from 0 to 3. Typically you would always use the user account default security level of 0. All account defaults are initially set to use voice recognition and pin to verify. If you are only sending a notification to the recipient of the phone call and do not require any form of verification you can specify the security level as 1. Security level 2 ensures that the voice verification is preformed with every call, such as is set with the default. Finally, security level 3 requires that the user performs multi-factor authentication. If you select security level the three the user will have to verify with their voice and pin as well as with another biometrics identifier. This will require the recipient of the phone call to have a fingerprint or iris scanner. Since these devices are not readily available security level 3 is not currently used.
security_level (required): security level for the transaction
0: Use Account Default. This security level option uses account defaults for all users. Account defaults are initially set to use voice recognition and pin.
1: No Verification Required. This security level option uses no verification to deliver the information.
2: Verification Required. This security level option requires verification using voice recognition and a pin to deliver the information.
3: Multifactor Verification Required. This security level option requires multi-factor verification using voice recognition
and a pin and possibly some other biometric identifier (i.e. fingerprint iris) to deliver the information.
Sender ID
The Sender ID is the account number of the sender assigned to him at user creation. The sender ID is used to indicate the sender of the transaction to the Videntity server. The ID allows the server to play the senders name and information. Unlike the receiver ID the sender ID can only include one account number.
sender_id (required): account number of the sender.
The 15 digit sender's account number is given to them at account creation.
You may only submit one sender account number.
Sender Entity
The sender entity field gives you an option to specify a specific sender entity. This entity will replace the current entity if the user type is AGENT.
sender_entity (required): entity of the sender. The sender entity is the field that specifies the entity that is played or displayed to the user.
Receiver ID
The reciever ID is the 15 digit account number of the receiver assigned to him at user creation. The receiver ID is used to indicate who the transaction is to be sent to. The receiver ID has a special built in syntax that gives you the capabilities to send to multiple receivers for one transaction.
To send to multiple receivers delimit each reciever account number with a semicolon
111111111111111:222222222222222:333333333333333
this would send the transaction with the same field parameters to each user with account numbers 111111111111111, 2222222222222222, and 333333333333333
receiver_id (required): account number of the receiver.
The 15 digit receiver's account number given to them at account creation.
You can submit multiple receiver account numbers per transaction.
To submit multiple receiver account numbers input each account number separated by a semicolon.
For example in the form input the receiver data as: recevier1:receiver2:reciever3 (111111111111111:222222222222222:333333333333333)
Phone Execute
The final step before you submit your transaction is to select whether you want your transaction to send out a phone call or a text message. To send out a phone call set the phone execute form field to 1 in your POST. If you do not want to send a phone call set the phone execute form field to 0 or leave it out of the POST completely.
phone_execute (optional): option to send the phone call
1: send the phone call
0 do not send the phone call
blank: if this values is not included phone call will not be sent
SMS Execute
The final step before you submit your transaction is to select whether you want your transaction to send out a phone call or a text message. To send out a text message set the sms execute form field to 1 in your POST. If you do not want to send a text message set the phone execute form field to 0 or leave it out of the POST completely.
sms_execute (optional): option to send the text message
1: send text message
0 do not send the text message
blank: if this values is not included text message will not be sent
Request: Send
To send your transaction send a form POST to the Transaction Send method
https://videntity.com/transactions/send
with the form field parameters listed above.
Response: Send
Once your transaction send request has been submitted the Videntity server will update its database and create a transaction ID (tx_id) for your transaction. This id will be given to you in the response XML as:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="transaction/send">
<status>PENDING</status>
<api_tx_number>182737893</api_tx_number>
<detail>your transaction is pending authorization</detail>
<response_name_value>
<tx_id>23</tx_id>
</response_name_value>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
Use this ID as a reference to your transaction. When you receive a result of a transactions sent by us to your web server this transaction id will be given.
