Confident Technologies Web Service

This API is a work in progress. We are adding and modifying resources, requests, representations, and documentation. Our goal is to help developers make their web applications more secure. Please email the API team to let us know how we can make your job easier.

This document describes the Confident Technologies Web Service (CSWS) API.

Table Of Contents

Overview

Authentication

Many API calls are restricted to the owner of a resource. When a call is restricted, use HTTP Basic Authentication (as described in RFC 2617, "HTTP Authentication: Basic and Digest Access Authentication") to authenticate to the API, using the API username and the API password from the site page on login.confidenttechnologies.com.

For these example values:

Customer ID
alice001
Site ID
site001
API username
QHW6aC7DsJKP
API password
g0OeLVS3I6ZE
the curl request for the site resource is:
curl https://api.confidenttechnologies.com/vs/customers/alice001/sites/site001 --user QHW6aC7DsJKP:g0OeLVS3I6ZE    
the PHP equivalent is:
<?php
    $vs_user = "QHW6aC7DsJKP";
    $vs_password = "g0OeLVS3I6ZE";
    $curl = curl_init("https://api.confidenttechnologies.com/vs/customers/alice001/sites/site001");
    curl_setopt($curl,CURLOPT_USERPWD,$vs_user . ":" . $vs_password);
    curl_exec($curl);
?>

Authentication Errors

When there is an authentication problem, the API responds with a "401 Unauthorized" status code and a generic response body. Some possible causes are:

  • No username or password
  • Unknown username
  • Wrong password for username
  • Correct username and password, but the site is not the owner of the resource

Resource Name Requirements

The name of a resource, initially specified in a PUT request for the resource, must contain no more than 40 characters. The allowed characters are alphanumerics (a-z, A-Z, 0-9), hyphen (-), period (.), and underscore (_).

If a resource name does not meet these requirements when requesting to create the resource, the status code of the response will be 400. The body of the response will describe the exact error.

Internationalization

Some resources contain messages meant to be shown directly to end-users. For example, /vs/categories contains category names. Localized messages can be shown in any supported locale. The following locales are supported:

  • English (United States) [en-us]
  • Japanese (Japan) [ja-jp]

By default, localized messages are shown in the English (United States) locale. To request a different locale, use the Accept-Langauge header as documented in RFC 2616.

The user_id Parameter

All premium services require the user_id parameter. This parameter must uniquely identify your end-users and must not exceed 100 characters. For your security and your end-users' privacy, this should not be the actual usernames used on your site. A good alternative is to submit a salted hash of the username or the primary key of the users table of your database.

Statistics

Statistics are a new feature that we expect to change rapidly in the coming weeks. Please send us feedback on what you'd like from this feature.

Statistics requests have these parameters:

  • from: Statistics start at and include this date, given in ISO format (i.e. 2008-04-13T12:34). Note: there are no statistics available before April 1st, 2009.
  • to: Statistics end at but do not include this date, given in ISO format (i.e. 2009-03-13T4:23).
  • granularity: The time granularity to aggregate statistics.

The granularity affects how the dates are interpreted. Not all granularities are allowed for every statistics query.

Granularity Date Interpretation Statistics Returned
year Rounded down to given year Aggregated by year
month Rounded down to given year and month Aggregated by month
day Rounded down to given year, month, and day Aggregated by day
total Rounded down to given year, month, and day One row for the given date range

For example, given these dates:

  • from=2008-12-30T08:13
  • to=2009-01-02T06:59
different values for granularity have different results:
  • granularity=year - Statistics for 2008.
  • granularity=month - Statistics for December 2008.
  • granularity=day - Statistics for December 30th 2008, December 31st 2008, and January 1st 2009.
  • granularity=total - Summed statistics from December 30th 2008 through January 1st 2009.

Resources

/vs/customers

The customers resource is a container for customer resources.

GET

This request returns the customer associated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers

Available response representations:

    Status Code 200 - application/xml (boca:customerURIs)

    A list of customer URIs that can be managed using the authentication credentials.

    Example:

    Content-Type: application/xml
    
    <customerURIs>
      <customerURI>https://api.confidenttechnologies.com/vs/customers/cust001</customerURI>
    </customerURIs>

/vs/customers/{customer}

The customer resource holds data about a customer of the API.

GET

This request returns a representation of the specified customer, if it exists. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001

Available response representations:

    Status Code 200 - application/xml (boca:customer)

    A representation of the customer, containing its name, email address, and phone number. The admin_name is the friendly name of the administrating authority that manages this customer account.

    Example:

    Content-Type: application/xml
    
    <customer>
      <name>bob</name>
      <email>bob@example.com</email>
      <phone>555555555</phone>
      <sitesURI>https://api.confidenttechnologies.com/vs/customers/cust123/sites</sitesURI>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust123/stats</statsURI>
      <admin_name>Confident</admin_name>
    </customer>
    Status Code 410

    The customer has been deleted.

/vs/customers/{customer}/sites

The sites resource is a container for site resources.

GET

This request returns a list of site URIs associated with the specified customer, if the customer exists. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites

Available response representations:

    Status Code 200 - application/xml (boca:siteURIs)

    A list of site URIs associated with the customer.

    Example:

    Content-Type: application/xml
    
    <siteURIs>
      <siteURI site_name="example.com">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001</siteURI>
    </siteURIs>

/vs/customers/{customer}/sites/{site}

The site resource holds data about a customer's site, used to access the authentication services of the API.

GET

This request returns a representation of the specified site, if it exists. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001

Available response representations:

    Status Code 200 - application/xml (boca:site)

    A representation of the site, containing its name and a link to services.

    Example:

    Content-Type: application/xml
    
    <site>
      <site_name>example.com</site_name>
      <api_username>aLongRandomString</api_username>
      <api_password>anotherLongRandomString</api_password>
      <servicesURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services</servicesURI>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust123/sites/example.com001/stats</statsURI>
    </site>

This request will return the banner information for a site. Multiple banners can be bound to the site therefor we request the banner by name.

GET

Acceptable request representations:

    Example:

    GET vs/customers/cust001/sites/example.com001/banner/example_banner_name

Available response representations:

    Status Code 200 - application/xml (boca:site)

    Information about the banner that can help render the banner image in a browser

    Example:

       Content-Type: application/xml
    
    <banner>
      <image>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/banner/example_banner_name/image</image>
      <content_type>png</content_type>
      <width>020</width>
      <height>100</height>
      <alt_text>Banner image alt text</alt_text>
    </banner>

