Method: /transaction/create
From Videntity Wiki - The API Documentation
URL: https://vidapi.com/transaction/send
Definition: Generates and sends the main transaction request. Sends out a phone call or SMS text message.
Request Type: POST
Content-Type: application/x-www-form-urlencoded
Arguments: 8 (required), 2(optional)
- session_key (required): key to your current session. Your session key is given to you in response to your login request.
- transaction_type (required): type of transaction to send to the user.
- 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.
- 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).
- object: transaction used only to send object 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.
- notify: transactions used to play only a notification to the recipient of the phone call. There is no option of any type of response with the notification transaction type.
- enroll: transaction used to enroll a user (i.e. login) in a biometric.
- 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.
- notification_message_id (required): preset message for the notification message of the phone call
- inquiry_message_id (required): preset message for the inquiry message of the phone call
- 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 (required): entity of the sender. The sender entity is the field that specifies the entity that is played or displayed to the user. Only used in text messaging.
- 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 (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 (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
URL Encoded example:
receiver_id=130679124801914&sender_entity=Your+Hospital&sender_id=121229124802739&inquiry_message_id=36& transaction_type=request&security_level=0&phone_execute=1¬ification_message_id=59&session_key=4KEoRPXJqMGy2Lc&sms_execute=0
Response Type: XML
Response Format:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="transaction/send">
<status>STATUS</status>
<api_tx_number>TRANSACTION_NUMBER</api_tx_number>
<detail>DETAILS</detail>
<response_name_value>
<tx_id>TRANSACTION_ID</tx_id>
</response_name_value>
<timestamp>TIMESTAMP</timestamp>
</response>
Response Example:
<?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>
Errors:
| ERROR NUMBER | ERROR NAME | ERROR DETAILS | ERROR EXPLANATION |
|---|---|---|---|
| 2 | SESSION_DOES_NOT_EXIST | Your session does not exist | This error message indicates that your session hasn't been created or has expired. If you receive this error message please call the API login URL to generate a new session. |
| 3 | SESSION_EXPIRED | Your session has expired | This error message indicates that your session hasn't been created or has expired. If you receive this error message please call the API login URL to generate a new session. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field transaction_type is missing | This error message indicates that the transaction_type field was not in your form POST arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field security_level is missing | This error message indicates that the security_level field was not in your form POST arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field notification_message_id is missing | This error message indicates that the notification_message_id field was not included in the form POST arguments. The notification_message_id is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field inquiry_message_id is missing | This error message indicates that the inquiry_message_id field was not included in the form POST arguments. The inquiry_message_id is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field sender_id is missing | This error message indicates that the sender_id field was not included in the form POST arguments. The sender_id is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field receiver_id is missing | This error message indicates that the receiver_id field was not included in the form POST arguments. The receiver_id is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field sms_execute is missing | This error message indicates that the phone_execute field was not included in the form POST arguments. The phone_execute is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field phone_execute is missing | This error message indicates that the sms_execute field was not included in the form POST arguments. The sms_execute is a required field and must be in the arguments. |
| 4 | MISSING_MANDATORY_FIELD | Mandatory field user_type is missing | This error indicates that the user_type field was not included in the form POST arguments. The user_type is a required field and must be in the arguments. |
| 7 | ENUMERATION_ERROR | Field response_type must be one of the following values: keypad or audio | The value supplied in the field response_type is not in the enumerated list. Please make sure your response_type field is one of the following values: keypad or audio (lower case) |
| 11 | SERVER_ERROR | The server could not process your request. | The server could not process your request. Please Try again. |
- Error Detail: not in post
- Error Explanation:
Error Example:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="transaction/send">
<status>ERROR</status>
<api_tx_number>1423534645</api_tx_number>
<error_number>36</error_number>
<error_name>Post Error</error_name>
<error_detail>user_type not in post</error_detail>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
