![\"Successful](\"https://www.v2ondemand.com/assets/docs/images/sucessful.enrollment.sequence.png\")
Established in 2005, V2verify™ provides the core Speaker Verification Engine (SVE) for some of the leading deployments of this technology. V2verify now has operations in North America, and Asia Pacific with plans for further expansion. Long term customers have proven the reliability and robustness of the V2verify SVE.
\nV2verify’s Speaker Verification Engine provides significantly better performance than other available engines. Independent comparisons show performance in terms of Equal Error Rate (ERR) as being an order of magnitude better than the leading players. V2verify packages the SVE with an Application Programming Interface (API). The packaged engine is available to corporate and application developer customers as a superior authentication engine to those already on the market.
\nV2verify continues to build on its more than 5 years of intensive development. EER is considered the best measure of usability of a verification system. It is the measure of where the potential for false accepts and false rejects is balanced. A lower EER value means superior customer satisfaction whilst maintaining the required level of security.
\nV2verify’s product focus is to provide enhanced security and privacy for the web on-line world and emerging 3G technologies (transactional & content management). V2verify aims to provide security, privacy and convenience for the individual and reduce costs for the business and call center operator. V2verify enhances privacy in offshore and virtual contact centers (on-shoring and home agents), but still allow businesses to utilize the cost benefit from operating in low cost jurisdictions. V2verify assists in driving automation of self-service requirements by providing a secure and convenient method of identifying customers and employees. V2verify also continues to work closely with leading research institutions to maintain the Speaker Verification Engine’s leading-edge performance.
\nCOPYRIGHT NOTICE
\nThe V2verify Speaker Verification Engine (SVE) is copyrighted by V2verify™. © 2005-2023
\nThis API specification is the property of V2verify and distributed only to authorized individuals and organizations that have signed a non-disclosure agreement, which will be vigorously enforced. Additionally, certain aspects of the software and its documentation are trade secrets, and all software and documentation are copyrighted.
\nTrade secrets are limited in distribution and possession of this information by unauthorized individuals and organizations may result in severe civil and criminal penalties and will be prosecuted to the maximum extent possible under the law.
\nCopyright law and international treaties protect the software and its documentation referred to in this API specification. Unauthorized reproduction or distribution of any program, its documentation, or any portion of either of them, may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under the law.
\nThe information regarding the products in this API specification are subject to change without notice. All statements, information and recommendations in this guide are believed to be accurate but are presented without warranty of any kind, expressed or implied. Users must take full responsibility for their application of any products. The software license and limited warranty for the accompanying product is set forth in the duly executed Master Software License Agreement (MSLA) and is incorporated herein by this reference. If unable to locate the Master Software License Agreement, contact a V2verify representative for a copy. Notwithstanding any other warranty herein, all document files are provided “AS IS” with all faults.
\nAll other trademarks mentioned in this API specification or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between V2verify and any other company.
\nDISCLAIMER
\nWHILE THE MAJORITY OF THE INFORMATION IN THIS API SPECIFICATION IS PRODUCTION READY, FROM A DEVELOPMENT AND INTEGRATION STANDPOINT, PARTIES INTERESTED IN USING THIS API FOR PRODUCTION ENVIRONMENTS SHOULD FIRST CONTACT V2VERIFY MORE DETAILED INFORMATION.
\nVoice biometrics also known as Voice Authentication or Speaker Verification, verifies the identity of the speaker based on numerous vocal tract traits and style of speech. Voice biometrics is based on the fact that each individual's voice is unique. It is more effective and efficient than other biometric solutions as well as one of the latest non-intrusive technologies commercially available for identity verification. V2verify's Speaker Verification Engine (SVE) processes both Text Independent and Text Dependent utterances to provide flexibility across a range of security requirements. These utterances can be used to not only identify what the speaker is saying but it can also be used to identify the speaker by his/her vocal traits.
\nThe Speaker Verification Engine (SVE) by itself when run does nothing except to wait for incoming audio. It is developed with a set of powerful API calls that allow for seamless integration into existing environments. In a live production environment, there is usually some other application that interacts with the SVE, such as an Interactive Voice Response (IVR) system that forwards incoming requests to the SVE for enrollment and verification.
\nThis API specification covers the use of the Representational State Transfer (REST) Application Program Interface (API) for V2verify's Speaker Verification Engine (SVE); it does not address issues of engine deployment or tuning. Should greater control of the V2verify engine be required, such as changing the locations of stored data or the use of specific encryptions contact your nearest V2verify representative for additional support.
\nThis interface supports enrollment and verification processes. It is up to the application developer to ensure that all other processing logic, security and procedures are developed appropriately. Storage of enrollment vectors is the responsibility of the application. The general structure is depicted in the Platform API Diagram below.
\n![](\"https://www.v2ondemand.com/assets/docs/images/platform.api.diagram.png\")
\n\nIt is important to pay attention to the calls documented in this API. The following points should be observed at all times:
\nAll fields exccept where indicated are case sensitive. For example, sending in VV-Session-id instead of Vv-Session-Id will result in an http status error code.
\nOnly the approved fields for their respective calls are allowed. In the event that a call is made without an approved field, with unexpected fields, or the field(s) case(s) does not match what is expected, an HTTP status error code is returned with an appropriate error message.
\nWhen reviewing the example requests and responses for each call, the Cloud-Developer-Key and Cloud-Application-Key header fields are left blank for documentation purposes. When testing, please use the key pairs given to your company.
\nAny url containing text in {} is meant to indicate that you should substitute the text in {} with either the required text or if allowed text of your own. For example, https://public.v2ondemandapis.com/1/sve/Enrollment/{client_id}/{subpop} is meant to be interpreted as https://public.v2ondemandapis.com/1/sve/Enrollment/1454142/M
\nAny session started through this API has a hard default configured value of 5 minutes on our servers. What this means is that if a session is started for a specific Vv-Session-Id and we do not receive any further calls to the API for that ID within 5 minutes the session will time out, and you will have to initiate the start session call again. With each call to the server with a specific session ID, the timeout window is reset.
\n-
6. This API currently uses a load balancer with stickiness enabled. What this means is when a start session is requested for either enrollments or verifications, the response contains a cookie that must be sent in for all subsequent calls for the session. Additionally, after the finalize call you MUST clear the cookie to prevent later calls from using the same cookie.
-
The SVE REST API uses the JSON Language to send result responses. The API returns only two HTTP response codes: HTTP 200 OK and HTTP 500 INTERNAL SERVER ERROR. The HTTP 200 OK response message varies from API call to API call, while the HTTP 500 INTERNAL SERVER ERROR response message remains the same.
\nThe following is an example of an HTTP 500 INTERNAL SERVER ERROR response message.
\n/* HTTP 500 - Json Error Response */\n{\n /* Error Code (API error, not a catastrophic error) */\n \"error\": 0,\n /* Description of the error code */\n \"description\": \"Description of error\"\n}\n\nIt is worth noting that for some instances, the HTTP 200 OK response message can have an error block as well; this is considered a catastrophic error and the data inside needs to be transmitted to V2verify for inspection, along with the Cloud-Developer-Key, Cloud-Application-Key, Client-Id, and Vv-Session-Id from the message it came from.
\n-
\nThe Cancel Method is used to cancel an Enrollment or Verification session in the event an error occurred in the voice data phases.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Cancel/{reason}
\n{reason} in the url above, is a hyphen (-) separated string of text of length char(64) supplied as the reason for cancelling the session. You should not include the {} when submitting your url.
\nURL Example: https://public.v2ondemandapis.com/1/sve/Cancel/testing-session-connection
\nHTTP Request Headers
\nSuccessful Result
\nThere is no JSON result response for a successful cancel.
\nThe following calls are used to start, process, and terminate an enrollment.
\n\n\nWe recommend having over 50 seconds of enrollment data for text independent profiles. In the image above, there are 20.5 + 30.0 = 50.05 seconds. The seconds returned is the amount of usable speech that the SVE feature extraction process found in the enrollment audio data file. It is important to note here that 50 seconds of audio data does not necessarily equal 50 seconds of enrollment speech. A general rule of thumb is to associate every 3 seconds of audio data with 1 second of enrollment speech data.
\n![](\"https://www.v2ondemand.com/assets/docs/images/rejected.enrollment.sequence.png\")
\n\nIn this case the client should have called the Enrollment Process Data again, even with the same data. In the case of Text-Dependent processing, this would be the same enrollment phase, while additional data could be sent for Text Independent processing.
\nAn enrollment session is initiated using a Cloud-Developer-Key and an Cloud-Application-Key to uniquely identify the developer’s application and it also requires a unique client id and the sub-pop (gender) of the client enrolling. If the gender is unknown preset the subpop to “U”.
\nPOST - https://public.v2ondemandapis.com/1/sve/Enrollment/{client_id}/{subpop}
\nURL Parameters
\nHTTP Request Headers
\nHTTP Response Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - Json Enrollment Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{ ... },\n /* Profile information only present on enrollment start message */\n \"profile.enroll\":{\n /* Index number of the profile */\n \"index\":0,\n /* Kind of Profile: Independent - 1, Liveness - 2 */\n \"kind\":0,\n /* Type of Audio Codec: pcm_little_endian -or- alaw */\n \"codec\":\"\",\n /* Number of seconds of extracted speech required to train an enrollment. */\n \"min_seconds_of_speech\":0.0\n }\n}\n\nHTTP Status Code: 200 (Success)
\nSending voice data to an enrollment can be called multiple times. For Text-Independent Processing, we recommend gathering at least 50 seconds of buffered vectors.
\nPOST - https://public.v2ondemandapis.com/1/sve/Enrollment
\nHTTP Request Headers
\nAdditional Notes
\nUses File Upload Standard RFC 1867.
\n\"Form-based File Upload in HTML\". An HTTP request submitted using the POST method with a content-type of \"multipart/form-data\"
\nThe audio data to be transmitted needs to be encoded by the same audio codec that was received with the profile.enroll JSON object from the start enrollment HTTP Data Stream.
\nIf sending audio with a single channel (mono), the audio data is required to be transmitting as a raw wav stream without any \"RIFF\" headers.
\nIf sending audio with dual channels (stereo), the audio data is required to be transmitted as a raw wav stream including the RIFF headers.
\nMax File Upload Size is currently set by default to 5 megabytes. If you need to send in a file size larger than 5 Megabytes please contact your v2verify support representative.
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Enrollment Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on enrollment process and end messages */\n \"result.enroll\":{\n /* The client_id used in the enrollment start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Current processing call sampling error */\n \"error\":0\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nFinalize an Enrollment, train and save data, destroy the session.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Enrollment
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Enrollment End Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on enrollment process and end messages */\n \"result.enroll\":{\n /* The client_id used in the enrollment start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Number of seconds of speech trained from all voice samples */\n \"seconds_trained\":0.0,\n /* Current processing call sampling error */\n \"error\":0\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nThe following calls are used to start, process, and terminate a verification
\n![](\"https://www.v2ondemand.com/assets/docs/images/successful.verification.process.flow.png\")
\n\nThe general sequence for a verification is to start a session which may then be left open for as long as it is required. This supports being able to do continuous verifications during an interaction. A verification session can be finalized at any time.
\n![](\"https://www.v2ondemand.com/assets/docs/images/failed.verification.example.png\")
\n\nThe image above gives an example of what a failed verification looks like. In this example, the error returned indicates more data is required to produce a reliable result. In this case we would persist and submit additional data, or if trying to verify against a text dependent profile, we would resubmit the same data file.
\nInitiate a verification session using a pre-configured profile and the same unique client_id that was used in the enrollment session. It's important to note here that the values entered for the client_id are not required to be case-sensitive.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification/{client_id}
\nURL Parameters
\nHTTP Request Headers
\nHTTP Response Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Profile information only present on verification start message */\n \"profile.verify\":{\n /* Index number of the profile */\n \"index\":0,\n /* Profile Kind: Independent - 1, Liveness - 2 */\n \"kind\":0,\n /* Profile Type: Single - 2 */\n \"type\":0,\n /* Type of Audio Codec: pcm_little_endian -or- alaw */\n \"codec\":\"\",\n /* Passing Threshold */\n \"pass\":0\n /* Failing Threshold */\n \"fail\":0\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nSending Voice Data can be called multiple times even with the same data.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification
\nHTTP Request Headers
\nAdditional Notes
\nUses File Upload Standard RFC 1867.
\n\"Form-based File Upload in HTML\". An HTTP request submitted using the POST method with a content-type of \"multipart/form-data\"
\nThe audio data to be transmitted needs to be encoded by the same audio codec that was received with the profile.enroll JSON object from the start enrollment HTTP Data Stream.
\nIf sending audio with a single channel (mono), the audio data is required to be transmitting as a raw wav stream without any \"RIFF\" headers.
\nIf sending audio with dual channels (stereo), the audio data is required to be transmitted as a raw wav stream including the RIFF headers.
\nMax File Upload Size is currently set by default to 5 megabytes. If you need to send in a file size larger than 5 Megabytes please contact your v2verify support representative.
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\":{\n /* The client_id used in the verification start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Current processing call sampling error */\n \"error\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Score determined from all samples thus far */\n \"score\":0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\"\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\": {\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\": {\n /* The client_id used in the verification start message */\n \"{client_id}\": {\n /* Index number of the profile */\n \"index\": 0,\n /* Current processing call sampling error */\n \"error\": 0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\": 0.0,\n /* Score determined from all samples thus far */\n \"score\": 0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\": \"P\"\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nSending live voice data, or more commonly referred to as a liveness test, is a proven method of ensuring the person verifying is alive, present at the time the voice is captured, and is not a recording.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification/Liveness/{language_code}/{liveness_text}
\nNOTE: {liveness_text} currently only accepts 4 numbers, and they must each be separated by a single space. For example, if you were to send in the number set 1234, it should be sent as 1 2 3 4. More importantly the text should be URL escaped, which looks like 1 2 3 4. Any other character sequence not formatted as defined above, will return a 404 Not found error.
\nHTTP Request Headers
\nAdditional Notes
\nUses File Upload Standard RFC 1867.
\n\"Form-based File Upload in HTML\". An HTTP request submitted using the POST method with a content-type of \"multipart/form-data\"
\nThe audio data to be transmitted needs to be encoded by the same audio codec that was received with the profile.enroll JSON object from the start enrollment HTTP Data Stream.
\nIf sending audio with a single channel (mono), the audio data is required to be transmitting as a raw wav stream without any \"RIFF\" headers.
\nIf sending audio with dual channels (stereo), the audio data is required to be transmitted as a raw wav stream including the RIFF headers.
\nMax File Upload Size is currently set by default to 5 megabytes. If you need to send in a file size larger than 5 Megabytes please contact your v2verify support representative.
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\": {\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\": {\n /* The client_id used in the verification start message */\n \"{client_id}\": {\n /* Index number of the profile */\n \"index\":0,\n /* Current processing call sampling error */\n \"error\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Score determined from all samples thus far */\n \"score\":0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\"\n }\n },\n /* Present on liveness verification process */\n \"result.liveness\": {\n /* Result of Liveness. Boolean: True or False */\n \"is_alive\": true\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nFinalize the verification session and get the final score result.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Verification
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification End Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\": {\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\": {\n /* The client_id used in the verification start message */\n \"{client_id}\": {\n /* Index number of the profile */\n \"index\": 0,\n /* Current processing call sampling error */\n \"error\": 0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\": 0.0,\n /* Score determined from all samples thus far */\n \"score\": 0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\",\n /*\n * regardless of the status, authorized states the final decision of the engine,\n * if a transaction was overriden by a pin, then authorized will still be true,\n * if liveness failed, authorized will be false\n */\n \"authorized\": true/false\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nThis API spec is currently exposed to any developer who wants to use our cloud solution as a limited freemium service. Multi verify is generally a premium service which we only make available on an as needed basis.
\nOnce multi verify is configured for your application instance, instead of sending in a single id for the client_id url parameter, when performing a verification send in a string of previously/already enrolled comma separated IDs in the client_id url parameter. It's important to note here that the values entered for the client_id are not required to be case-sensitive. Other than sending in a comma separated list of client ids, a Multi-Verify Verification should be handled exactly as you would a Single Verify Verification, i.e., you must start the verification, send in voice data, and then finalize the verification.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification/{client_id_01,client_id_02...}
\nURL Parameters
\nHTTP Request Headers
\nHTTP Response Headers
\nNOTE: The Vv-Session-Id will not be returned if the engine encountered an error in processing the Multi Verify Start Call. Also, if we are unable to find any of the client_ids you sent in, we will return a HTTP 500 error message. See below.
\n/* HTTP 500 - Json Error Response */\n{\n /* Error Code (API error, not a catastrophic error) */\n \"error\": 0,\n /* Description of the error code */\n \"description\": \"Comma separated list of all the ids we could not find in the enrollment database\"\n}\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Profile information only present on verification start message */\n \"profile.verify\":{\n /* Index number of the profile */\n \"index\":0,\n /* Profile Kind: Independent - 1, Liveness - 2 */\n \"kind\":0,\n /* Profile Type: Single - 2 */\n \"type\":0,\n /* Type of Audio Codec: pcm_little_endian -or- alaw */\n \"codec\":\"\",\n /* Passing Threshold */\n \"pass\":0\n /* Failing Threshold */\n \"fail\":0\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\nThe following calls can be used to further integrate with our API.
\nThis endpoint allows Interactive Voice Response (IVR) Systems to specify which agent should receive a notification once a verification is complete.
\nPOST - https://customer-demos.v2ondemandapis.com/1/cloud/notifications/agent
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to V2verify for investigation.\n */\n \"error\":{\n ...\n },\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n-
\nThe engine currently supports the following audio formats:
\nWave PCM signed 16-bit, 8000 Hz, 128 kbps, mono
\nWave PCM signed 16-bit, 8000 Hz, 256 kbps, stereo
\nThe expected audio format is returned in the Enrollment and Verification initialization response JSON messages located in the field codec. Please note, that failure to send in the audio format in any of the specified formats above may result in unintended results, such as for example, an unusually high amount of extracted speech. The extracted speech will always be less than the amount of audio sent to the engine.
\nAs with other biometric solutions, a person’s demeanor and physical environment can have either a positive or a negative outcome on the biometric result. V2verify has recognized this trait and has implemented a failsafe that can be used to both enhance a person’s enrollment voiceprint and to guarantee that the person will always be authorized provided he/she enters the correct pin when prompted. Enhancing a person’s enrollment voiceprint trains the engine to recognize the different physical environments or the different demeanors in which a person may use their voice for authorization.
\nThe pin should always be submitted at the starting phase of the enrollment (see section 4.1). The HTTP POST Method URL remains the same as defined in section 4.1, and the only addition to this API call is the mandatory addition of a header field (see below).
\nHTTP Request Headers
\nThe ability to use the behavioral enhancement pin during verification depends on server-side conditions. Please note, when an \"overrideable\" field is returned in the response message during a process interaction and its value is true, you should prompt users for their training-pin. You should then finalize the verification making sure to include the pin in the required header field as described below in the JSON Object. The “overrideable” field’s visibility in the response message is also dependent on the server-side conditions becoming true.
\n/* HTTP 200 - JSON Verification Process Response */\n{\n \"result.verify\":{\n /* The client_id used in the verification start message */\n \"{client_id}\":{\n ...\n /* Can the verification be overridden? */\n \"overridable\": true/false,\n ...\n }\n }\n}\n\nHTTP Request Headers
\nV2verify recommends that users who are developing their own interfaces should consider the following methods to implement the on-boarding (Enrollment) and User Authentication processes. Please note that different on-boarding methods can be used based on how the process is implemented.
\nWhen implementing a natural language enrollment, the inbound phone channel is monitored, and the live voice used for the process. The benefit to both organization and customer is that the customer/enrollee does not need to utter any specific words or sentence, thus reducing friction, and startup cost. The natural language speech is then sent to v2ondemand which is our voice biometric engine solution (www.v2ondemand.com) system for enrollment.
\nThe engine will return the results of the enrollment, indicating whether it accepted the enrollment, whether it rejected the enrollment and a possible reason why, or whether it requires more speech based on the minimum seconds of speech parameter configured for this specific application instance.
\nV2verify recommends a bare “minimum seconds of speech” enrollment value of 40 seconds. Please note, seconds of speech here indicates trained speech, that is, the seconds of speech the engine was able to extrapolate from the raw audio it received. The number of seconds of raw audio captured is generally more than the number of seconds the engine extrapolates.
\nThe application should be developed to guide the user through the enrollment process step by step. When enrolling with this method, it is always good to use a set of questions during the enrollment process. These questions should be asked up to 3 times each to ensure that there is enough variance in the captured voice. A recommended question set, and sequence of questions are as follows.
\nPlease say your full name
\nPlease say your full address
\nPlease repeat your full name
\nPlease repeat your full address
\nPlease repeat your full name one last time
\nPlease repeat your full address one last time
\nPlease count from zero to nine
\nAdditional Questions if needed:
\nPlease say the days of the week
\nPlease say the months of the year
\nPlease say the four seasons of the year.
\nThe engine will return the results of the enrollment, indicating whether it accepted the enrollment, whether it rejected the enrollment and a possible reason why, or whether it requires more speech based on the minimum seconds of speech parameter configured for this specific application instance.
\nV2verify recommends a bare “minimum seconds of speech” enrollment value of 12 seconds. Please note, seconds of speech here indicates trained speech, that is, the seconds of speech the engine was able to extrapolate from the raw audio it received. The number of seconds of raw audio captured is generally more than the number of seconds the engine extrapolates.
\nWhen implementing a natural language verification, the inbound phone channel is monitored, and the live voice used for the process. The user does not need to utter any specific words or sentence, thus reducing friction and overall continuous cost. The natural language speech is then sent to v2ondemand which is our voice biometric engine cloud solution (www.v2ondemand.com) system for enrollment.
\nThe system will return the results of the verification. It will either return a verified, not verified or ambiguous result or it may ask for more speech. The application should capture and send more speech to www.v2ondemand.com, if requested.
\nThe application should be developed to guide the user through the verification process step by step. The process should resemble the outline below:
\nAsk the user \"Please say your full name\"
\nEither display a set of 4 numbers (pin pattern) and ask the user to repeat them on mobile apps, or say a set of 4 numbers and ask the user to repeat them on an IVR for a liveness test.
\nAdditional Questions if required:
\nAsk the user “Please say your full address”
\nAsk the user “Please say your complete phone number”
\nAsk the user “What day of the week is it today”
\nThe system will return the results of the verification. It will either return a verified, not verified or ambiguous result or it may ask for more speech. The application should capture and send more speech to www.v2ondemand.com, if requested.
\nWe have the taken the liberty of preparing code samples to show how easy it is to consume this REST API. For now the code samples available are for the C# Programming language. As we get more interest in our engine from the developer community we may publish more code samples in different languages.
\nTo view the sample C# code visit our public repo using the link below
\nPOST - https://v2verify@bitbucket.org/vvoicedev/v2_dynamic_samples.git
\nPOST - https://github.com/v2verify/speech_auth_client
\nThe following endpoints are allowed by the API. Please review the section in this API regarding the Process Flow for details on how you should use this API.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"About Us","slug":"about-us"},{"content":"Overview","slug":"overview"},{"content":"Notations","slug":"notations"},{"content":"Response Messages","slug":"response-messages"},{"content":"Cancel Method","slug":"cancel-method"},{"content":"Enrollments","slug":"enrollments"},{"content":"Verifications","slug":"verifications"},{"content":"Service Methods","slug":"service-methods"},{"content":"Audio Formats","slug":"audio-formats"},{"content":"Behavioral Enhancement Pin","slug":"behavioral-enhancement-pin"},{"content":"Best Practices For Implementation","slug":"best-practices-for-implementation"},{"content":"Sample Code","slug":"sample-code"},{"content":"API Calls","slug":"api-calls"}],"owner":"6633182","collectionId":"ecfdc446-a66b-4e46-b4ad-1ffb64afba68","publishedId":"SVfH1sub","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-08-19T19:29:07.000Z"},"item":[{"name":"Cancel Method","item":[{"name":"Cancel Request","id":"4051a2e9-6f0c-4841-8aea-356c0e20665b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"","description":"The Cancel Method is used to cancel an Enrollment or Verification session in the event an error occurred in the voice data phases.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Cancel/{reason}
\n{reason} in the url above, is a hyphen (-) separated string of text of length char(64) supplied as the reason for cancelling the session. You should not include the {} when submitting your url.
\nURL Example: https://public.v2ondemandapis.com/1/sve/Cancel/testing-session-connection
\nHTTP Request Headers
\nSuccessful Result
\nThere is no JSON result response for a successful cancel.
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"4051a2e9-6f0c-4841-8aea-356c0e20665b"}],"id":"4ae2792f-a97e-462e-9d38-4d4dc9dfe7c4","event":[{"listen":"prerequest","script":{"id":"655972a4-0886-4896-a82f-7280114c3cf1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"48f8c7e4-d56c-438d-8e4f-948ecc47de8a","type":"text/javascript","exec":[""]}}],"_postman_id":"4ae2792f-a97e-462e-9d38-4d4dc9dfe7c4","description":""},{"name":"Enrollment Methods","item":[{"name":"Starting An Enrollment","id":"44342273-1c28-4adb-9568-0c22bd8cb542","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"An enrollment session is initiated using a Developer-Key and an Application-Key to uniquely identify the developer’s application and it also requires a unique client id and the sub-pop (gender) of the client enrolling. If the gender is unknown preset the subpop to “U”.
\nPOST - https://public.v2ondemandapis.com/1/sve/Enrollment/{client_id}/{subpop}
\nURL Parameters
\nHTTP Request Headers
\nHTTP Response Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - Json Enrollment Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{ ... },\n\n /* Profile information only present on enrollment start message */\n \"profile.enroll\":{\n\n /* Index number of the profile */\n \"index\":0,\n\n /* Kind of Profile: Independent - 1, Liveness - 2 */\n \"kind\":0,\n\n /* Type of Audio Codec: pcm_little_endian -or- alaw */\n \"codec\":\"\",\n\n /* Number of seconds of extracted speech required to train an enrollment. */\n \"min_seconds_of_speech\":0.0\n }\n}\nHTTP Status Code: 200 (Success)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"44342273-1c28-4adb-9568-0c22bd8cb542"},{"name":"Sending Voice Data to An Enrollment","id":"8e3690c0-fedb-4e86-9134-a1258fb2fd31","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"Sending voice data to an enrollment can be called multiple times. For Text-Independent Processing, we recommend gathering at least 50 seconds of buffered vectors.
\nPOST - https://public.v2ondemandapis.com/1/sve/Enrollment
\nHTTP Request Headers
\nAdditional Notes
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition with Multiple Voice Snippets
\n -- The sample below indicates you intend on sending 3 mono wav files to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_1.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_1.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_2.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_2.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_3.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_3.raw ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Enrollment Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on enrollment process and end messages */\n \"result.enroll\":{\n /* The client_id used in the enrollment start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Current processing call sampling error */\n \"error\":0\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"8e3690c0-fedb-4e86-9134-a1258fb2fd31"},{"name":"Finalize An Enrollment","id":"01849d79-676d-44c5-984f-13f7d3cd8685","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"","description":"Finalize an Enrollment, train and save data, destroy the session.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Enrollment
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Enrollment End Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n\n /* Present on enrollment process and end messages */\n \"result.enroll\":{\n\n /* The client_id used in the enrollment start message */\n \"{client_id}\":{\n\n /* Index number of the profile */\n \"index\":0,\n\n /* Number of seconds of speech trained from all voice samples */\n \"seconds_trained\":0.0,\n\n /* Current processing call sampling error */\n \"error\":0\n }\n }\n}\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"01849d79-676d-44c5-984f-13f7d3cd8685"}],"id":"3d1f7963-46c3-4e76-89d1-f9982db1f507","description":"The following calls are used to start, process, and terminate an enrollment.
\n
We recommend having over 50 seconds of enrollment data for text independent profiles. In the image above, there are 20.5 + 30.0 = 50.05 seconds. The seconds returned is the amount of usable speech that the SVE feature extraction process found in the enrollment audio data file. It is important to note here that 50 seconds of audio data does not necessarily equal 50 seconds of enrollment speech. A general rule of thumb is to associate every 3 seconds of audio data with 1 second of enrollment speech data.
\n
In this case the client should have called the Enrollment Process Data again, even with the same data. In the case of Text-Dependent processing, this would be the same enrollment phase, while additional data could be sent for Text Independent processing.
\n ","event":[{"listen":"prerequest","script":{"id":"d231a354-c244-4546-a18d-f74438ff8a7d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"73ab8ef8-f055-46a3-8514-35ff8fe87021","type":"text/javascript","exec":[""]}}],"_postman_id":"3d1f7963-46c3-4e76-89d1-f9982db1f507"},{"name":"Verification Methods","item":[{"name":"Starting A Verification","id":"be3ceec7-569a-448e-b81b-810a3f4329fe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"Initiate a verification session using a pre-configured profile and the same unique client_id that was used in the enrollment session. It's important to note here that the values entered for the client_id are not required to be case-sensitive.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification/{client_id}
\nURL Parameters
\nHTTP Request Headers
\nHTTP Response Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n\n /* Profile information only present on verification start message */\n \"profile.verify\":{\n\n /* Index number of the profile */\n \"index\":0,\n\n /* Profile Kind: Independent - 1, Liveness - 2 */\n \"kind\":0,\n\n /* Profile Type: Single - 2 */\n \"type\":0,\n\n /* Type of Audio Codec: pcm_little_endian -or- alaw */\n \"codec\":\"\",\n\n /* Passing Threshold */\n \"pass\":0\n\n /* Failing Threshold */\n \"fail\":0\n }\n}\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"be3ceec7-569a-448e-b81b-810a3f4329fe"},{"name":"Sending Voice Data to a Verification","id":"1442e5a1-2698-41d5-b4d6-a686e3c0f96d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"Sending a Voice Snippet can be called multiple times even with the same data.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification
\nHTTP Request Headers
\nAdditional Notes
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition with Multiple Voice Snippets
\n -- The sample below indicates you intend on sending 3 mono wav files to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_1.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_1.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_2.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_2.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_3.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_3.raw ...\n --current-date-time-in-hex--\n\nSample Content Disposition with a Voice Snippet and a Speech Context
\n -- The sample below indicates you intend on sending 3 mono wav files to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n -- name=\"speech\" segment is applied to the previous most audio segment in the mulipart array\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"speech\"; filename=\"youraudiospeechcontext.json\"\n Content-Type: application/json\n {\n \"name\": \"challenge\",\n \"grammar\": \"[#][#][#][#]\",\n \"languageCode\": \"en-US\",\n \"phrases\": [ \"1 2 3 4\" ]\n }\n --current-date-time-in-hex--\n\n {\n -- A name\n \"name\": \"challenge\",\n -- Grammar is a hint to our engine on what the 'phrases' field contains\n -- [#][#][#][#] indicates a sequence of 4 numbers\n \"grammar\": \"[#][#][#][#]\",\n -- Language Code for the speech recognizer\n \"languageCode\": \"en-US\",\n -- Phrase to validate against\n \"phrases\": [ \"1 2 3 4\" ]\n }\n\nSample Content Disposition with multiple Voice Snippets and Speech Contexts
\n -- The sample below indicates you intend on sending 3 mono wav files to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n -- name=\"speech\" segment is applied to the previous most audio segment in the mulipart array\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_1.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_1.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"speech\"; filename=\"youraudiospeechcontext_1.json\"\n Content-Type: application/json\n {\n \"name\": \"challenge_1\",\n \"grammar\": \"[#][#][#][#]\",\n \"languageCode\": \"en-US\",\n \"phrases\": [ \"1 2 3 4\" ]\n }\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_2.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_2.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"speech\"; filename=\"youraudiospeechcontext_2.json\"\n Content-Type: application/json\n {\n \"name\": \"challenge_2\",\n \"grammar\": \"[#][#][#][#]\",\n \"languageCode\": \"en-US\",\n \"phrases\": [ \"5 6 7 8\" ]\n }\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiosnippet_3.raw\"\n Content-Type: audio/wav\n ... contents of youraudiosnippet_3.raw ...\n --current-date-time-in-hex\n content-disposition: form-data; name=\"speech\"; filename=\"youraudiospeechcontext_3.json\"\n Content-Type: application/json\n {\n \"name\": \"challenge_2\",\n \"grammar\": \"[#][#][#][#]\",\n \"languageCode\": \"en-US\",\n \"phrases\": [ \"9 5 3 4\" ]\n }\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\":{\n /* The client_id used in the verification start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Current processing call sampling error */\n \"error\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Score determined from all samples thus far */\n \"score\":0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\"\n }\n }\n}\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\":{\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\":{\n /* The client_id used in the verification start message */\n \"{client_id}\":{\n /* Index number of the profile */\n \"index\":0,\n /* Current processing call sampling error */\n \"error\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Score determined from all samples thus far */\n \"score\":0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\"\n }\n },\n /* Present on liveness verification process */\n \"result.liveness\": {\n /* Result of Liveness. Boolean: True or False */\n \"is_alive\": true\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"1442e5a1-2698-41d5-b4d6-a686e3c0f96d"},{"name":"Sending Live Voice Data (deprecated)","id":"73045ab1-e914-49f4-afed-0eb64dbb4b9a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"NOTE: This call is deprecated, please refer to the sections above 'Sample Content Disposition with a Voice Snippet and a Speech Context' and 'Sample Content Disposition with multiple Voice Snippets and Speech Contexts' on how to send liveness data.
\nSending live voice data, or more commonly referred to as a liveness test, is a proven method of ensuring the person verifying is alive, present at the time the voice is captured, and is not a recording.
\nPOST - https://public.v2ondemandapis.com/1/sve/Verification/Liveness/{language_code}/{liveness_text}
\nNOTE: {liveness_text} currently only accepts 4 numbers, and they must each be separated by a single space. For example, if you were to send in the number set 1234, it should be sent as 1 2 3 4. More importantly the text should be URL escaped, which looks like 1 2 3 4. Any other character sequence not formatted as defined above, will return a 404 Not found error.
\nHTTP Request Headers
\nAdditional Notes
\nContent Disposition Options
\nSample Content Disposition
\n -- The sample below indicates you intend on sending a mono wav file to the engine\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"data\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Right Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the right channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"right\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nSample Content Disposition for Left Channel
\n -- The sample below indicates you intend on sending a stereo wav file to the engine for processing the left channel only\n -- For reference let boundary = current-date-time-in-hex or some other value\n -- Content-Type is part of HTTP Headers\n -- Content-Length must also be specified in the HTTP Headers\n Your client request should look like:\n Content-Type: multipart/form-data, boundary=current-date-time-in-hex\n --current-date-time-in-hex\n content-disposition: form-data; name=\"left\"; filename=\"youraudiofilename.wav\"\n Content-Type: audio/wav\n ... contents of youraudiofilename.wav ...\n --current-date-time-in-hex--\n\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Process Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\": {\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\": {\n /* The client_id used in the verification start message */\n \"{client_id}\": {\n /* Index number of the profile */\n \"index\":0,\n /* Current processing call sampling error */\n \"error\":0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\":0.0,\n /* Score determined from all samples thus far */\n \"score\":0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\"\n }\n },\n /* Present on liveness verification process */\n \"result.liveness\": {\n /* Result of Liveness. Boolean: True or False */\n \"is_alive\": true\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"73045ab1-e914-49f4-afed-0eb64dbb4b9a"},{"name":"Finalize A Verification","id":"712f5545-0d78-4de7-9960-8bc2f4c8a703","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"","description":"Finalize the verification session and get the final score result.
\nDELETE - https://public.v2ondemandapis.com/1/sve/Verification
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification End Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to ValidVoice for investigation.\n */\n \"error\": {\n ...\n },\n /* Present on verification process and end messages */\n \"result.verify\": {\n /* The client_id used in the verification start message */\n \"{client_id}\": {\n /* Index number of the profile */\n \"index\": 0,\n /* Current processing call sampling error */\n \"error\": 0,\n /* Number of seconds of speech extracted from all voice samples thus far */\n \"seconds_extracted\": 0.0,\n /* Score determined from all samples thus far */\n \"score\": 0.0,\n /* Status of score. (P)assing, (A)mbiguous, (F)ailing, Need (M)ore Speech, (N)ot Scored */\n \"status\":\"P\",\n /*\n * regardless of the status, authorized states the final decision of the engine,\n * if a transaction was overriden by a pin, then authorized will still be true,\n * if liveness failed, authorized will be false\n */\n \"authorized\": true/false\n }\n }\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"712f5545-0d78-4de7-9960-8bc2f4c8a703"}],"id":"a0945f28-7f3d-4420-92cf-c066545c1c0a","description":"The following calls are used to start, process, and terminate a verification
\n
The general sequence for a verification is to start a session which may then be left open for as long as it is required. This supports being able to do continuous verifications during an interaction. A verification session can be finalized at any time.
\n
The image above gives an example of what a failed verification looks like. In this example, the error returned indicates more data is required to produce a reliable result. In this case we would persist and submit additional data, or if trying to verify against a text dependent profile, we would resubmit the same data file.
\nPlease note, this API currently uses a load balancer with stickiness enabled. What this means is when a start session is requested for a verification, the response contains a cookie that must be sent in for all subsequent calls for the session. Additionally, after the finalize call you MUST clear the cookie to prevent later calls from using the same cookie.
\n","event":[{"listen":"prerequest","script":{"id":"e9092d6b-0fc3-44ea-88e9-7ec5565e6b1f","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"91333ae4-687b-47a9-98ea-b7a66c866a1f","type":"text/javascript","exec":[""]}}],"_postman_id":"a0945f28-7f3d-4420-92cf-c066545c1c0a"},{"name":"Service Methods","item":[{"name":"Call Based Routing","id":"e8573782-9db2-47e6-ae82-bc1557a26bd7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"","description":"This endpoint allows Interactive Voice Response (IVR) Systems to specify which agent should receive a notification once a verification is complete.
\nPOST - https://customer-demos.v2ondemandapis.com/1/cloud/notifications/agent
\nHTTP Request Headers
\nHTTP Status Code: 200 (Success)
\n/* HTTP 200 - JSON Verification Start Response */\n{\n /*\n * Only present if a catastrophic error occurs inside the API.\n * Data inside this block should be sent to V2verify for investigation.\n */\n \"error\":{\n ...\n },\n}\n\nHTTP Status Code: 500 (Internal Server Error)
\n","urlObject":{"query":[],"variable":[]}},"response":[],"_postman_id":"e8573782-9db2-47e6-ae82-bc1557a26bd7"}],"id":"c4bd5092-5ab9-48d3-9f63-5835676db839","description":"The following calls can be used to further integrate with our API.
\n","event":[{"listen":"prerequest","script":{"id":"e9092d6b-0fc3-44ea-88e9-7ec5565e6b1f","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"91333ae4-687b-47a9-98ea-b7a66c866a1f","type":"text/javascript","exec":[""]}}],"_postman_id":"c4bd5092-5ab9-48d3-9f63-5835676db839"}],"event":[{"listen":"prerequest","script":{"id":"85cf87c3-6d7b-4ffe-9801-ce5a8e877a72","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3f085c22-5eef-447f-8929-53261c4093ff","type":"text/javascript","exec":[""]}}]}