A Banner Image resource for the given site.

GET

Acceptable request representations:

    Example:

    GET vs/customers/cust001/sites/example.com001/banner/example-banner-name/image

Available response representations:

    Status Code 200 - image/png (boca:site)

    A binary image resource of the type given in the /banner/ call.

This request will return the logo information for a site. You can request different logos by logo_name as multiple logos may be bound to the site.

Acceptable request representations:

    Example:

    GET vs/customers/cust001/sites/example.com001/logo/example-logo-nane

Available response representations:

    Status Code 200 - application/xml (boca:site)

    Information about the logo that can help render the logo image in a browser

    Example:

       Content-Type: application/xml
    
    <logo>
      <image>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/logo/example-logo-name/image</image>
      <content_type>png</content_type>
      <width>80</width>
      <height>80</height>
      <alt_text>Logo image alt text</alt_text>
    </logo>

/vs/customers/{customer}/sites/{site}/logo/{logo_name}/image

A Logo Image resource for the given site specified by name.

GET

Acceptable request representations:

    Example:

    GET vs/customers/cust001/sites/example.com001/logo/example-logo-name/image

Available response representations:

    Status Code 200 - image/png (boca:site)

    A binary image resource of the type given in the /logo/ call.

/vs/customers/{customer}/sites/{site}/resetcredentials

This request regenerates the API credentials for a site.

POST

Acceptable request representations:

    Example:

    POST vs/customers/cust001/sites/example.com001/resetcredentials

Available response representations:

    Status Code 200 - application/xml (boca:site)

    The API credentials have been reset.

    Example:

    Content-Type: application/xml
    
    <site>
      <site_name>example.com</site_name>
      <api_username>aLongRandomString</api_username>
      <api_password>anotherLongRandomString</api_password>
      <servicesURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services</servicesURI>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust123/sites/example.com001/stats</statsURI>
    </site>
    Status Code 409

    The site is has been previously deleted.

/vs/customers/{customer}/sites/{site}/services

The services resource is a container for the API authentication services available for a site.

To enable services, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of service URIs associated with the specified site. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of service URIs enabled for the specified site.

    Example:

    Content-Type: application/xml
    
    <services>
      <service enabled="true" id="captcha"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/captcha</service>
      <service enabled="false" id="smsotp"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp</service>
      <service enabled="false" id="voiceotp"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp</service>
      <service enabled="false" id="voicepin"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin</service>
      <service enabled="false" id="voiceptl"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl</service>
      <service enabled="false" id="imageshield"> https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/imageshield</service>
    </services>
    

/vs/customers/{customer}/sites/{site}/stats

The site statistics resource is a container for the statistics available for a site.

GET

This request returns the list of statistics URIs associated with the specified site. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the specified site.

    Example:

    Content-Type: application/xml
    
    <site_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/stats/users</statsURI>
    </site_statistics>
    

/vs/customers/{customer}/sites/{site}/stats/success

The site success statistics resource exposes statistics about service transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/cust001/sites/example.com001/stats/users?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","captcha",200,170,10,15,0,5
    "2009-03","imageshield",150,120,30,5,0,5
    "2009-03","smsotp",100,50,30,15,0,5
    "2009-03","voiceotp",80,35,25,10,5,5
    "2009-03","voicepin",90,44,33,0,0,13
    "2009-03","voiceptl",100,80,15,0,0,5
    

/vs/customers/{customer}/sites/{site}/stats/users

The site users statistics resource exposes statistics about the usage of premium services by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of a site's premium services over the specified time. If a user uses a service multiple times during a time period, it is counted once.

It also returns the Combined count, which counts the unique users across premium services. If a user uses several services multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/cust001/sites/example.com001/stats/users?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","smsotp unique users","voiceotp unique users","voicepin unique users","voiceptl unique users","imageshield unique users","site unique users"
    "2009-03",35,3,0,15,76,82
    

/vs/customers/{customer}/sites/{site}/services/captcha

The Confident CAPTCHA service allows a site to create captcha resources. This free service is enabled by default for new sites.

GET

This request returns the list of Confident CAPTCHA settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/captcha

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings and statistics URI for the Confident CAPTCHA service.

    Example:

    Content-Type: application/xml
    
    <captcha_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/captcha/stats</statsURI>
    </captcha_service>
    
    Status Code 404

    The Confident CAPTCHA service is not enabled for this site.

POST

This request generates a new Confident CAPTCHA. This request must be authenticated with the site API credentials.

The Confident CAPTCHA service enforces minimum strength requirements. If a weak Confident CAPTCHA is requested, the response will be HTTP 400 and indicate the dimensions or captcha_length should be increased.

Strength rating is the inverse of the probability of correctly guessing the solution given a known alphabet. There are height(H) times width(W) letters to choose from, and you must select captcha_length(L) letters. There is a one in H * W chance of choosing the first, one in (H*W - 1) of the second, and so on. Simplified down, the chance of guessing correctly is (H*W - L)! / (H*W)! so the strength rating (SR) formula is:

SR = (H*W)! / (H*W - L)!

A strength rating of 1000 or higher is required.

For example: 4x3 with captcha_length=2 has a strength rating of 132, so it will fail. But captcha_length=3 gives a strength rating of 1320, so it will succeed. Additionally, 3x3 with captcha_length=3 (SR = 504) will fail, but with captcha_length=4 (sr = 3024) will succeed.

Acceptable request representations:

    header parameters
    parameterdescription

    Accept-Language

    Sets the preferred languages for the response. See the Internationalization section for details.

    query parameters
    parameterdefaultrequireddescription

    captcha_length

    3

    No

    Number of categories that must be entered to solve the Confident CAPTCHA.

    order_matters

    True

    No

    Whether the categories should be entered in order.

    Deprecated: Confident CAPTCHA now requires order_matters to be True.

    width

    3

    No

    Width of the Confident CAPTCHA in images. width multiplied by height may not exceed 26.

    height

    4

    No

    Height of the Confident CAPTCHA in images. width multiplied by height may not exceed 26.

    image_code_color

    Red

    No

    Color of the image code. Valid colors are: White, Red, Orange, Yellow, Green, Teal, Blue, Indigo, Violet, Gray

    show_letters

    True

    No

    Include the image code on the images, or make it nearly invisible. Invisible letters are appropriate for clickable CAPTCHA.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/captcha
    Accept-Language: en-us
    Content-Type: application/x-www-form-urlencoded
                  
    captcha_length=3&order_matters=True&width=3&height=4&image_code_color=Red&show_letters=True

Available response representations:

    Status Code 201 - application/xml (boca:captcha)

    The Confident CAPTCHA has been created.

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/captchas/abc123
    
    <captcha uri="https://api.confidenttechnologies.com/vs/captchas/abc123">
      <id>abc123</id>
      <captcha_length>3</captcha_length>
      <order_matters>True</order_matters>
      <width>3</width>
      <height>4</height>
      <image_code_color>Red</image_code_color>
      <category_names>
        <category_name>airplanes</category_name>
        <category_name>cars</category_name>
        <category_name>boats</category_name>
      </category_names>
      <text>Type in the 3 letters you see on pictures of
    &lt;span class="category_name"&gt;airplanes&lt;/span&gt;,
    &lt;span class="category_name"&gt;cars&lt;/span&gt;, and
    &lt;span class="category_name"&gt;boats&lt;/span&gt;, in that
    order.</text>
      <letters>ABCDEFGHI</letters>
      <imageURI has_letters="true">https://api.confidenttechnologies.com/vs/captchas/abc123/image</imageURI>
      <audioURI>https://api.confidenttechnologies.com/vs/captchas/abc123/audio</audioURI>
      <attempted>false</attempted>
      <authenticated>false</authenticated>
    </captcha>
    Status Code 404

    The Confident CAPTCHA service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/captcha/stats

The Confident CAPTCHA statistics resource is a container for the statistics available for Confident CAPTCHA.

GET

This request returns the list of statistics URIs associated with Confident CAPTCHA. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/captcha/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for Confident CAPTCHA statistics.

    Example:

    Content-Type: application/xml
    
    <captcha_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/captcha/stats/success</statsURI>
    </captcha_statistics>
    

/vs/customers/{customer}/sites/{site}/services/captcha/stats/success

The Confident CAPTCHA success statistics resource exposes statistics about Confident CAPTCHA transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of Confident CAPTCHA transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/captcha/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","captcha",200,170,10,15,0,5
    

/vs/captchas/{captcha}

The captcha resource holds a CAPTCHA for a site's user. The resource is publicly available so that a web browser can make requests without authentication.

GET

Returns the specified Confident CAPTCHA. This request does not need to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/captchas/abc123
    Accept-Language: en-us

Available response representations:

    Status Code 200 - application/xml (boca:captcha)

    The Confident CAPTCHA's id, category_names, text, and imageURI are included in the response. category_names is a list of the correct categories for creating custom messages if text is not adequate.

    header parameters
    parameterdescription

    Accept-Language

    Sets the preferred languages for the response. See the Internationalization section for details.

    Example:

    Content-Type: application/xml
    
    <captcha uri="https://api.confidenttechnologies.com/vs/captchas/abc123">
      <id>abc123</id>
      <captcha_length>3</captcha_length>
      <order_matters>True</order_matters>
      <width>3</width>
      <height>4</height>
      <image_code_color>Red</image_code_color>
      <category_names>
        <category_name>airplanes</category_name>
        <category_name>cars</category_name>
        <category_name>boats</category_name>
      </category_names>
      <text>&lt;span class="in_order"&gt;In order&lt;/span&gt;, enter the
    letters for: &lt;span class="category_name"&gt;airplanes&lt;/span&gt;,
    &lt;span class="category_name"&gt;cars&lt;/span&gt;, &lt;span
    class="category_name"&gt;boats&lt;/span&gt;</text>
      <letters>ABCDEFGHI</letters>
      <imageURI has_letters="true">https://api.confidenttechnologies.com/vs/captchas/abc123/image</imageURI>
      <audioURI>https://api.confidenttechnologies.com/vs/captchas/abc123/audio.wav</audioURI>
      <attempted>false</attempted>
      <authenticated>false</authenticated>
    </captcha>
    Status Code 410

    This Confident CAPTCHA has expired.

POST

This request verifies that the code is correct for the specified Confident CAPTCHA. This request does not need to be authenticated.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    code

    Yes

    Code to verify.

    Example:

    POST /vs/captchas/abc123
    Content-Type: application/x-www-form-urlencoded
                  
    code=xyz

Available response representations:

    Status Code 200

    Authentication was successful.

    Status Code 409

    This Confident CAPTCHA has already been attempted, and cannot be attempted again.

    Status Code 410

    This Confident CAPTCHA has expired.

    Status Code 430

    Authentication failed because the code is incorrect, the image has not been fetched, or the submission occurred too soon after fetching the image.

/vs/captchas/{captcha}/image

The Confident CAPTCHA image resource holds a CAPTCHA image for a site's user. The resource is publicly available so that a web browser can make requests without authentication.

GET

Returns the image for the specified Confident CAPTCHA. This request does not have to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/captchas/abc123/image

Available response representations:

    Status Code 200 - image/jpeg
    Status Code 410

    This Confident CAPTCHA has expired.

/vs/captchas/{captcha}/audio.wav

The Confident CAPTCHA audio resource provides an audio version of the CAPTCHA. The resource is publicly available so that a web browser can make requests without authentication.

GET

Returns an audio WAV version of the Confident CAPTCHA. This request does not have to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/captchas/abc123/audio.wav

Available response representations:

    Status Code 200 - audio/wav
    Status Code 410

    This Confident CAPTCHA has expired.

/vs/customers/{customer}/sites/{site}/services/smsotp

The smsotp (SMS One Time Password) resource allows a site to initiate smsotp transactions.

To enable this service, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of smsotp settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/smsotp

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings and statistics URI for the smsotp service.

    Example:

    Content-Type: application/xml
    
    <smsotp_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/stats</statsURI>
    </smsotp_service>
    
    Status Code 404

    The Confident CAPTCHA service is not enabled for this site.

POST

This request generates a new smsotp transaction. This request must be authenticated with the site API credentials.

Acceptable request representations:

    application/x-www-form-urlencoded
    query parameters
    parameterrequireddescription

    phone

    Yes

    Phone number to send an SMS. Must be exactly 10 digits long.

    user_id

    Yes

    Unique identifier for the end-user. Must not exceed 100 characters. For more information, see the user_id section above.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/smsotp
    Content-Type: application/x-www-form-urlencoded
    
    phone=5555551234&user_id=hash_of_some_user_id

Available response representations:

    Status Code 201 - application/xml (boca:smsotp)

    The smsotp has been initiated.

    The smsotp phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The text message has not been sent.
    failure
    The text message could not be sent.
    success
    The text message was sent.

    Authentication statuses are:

    pending
    An OTP has not been submitted.
    failure
    An incorrect OTP was submitted.
    success
    The correct OTP was submitted.

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/transactions/234
    
    <smsotp uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/transactions/234">
      <id>234</id>
      <phone>5555551234</phone>
      <send_status>success</send_status>
      <authentication_status>pending</authentication_status>
    </smsotp>
    Status Code 404

    The smsotp service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/smsotp/stats

The smsotp statistics resource is a container for the statistics available for smsotp.

GET

This request returns the list of statistics URIs associated with smsotp. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/smsotp/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the smsotp.

    Example:

    Content-Type: application/xml
    
    <smsotp_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/stats/users</statsURI>
    </smsotp_statistics>
    

/vs/customers/{customer}/sites/{site}/services/smsotp/stats/success

The smsotp success statistics resource exposes statistics about SMS OTP transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of SMS OTP transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/smsotp/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","smsotp",100,50,30,15,0,5
    

/vs/customers/{customer}/sites/{site}/services/smsotp/stats/users

The smsotp users statistics resource exposes statistics about the usage of smsotp by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the smsotp service over the specified time. If a user uses a service multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, day, hour, and total.

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/smsotp/stats/users?from=2009-03-22&to=2009-04-02&granularity=day

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Day","smsotp unique users"
    "2009-03-22",3
    "2009-03-23",0
    "2009-03-24",4
    "2009-03-25",5
    "2009-03-26",3
    "2009-03-27",6
    "2009-03-28",2
    "2009-03-29",7
    "2009-03-30",4
    "2009-03-31",0
    "2009-04-01",1
    

/vs/customers/{customer}/sites/{site}/services/smsotp/transactions/{transaction}

An smsotp transaction resource contains the status of the transaction and verifies a user-submitted OTP.

GET

Returns information on the specified smsotp transaction. This request must be authenticated with site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/smsotp/transactions/234

Available response representations:

    Status Code 200 - application/xml (boca:smsotp)

    The smsotp phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The text message has not been sent.
    failure
    The text message could not be sent.
    success
    The text message was sent.

    Authentication statuses are:

    pending
    An OTP has not been submitted.
    failure
    An incorrect OTP was submitted.
    success
    The correct OTP was submitted.

    Example:

    Content-Type: application/xml
    
    <smsotp uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/smsotp/transactions/234">
      <id>234</id>
      <phone>5555551234</phone>
      <send_status>success</send_status>
      <authentication_status>success</authentication_status>
    </smsotp>
    Status Code 404

    The smsotp does not exist.

    Status Code 410

    This smsotp has expired.

POST

Attempt to verify a smsotp.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    otp

    Yes

    OTP to verify. May not exceed 16 digits.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/smsotp/transactions/234
    Content-Type: application/x-www-form-urlencoded
                  
    otp=994123

Available response representations:

    Status Code 200

    Authentication was successful.

    Status Code 403

    Authentication was not attempted because the send_status of the smsotp is pending or failure -- the body of the response has a message that indicates which.

    Status Code 409

    Authentication with this smsotp has already been successful, and cannot be attempted again.

    Status Code 410

    This smsotp has expired.

    Status Code 430

    Authentication failed because an incorrect OTP was submitted.

/vs/customers/{customer}/sites/{site}/services/voiceotp

The voiceotp (Voice One Time Password) service allows a site to initiate voiceotp transactions.

To enable this service, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of voiceotp settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceotp

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings and statistics URI for the voiceotp service.

    Example:

    Content-Type: application/xml
    
    <voiceotp_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/stats</statsURI>
    </voiceotp_service>
    
    Status Code 404

    The voiceotp service is not enabled for this site.

POST

This request generates a new voiceotp transaction. This request must be authenticated with the site API credentials.

The voiceotp transaction starts by calling the given phone number. If the user picks up and says hello, they hear the first prompt, asking them to press pound (#). After pressing pound, they hear the one-time password (the send status goes from "pending" to "success"). The use then enters the one-time password into the webpage to authenticate (the authentication status goes from "pending" to "success".

Acceptable request representations:

    application/x-www-form-urlencoded
    query parameters
    parameterdefaultrequireddescription

    phone

    N/A

    Yes

    Phone number to call.

    user_id

    N/A

    Yes

    Unique identifier for the end-user. Must not exceed 100 characters. For more information, see the user_id section above.

    prompt

    Press pound to receive your one time password. Hang up if you did not request this call.

    No

    The initial prompt spoken to the user. This should direct the user to press pound (#) on their phone.

    otp_delivery

    Your one time password is, %(otp_text)s. To repeat your password, press pound.

    No

    The One-Time Password (OTP) message spoken to the user. This must include the text ' %(otp_text)s.', which is replaced by the OTP.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/voiceotp
    Content-Type: application/x-www-form-urlencoded
    
    phone=5555551234&user_id=hash_of_some_user_id

Available response representations:

    Status Code 201 - application/xml (boca:voiceotp)

    The voiceotp has been initiated.

    The voiceotp phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    An OTP has not been accepted, rejected, or submitted.
    accepted
    The answerer accepted the authentication request and received the correct OTP.
    rejected
    The answerer rejected the authentication request.
    failure
    An incorrect OTP was submitted.
    success
    The correct OTP was submitted.

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/transactions/345
    
    <voiceotp uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/transactions/345">
      <id>345</id>
      <phone>5555551234</phone>
      <send_status>pending</send_status>
      <authentication_status>pending</authentication_status>
    </voiceotp>
    Status Code 404

    The voiceotp service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/voiceotp/stats

The voiceotp statistics resource is a container for the statistics available for voiceotp.

GET

This request returns the list of statistics URIs associated with voiceotp. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceotp/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the voiceotp.

    Example:

    Content-Type: application/xml
    
    <voiceotp_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/stats/users</statsURI>
    </voiceotp_statistics>
    

/vs/customers/{customer}/sites/{site}/services/voiceotp/stats/success

The Voice OTP success statistics resource exposes statistics about Voice OTP transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of Voice OTP transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/voiceotp/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","voiceotp",80,35,25,10,5,5
    

/vs/customers/{customer}/sites/{site}/services/voiceotp/stats/users

The voiceotp users statistics resource exposes statistics about the usage of voiceotp by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the voiceotp service over the specified time. If a user uses a service multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, day, hour, and total.

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceotp/stats/users?from=2009-03-22T00:00&to=2009-03-23T00:00&granularity=hour

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Hour","voiceotp unique users"
    "2009-03-22T00:00",0
    "2009-03-22T00:01",0
    "2009-03-22T00:02",0
    "2009-03-22T00:03",0
    "2009-03-22T00:04",0
    "2009-03-22T00:05",0
    "2009-03-22T00:06",1
    "2009-03-22T00:07",5
    "2009-03-22T00:08",1
    "2009-03-22T00:09",0
    "2009-03-22T00:10",0
    "2009-03-22T00:11",1
    "2009-03-22T00:12",3
    "2009-03-22T00:13",1
    "2009-03-22T00:14",1
    "2009-03-22T00:15",1
    "2009-03-22T00:16",1
    "2009-03-22T00:17",4
    "2009-03-22T00:18",12
    "2009-03-22T00:19",3
    "2009-03-22T00:20",1
    "2009-03-22T00:21",2
    "2009-03-22T00:22",0
    "2009-03-22T00:23",8
    

/vs/customers/{customer}/sites/{site}/services/voiceotp/transactions/{transaction}

A voiceotp transaction resource contains the status of the transaction and verifies a user-submitted OTP.

GET

Returns information on the specified voiceotp transaction. This request must be authenticated with site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceotp/transactions/345

Available response representations:

    Status Code 200 - application/xml (boca:voiceotp)

    The voiceotp phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    An OTP has not been accepted, rejected, or submitted.
    accepted
    The answerer accepted the authentication request and received the correct OTP.
    rejected
    The answerer rejected the authentication request.
    failure
    An incorrect OTP was submitted.
    success
    The correct OTP was submitted.

    Example:

    Content-Type: application/xml
    
    <voiceotp uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceotp/transactions/345">
      <id>345</id>
      <phone>5555551234</phone>
      <send_status>success</send_status>
      <authentication_status>success</authentication_status>
    </voiceotp>
    Status Code 404

    The voiceotp does not exist.

    Status Code 410

    This voiceotp has expired.

POST

Attempt to verify a voiceotp

Acceptable request representations:

    query parameters
    parameterrequireddescription

    otp

    Yes

    OTP to verify. May not exceed 16 digits.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/voiceotp/transactions/345
    Content-Type: application/x-www-form-urlencoded
                  
    otp=994123

Available response representations:

    Status Code 200

    Authentication was successful.

    Status Code 403

    Authentication was not attempted because the send_status of the voiceotp is pending or failure -- the body of the response has a message that indicates which.

    Status Code 409

    Authentication with this voiceotp has already been successful, and cannot be attempted again.

    Status Code 410

    This voiceotp has expired.

    Status Code 430

    Authentication failed because an incorrect OTP was submitted.

/vs/customers/{customer}/sites/{site}/services/voicepin

The voicepin (One Key Login - PIN mode) resource allows a site to initiate voicepin transactions.

To enable this service, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of Voice PIN settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voicepin

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings and statistics URI for the Voice PIN service.

    Example:

    Content-Type: application/xml
    
    <voicepin_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/stats</statsURI>
    </voicepin_service>
    
    Status Code 404

    The Voice PIN service is not enabled for this site.

POST

This request generates a new voicepin transaction. This request must be authenticated with the site API credentials.

The voicepin transaction starts by calling the given phone number. If the user picks up and says hello, they hear the first prompt, asking them to enter their Personal Identification Number (PIN). At this point, the send status goes from "pending" to "success". After entering their PIN and pressing pound or waiting a few seconds, they hear the goodbye message and the call ends. At this point, the authentication status goes from "pending" to "success" or "failure".

Acceptable request representations:

    application/x-www-form-urlencoded
    query parameters
    parameterdefaultrequireddescription

    phone

    N/A

    Yes

    Phone number of the customer.

    pin

    N/A

    Yes

    Four- to sixteen-digit PIN the user must submit.

    user_id

    N/A

    Yes

    Unique identifier for the end-user. Must not exceed 100 characters. For more information, see the user_id section above.

    prompt

    Enter your personal identification number. Hang up if you did not request this call.

    No

    The initial prompt spoken to the user. This should direct the user to enter their personal identification number (and optionally press pound when complete), or to hang up to reject the authentication attempt.

    goodbye

    Goodbye.

    No

    The goodbye message spoken to the user.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/voicepin
    Content-Type: application/x-www-form-urlencoded
    
    phone=5555551234&pin=123456&user_id=hash_of_some_user_id

Available response representations:

    Status Code 201 - application/xml (boca:voicepin)

    The voicepin has been initiated.

    The voicepin phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    A PIN has not been submitted and the answerer has not rejected the authentication request.
    rejected
    The answered rejected the authentication request.
    failure
    The answered entered an incorrect PIN.
    success
    The answered entered the correct PIN.

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/transactions/567
    
    <voicepin uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/transactions/567">
      <id>567</id>
      <phone>5555551234</phone>
      <send_status>pending</send_status>
      <authentication_status>pending</authentication_status>
    </voicepin>
    Status Code 404

    The Voice PIN service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/voicepin/stats

The voicepin statistics resource is a container for the statistics available for voicepin.

GET

This request returns the list of statistics URIs associated with voicepin. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voicepin/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the voicepin.

    Example:

    Content-Type: application/xml
    
    <voicepin_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/stats/users</statsURI>
    </voicepin_statistics>
    

/vs/customers/{customer}/sites/{site}/services/voicepin/stats/success

The Voice PIN success statistics resource exposes statistics about Voice PIN transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of Voice PIN transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/voicepin/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","voicepin",90,44,33,0,0,13
    

/vs/customers/{customer}/sites/{site}/services/voicepin/stats/users

The voicepin users statistics resource exposes statistics about the usage of voicepin by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the voicepin service over the specified time. If a user uses a service multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, day, hour, and total.

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voicepin/stats/users?from=2008&to=2009&granularity=year

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Year","voicepin unique users"
    "2008",256
    

/vs/customers/{customer}/sites/{site}/services/voicepin/transactions/{transaction}

A Voice PIN transaction resource contains the status of the transaction.

GET

Returns information on the specified Voice PIN transaction. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voicepin/transactions/567

Available response representations:

    Status Code 200 - application/xml (boca:voicepin)

    The Voice PIN phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    A PIN has not been submitted and the answerer has not rejected the authentication request.
    rejected
    The answered rejected the authentication request.
    failure
    The answered entered an incorrect PIN.
    success
    The answered entered the correct PIN.

    Example:

    Content-Type: application/xml
    
    <voicepin uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voicepin/transactions/567">
      <id>567</id>
      <phone>5555551234</phone>
      <send_status>success</send_status>
      <authentication_status>success</authentication_status>
    </voicepin>
    Status Code 404

    The Voice PIN does not exist.

    Status Code 410

    This Voice PIN has expired.

/vs/customers/{customer}/sites/{site}/services/voiceptl

The voiceptl (One Key Login) resource allows a site to initiate voiceptl transactions.

To enable this service, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of voiceptl settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceptl

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings and statistics URI for the voiceptl service.

    Example:

    Content-Type: application/xml
    
    <voiceptl_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/stats</statsURI>
    </voiceptl_service>
    
    Status Code 404

    The voiceptl service is not enabled for this site.

POST

This request generates a new voiceptl transaction. This request must be authenticated with the site API credentials.

The voiceptl transaction starts by calling the given phone number. If the user picks up and says hello, they hear the first prompt, asking them to enter pound to authenticate. At this point, the send status goes from "pending" to "success". After pressing pound, they hear the goodbye message and the call ends. At this point, the authentication status goes from "pending" to "success".

Acceptable request representations:

    application/x-www-form-urlencoded
    query parameters
    parameterdefaultrequireddescription

    phone

    N/A

    Yes

    Phone number of the customer.

    user_id

    N/A

    Yes

    Unique identifier for the end-user. Must not exceed 100 characters. For more information, see the user_id section above.

    prompt

    Press pound to authenticate. Hang up if you did not request this call.

    No

    The initial prompt spoken to the user. This should direct the user to press pound to authenticate, or to hang up to reject the authentication attempt.

    goodbye

    You are now authenticated. Goodbye.

    No

    The goodbye message spoken to the user.

    Example:

    POST vs/customers/cust001/sites/example.com001/services/voiceptl
    Content-Type: application/x-www-form-urlencoded
    
    phone=5555551234&user_id=hash_of_some_user_id

Available response representations:

    Status Code 201 - application/xml (boca:voiceptl)

    The voiceptl has been initiated.

    The voiceptl phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    Authentication has not failed or succeeded.
    failure
    The answerer rejected the authentication request.
    success
    The answerer accepted the authentication request.

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/transactions/678
    
    <voiceptl uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/transactions/678">
      <id>678</id>
      <phone>5555551234</phone>
      <send_status>pending</send_status>
      <authentication_status>pending</authentication_status>
    </voiceptl>
    Status Code 404

    The voiceptl service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/voiceptl/stats

The voiceptl statistics resource is a container for the statistics available for voiceptl.

GET

This request returns the list of statistics URIs associated with voiceptl. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceptl/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the voiceptl.

    Example:

    Content-Type: application/xml
    
    <voiceptl_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/stats/users</statsURI>
    </voiceptl_statistics>
    

/vs/customers/{customer}/sites/{site}/services/voiceptl/stats/success

The Voice PTL success statistics resource exposes statistics about Voice PTL transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of Voice PTL transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/voiceptl/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","voiceptl",100,80,15,0,0,5
    

/vs/customers/{customer}/sites/{site}/services/voiceptl/stats/users

The voiceptl users statistics resource exposes statistics about the usage of voiceptl by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the voiceptl service over the specified time. If a user uses a service multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, day, hour, and total.

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceptl/stats/users?from=2009-01&to=2009-03&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","voiceptl unique users"
    "2009-01",43
    "2009-02",54
    

/vs/customers/{customer}/sites/{site}/services/voiceptl/transactions/{transaction}

A voiceptl transaction resource contains the status of the transaction.

GET

Returns information on the specified voiceptl transaction. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/voiceptl/transactions/678

Available response representations:

    Status Code 200 - application/xml (boca:voiceptl)

    The voiceptl phone number, send status, and authentication status are included in the response.

    Send statuses are:

    pending
    The phone call has not been made.
    failure
    The phone call could not be made or the phone call was made made but was determined to have not been answered by a human.
    success
    The phone call was made and was determined to have been answered by a human.

    Authentication statuses are:

    pending
    Authentication has not failed or succeeded.
    failure
    The answerer rejected the authentication request.
    success
    The answerer accepted the authentication request.

    Example:

    Content-Type: application/xml
    
    <voiceptl uri="https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/voiceptl/transactions/678">
      <id>678</id>
      <phone>5555551234</phone>
      <send_status>success</send_status>
      <authentication_status>success</authentication_status>
    </voiceptl>
    Status Code 404

    The voiceptl does not exist.

    Status Code 410

    This voiceptl has expired.

/vs/customers/{customer}/sites/{site}/services/imageshield

The ImageShield service allows a site to create ImageShield resources. This is a paid service, disabled by default

GET

This request returns the list of ImageShield settings and stats. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/imageshield

Available response representations:

    Status Code 200 - application/xml (boca:settings)

    A list of settings for the ImageShield service.

    Example:

    Content-Type: application/xml
    
    <imageshield_service>
      <settings/>
      <statsURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/imageshield/stats</statsURI>
    </imageshield_service>
    
    Status Code 404

    The ImageShield service is not enabled for this site, contact Confident Technologies Sales to enable it.

POST

This request generates a new ImageShield. This request must be authenticated with the site API credentials.

Acceptable request representations:

    query parameters
    parameterdefaultrequireddescription

    imageshield_length

    2

    No

    Number of categories that must be entered to solve the ImageShield.

    order_matters

    False

    No

    Whether the categories should be entered in order.

    width

    3

    No

    Width of the ImageShield in images. width multiplied by height may not exceed 26.

    height

    3

    No

    Height of the ImageShield in images. width multiplied by height may not exceed 26.

    image_code_color

    Red

    No

    Color of the image code. Valid colors are: White, Red, Orange, Yellow, Green, Teal, Blue, Indigo, Violet, Gray

    show_letters

    True

    No

    Show the image code on the image, or make it nearly invisible. Invisible image codes are appropriate for clickable ImageShields.

    use_category_images

    False

    No

    Generate an ImageShield with the category representative images. This can be used as an optional practice step in an enrollment process, so that the user can find the familiar images. It should not be used during normal authentication.

    bundle

    N/A

    Yes

    Colon-delimited list of category-ids. It must be height * width elements in length. The first imageshield_length category-ids are used as the auth-categories.

    user_id

    N/A

    Yes

    Unique identifier for the end-user. Must not exceed 100 characters. For more information, see the user_id section above.

    encrypt_config_with_passcode

    N/A

    No

    Encrypts the parameters with the given passcode and user_id, and adds an element encrypted_config to the XML. The encrypted string represents the imageshield_length, order_matters, width, height, image_code_color, show_letters, and bundle, and is padded to hide information about the bundle length. The encrypted string can be used in future calls with encrypted_config and encrypted_passcode.

    encrypted_config

    N/A

    No

    Load the configuration in the encrypted string, generated from a previous ImageShield created with encrypt_config_with_passcode. Must be used with encrypted_passcode. When this is used, the bundle and other parameters are in the encrypted string and are no longer required. However, user_id is still required to decrypt the encrypted string.

    encrypted_passcode

    N/A

    No

    The passcode for the encrypted string, used when generating a previous ImageShield with encrypt_config_with_passcode. Must be used with encrypted_config. When this is used, the bundle and other parameters are in the encrypted string and are no longer required. However, user_id is still required to decrypt the encrypted string.

    Example:

    Standard usage:
    POST vs/customers/cust001/sites/example.com001/services/imageshield
    Content-Type: application/x-www-form-urlencoded
                  
    imageshield_length=3&order_matters=True&width=3&height=4&
    image_code_color=Red&show_letters=true&bundle=food0001:clocks01:
    wldanml1:dogs0001:insects1:skyscrp1:houses01:tysngms1:comptrs1:flowers1:
    people01:stndgls1&user_id=hash_of_some_user_id

    Example:

    Generating encrypted config:
    POST vs/customers/cust001/sites/example.com001/services/imageshield
    Content-Type: application/x-www-form-urlencoded
    
    imageshield_length=3&order_matters=True&width=3&height=4&
    image_code_color=Red&show_letters=true&bundle=food0001:clocks01:
    wldanml1:dogs0001:insects1:skyscrp1:houses01:tysngms1:comptrs1:flowers1:
    people01:stndgls1&user_id=hash_of_some_user_id&
    encrypted_config_with_passcode=p@ssc0de

    Example:

    Using encrypted config:
    POST vs/customers/cust001/sites/example.com001/services/imageshield
    Content-Type: application/x-www-form-urlencoded
    
    user_id=hash_of_some_user_id&encrypted_config=YQNhYWFhYWFhYWFhYWFhY
    Wh9wrGtedtSLBYE6zc3aC0wdgNI7JPYeLJU-xHnjcHjV5XlbA2mruUWZh_o2m2O8kJt
    _L_IllNdn4-G0lyO7D6oBMDNnZQm0ROALPfXaWts8d5GNLF9Ve_-DTuiv7lwiA&
    encrypted_passcode=p@ssc0de

Available response representations:

    Status Code 201 - application/xml (boca:imageshield)

    The ImageShield has been created (Standard usage).

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/imageshields/xyz890
    
    <imageshield uri="https://api.confidenttechnologies.com/vs/imageshields/xyz890">
      <id>xyz890</id>
      <imageshield_length>3</imageshield_length>
      <order_matters>True</order_matters>
      <width>3</width>
      <height>4</height>
      <letters>ABCDEFGHIJKL</letters>
      <image_code_color>Red</image_code_color>
      <imageURI has_letters="true">https://api.confidenttechnologies.com/vs/imageshields/xyz890/image</imageURI>
      <attempted>false</attempted>
      <authenticated>false</authenticated>
    </imageshield>
    Status Code 201 - application/xml (boca:imageshield)

    The ImageShield has been created (Generating encrypted config with encrypted_config_with_passcode).

    Example:

    Content-Type: application/xml
    Location: https://api.confidenttechnologies.com/vs/imageshields/xyz890
    
    <imageshield uri="https://api.confidenttechnologies.com/vs/imageshields/xyz890">
      <id>xyz890</id>
      <imageshield_length>3</imageshield_length>
      <order_matters>True</order_matters>
      <width>3</width>
      <height>4</height>
      <letters>ABCDEFGHIJKL</letters>
      <image_code_color>Red</image_code_color>
      <imageURI has_letters="true">https://api.confidenttechnologies.com/vs/imageshields/xyz890/image</imageURI>
      <attempted>false</attempted>
      <authenticated>false</authenticated>
      <encrypted_config>YQNhYWFhYWFhYWFhYWFhYWh9wrGtedtSLBYE6zc3aC0wd
      gNI7JPYeLJU-xHnjcHjV5XlbA2mruUWZh_o2m2O8kJt_L_IllNdn4-G0lyO7D6oBM
      DNnZQm0ROALPfXaWts8d5GNLF9Ve_-DTuiv7lwiA</encrypted_config>
    </imageshield>
    Status Code 404

    The ImageShield service is not enabled for this site.

/vs/customers/{customer}/sites/{site}/services/imageshield/stats

The imageshield statistics resource is a container for the statistics available for imageshield.

GET

This request returns the list of statistics URIs associated with imageshield. This request must be authenticated with the site API credentials.

Acceptable request representations:

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/imageshield/stats

Available response representations:

    Status Code 200 - application/xml (boca:services)

    A list of statistics URIs available for the imageshield.

    Example:

    Content-Type: application/xml
    
    <imageshield_statistics>
      <statsURI id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/imageshield/stats/success</statsURI>
      <statsURI id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com001/services/imageshield/stats/users</statsURI>
    </imageshield_statistics>
    

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/success

The ImageShield success statistics resource exposes statistics about ImageShield transactions. See the Statistics section for more information about querying statistics.

GET

This request returns counts of ImageShield transactions satisfying states over the specified time. The transaction states are: created, authentication successful, authentication failed, authentication unattempted, delivery refused, and delivery failed.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, and day.

    Example:

    GET /vs/customers/{customer}/sites/{site}/services/imageshield/stats/success?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","Service","Created","Authentication Successful","Authentication Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"
    "2009-03","imageshield",150,120,30,5,0,5
    

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/users

The imageshield users statistics resource exposes statistics about the usage of imageshield by site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the imageshield service over the specified time. If a user uses a service multiple times during a time period, it is counted once.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    from

    Yes

    The starting date in ISO format. Statistics are reported starting at and including this date. Note: there are no statistics available before April 1st, 2009.

    to

    Yes

    The ending date in ISO format. Statistics are reported up to but not including this date. It must be later than the from date.

    granularity

    Yes

    Time period to aggregate statistics over. Permitted values are year, month, day, hour, and total.

    Example:

    GET /vs/customers/cust001/sites/example.com001/services/imageshield/stats/users?from=2009-03&to=2009-04&granularity=month

Available response representations:

    Status Code 200 - text/csv (boca:services)

    A comma-separated values list of the specified statistics.

    Example:

    Content-Type: text/csv; charset=UTF-8
    
    "Month","imageshield unique users"
    "2009-03",154
    

/vs/imageshields/{imageshield_id}

The ImageShield resource holds a ImageShield for a site's user. The resource is publicly available so that a web browser can make requests without authentication.

GET

Returns the specified ImageShield. This request does not need to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/imageshields/xyz890

Available response representations:

    Status Code 200 - application/xml (boca:imageshield)

    The ImageShield's id, and imageURI are included in the response.

    Example:

    Content-Type: application/xml
    
    <imageshield uri="https://api.confidenttechnologies.com/vs/imageshields/xyz890">
      <id>xyz890</id>
      <imageshield_length>3</imageshield_length>
      <order_matters>True</order_matters>
      <width>3</width>
      <height>4</height>
      <letters>ABCDEFGHIJKL</letters>
      <image_code_color>Red</image_code_color>
      <imageURI has_letters="true">https://api.confidenttechnologies.com/vs/imageshields/xyz890/image</imageURI>
      <attempted>false</attempted>
      <authenticated>false</authenticated>
    </imageshield>
    Status Code 410

    This ImageShield has expired.

POST

This request verifies that the code is correct for the specified ImageShield. This request does not need to be authenticated.

Acceptable request representations:

    query parameters
    parameterrequireddescription

    code

    Yes

    Code to verify.

    Example:

    POST /vs/imageshields/xyz890
    Content-Type: application/x-www-form-urlencoded
                  
    code=xyz

Available response representations:

    Status Code 200

    Authentication was successful.

    Status Code 409

    This ImageShield has already been attempted, and cannot be attempted again.

    Status Code 410

    This ImageShield has expired.

    Status Code 430

    Authentication failed because the code is incorrect, the image has not been fetched, or the submission occurred too soon after fetching the image.

/vs/imageshields/{imageshield_id}/image

The ImageShield image resource holds a ImageShield image for a site's user. The resource is publicly available so that a web browser can make requests without authentication.

GET

Returns the image for the specified ImageShield. This request does not have to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/imageshield/xyz890/image

Available response representations:

    Status Code 200 - image/jpeg
    Status Code 410

    This ImageShield has expired.

/vs/categories

The categories resource is used for retrieving a list of ImageShield categories and associated information.

GET

Returns an XML representation of all possible image categories in random order. Each category element contains the id, name, and a list of representative image URIs for use in enrollment.

The optional parameters count and start_with are useful for generating random category bundles for imageshields.

Acceptable request representations:

    header parameters
    parameterdescription

    Accept-Language

    Sets the preferred languages for the response. See the Internationalization section for details.

    query parameters
    parameterdefaultrequireddescription

    count

    0

    No

    Number of categories to return, or 0 to return all available. Must be a non-negative integer.

    start_with

    No

    Colon-delimited list of valid category-ids. These will be returned, in this order, before any randomly picked categories are returned.

    Example:

    GET /vs/categories?count=2&start_with=catdid1
    Accept-Language: en-us

Available response representations:

    Status Code 200 - application/xml

    Example:

    Content-Type: application/xml
    
    <categories>
      <bundle>catid1:catid3</bundle>
      <category uri="https://api.confidenttechnologies.com/vs/categories/catid1">
        <id>catid1</id>
        <name>category 1 name</name>
        <representative_images>
          <imageURI>https://api.confidenttechnologies.com/vs/categories/catid1/representative_images/img123</imageURI>
        </representative_images>
      </category>
      <category uri="https://api.confidenttechnologies.com/vs/categories/catid2">
        <id>catid3</id>
        <name>category 3 name</name>
        <representative_images>
          <imageURI>https://api.confidenttechnologies.com/vs/categories/catid3/representative_images/img678</imageURI>
        </representative_images>
      </category>
    </categories>

/vs/categories/{category_id}

The category resource is used for retrieving information about category corresponding to the given category_id

GET

Returns an XML representation of the specified image category. The representation contains the id, name, and a list of representative image URIs for use in enrollment.

Acceptable request representations:

    header parameters
    parameterdescription

    Accept-Language

    Sets the preferred languages for the response. See the Internationalization section for details.

    Example:

    GET /vs/categories/catid1
    Accept-Language: en-us

Available response representations:

    Status Code 200 - application/xml

    Example:

    Content-Type: application/xml
    
    <category>
      <id>catid1</id>
      <name>category 1 name</name>
      <representative_images>
        <imageURI>https://api.confidenttechnologies.com/vs/categories/catid1/representative_images/img123</imageURI>
      </representative_images>
    </category>

/vs/categories/{category_id}/representative_images

A list of image resources that represent the image category. These images were picked to be suitable for imageshield enrollment.

Note: There is currently one representative image per category, but more may be added in the future.

GET

Get a list of image resources. This request does not have to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/categories/catid1/representative_images

Available response representations:

    Status Code 200 - application/xml

    Example:

    Content-Type: application/xml
    
    <representative_images>
      <imageURI>https://api.confidenttechnologies.com/vs/categories/catid1/representative_images/img123</imageURI>
    </representative_images>

/vs/categories/{category_id}/representative_images/{image_id}

The image resource is used for retrieving a image representing a category.

GET

Returns the image corresponding to the specified image_id. This request does not have to be authenticated.

Acceptable request representations:

    Example:

    GET /vs/categories/catid1/representative_images/img123

Available response representations:

    Status Code 200 - image/jpeg