Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Ruby wrapper classes around the miiCard API

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

api-wrappers-ruby

Ruby wrapper classes around the miiCard API.

This repository houses the source for the latest version of the miiCard Consumers library available on RubyGems.org.

What is miiCard

miiCard lets anybody prove their identity to the same level of traceability as using a passport, driver's licence or photo ID. We then allow external web applications to ask miiCard users to share a portion of their identity information with the application through a web-accessible API.

What is the library for?

miiCard's API is an OAuth-protected web service supporting SOAP, POX and JSON - documentation is available. The library wraps the JSON endpoint of the API, making it easier to make the required OAuth signed requests.

You can obtain a consumer key and secret from miiCard by contacting us on our support form, including the details listed on the developer site.

Pull the library into your own application by downloading the latest released version from RubyGems.org.

Usage

You'll need to implement your own OAuth exchange with miiCard.com's OAuth endpoint to obtain an access token and secret for a user.

Accessing the Claims API

Once you've got your consumer key and secret, access token and access token secret you can instantiate an API wrapper:

api = MiiCardOAuthClaimsService.new("consumer_key", "consumer_secret", "access_token", "access_token_secret")

Then make calls against it simply:

user_profile_response = api.get_claims().data

user_first_name = user_profile_response.data.first_name

Financial API

Accessing the Financial API is the same, but with a different wrapper type - MiiCardOAuthFinancialService:

api = MiiCardOAuthFinancialService.new("consumer_key", "consumer_secret", "access_token", "access_token_secret")

Directory API

Unlike the Claims and Financial APIs, the Directory API is a public lookup service that requires no special OAuth steps to access:

api = MiiCardDirectoryService.new()

Test harness

There is a Rails test harness that provides a little sample code as well as letting you exercise the APIs and check that OAuth tokens that you've obtained are valid, also available on GitHub along with instructions on how to run and use it.

Mapping from API data types

The following list is provided as a convenient cheat-sheet, and maps the API's methods and data types to their equivalents in the Ruby wrapper library classes.

Methods

Claims API (documentation link)

API method Ruby equivalent (given `api` instance of `MiiCardOAuthClaimsService`)
AssuranceImage api.assurance_image(type)
GetCardImage api.get_card_image(snapshot_id, show_email_address, show_phone_number, format)
GetClaims api.get_claims()
GetIdentitySnapshot api.get_identity_snapshot(snapshot_id)
GetIdentitySnapshotPdf api.get_identity_snapshot_pdf(snapshot_id)
GetIdentitySnapshotDetails api.get_identity_snapshot_details()
Or, for a specific snapshot:
api.get_identity_snapshot_details(snapshot_id)
IsSocialAccountAssured api.is_social_account_assured(social_account_id, social_account_type)
IsUserAssured api.is_user_assured()

Financial API (documentation link)

API method Ruby equivalent (given `api` instance of `MiiCardOAuthFinancialService`)
IsRefreshInProgress api.is_refresh_in_progress()
IsRefreshInProgressCreditCards api.is_refresh_in_progress_credit_cards()
RefreshFinancialData api.refresh_financial_data()
RefreshFinancialDataCreditCards api.refresh_financial_data_credit_cards()
GetFinancialTransactions api.get_financial_transactions()
GetFinancialTransactionsCreditCards api.get_financial_transactions_credit_cards()

Directory API (documentation link)

Search criterion Ruby equivalent (given `api` instance of MiiCardDirectoryService)
Any api.find_by(criterion, criterion_value, hashed = false)
Username api.find_by_username(username, hashed = false)
Email api.find_by_email(email, hashed = false)
Phone api.find_by_phone(phone, hashed = false)
Twitter api.find_by_twitter(twitter_handle_or_url, hashed = false)
Facebook api.find_by_facebook(facebook_url, hashed = false)
LinkedIn api.find_by_linkedin(linkedin_www_url, hashed = false)
Google api.find_by_google(google_handle_or_url, hashed = false)
LiveID/Microsoft ID api.find_by_microsoft_id(microsoft_id_url, hashed = false)
eBay api.find_by_ebay(ebay_handle_or_my_ebay_url, hashed = false)
Veritas Vitae api.find_by_veritas_vitae(vv_number_or_profile_url, hashed = false)

If you need to hash an identifier you can use the MiiCardDirectoryService.hash_identifier(identifier) static function. This won't normalise the identifier, but will at least lowercase it before hashing - see the Directory API documentation for details on normalisation steps.

Data types - Claims API

AuthenticationDetails (documentation link)

API data-type property Ruby equivalent (given `details` instance of `AuthenticationDetails`)
AuthenticationTimeUtc details.authentication_time_utc
SecondFactorType details.second_factor_type
SecondFactorProvider details.second_factor_provider
Locations details.locations

AuthenticationTokenType enumeration type (documentation link)

API data-type property Ruby equivalent
None AuthenticationTokenType.NONE
Soft AuthenticationTokenType.SOFT
Hard AuthenticationTokenType.HARD

EmailAddress (documentation link)

API data-type property Ruby equivalent (given `email` instance of `EmailAddress`)
DisplayName email.display_name
Address email.address
IsPrimary email.is_primary
Verified email.verified

GeographicLocation (documentation link)

API data-type property Ruby equivalent (given `location` instance of `GeographicLocation`)
LocationProvider location.location_provider
Latitude location.latitude
Longitude location.longitude
LatLongAccuracyMetres location.lat_long_accuracy_metres
ApproximateAddress location.approximate_address

Identity (documentation link)

API data-type property Ruby equivalent (given `identity` instance of `Identity`)
Source identity.source
UserId identity.user_id
ProfileUrl identity.profile_url
Verified identity.verified

IdentitySnapshot (documentation link)

API data-type property Ruby equivalent (given `snapshot` instance of `IdentitySnapshot`)
Details snapshot.details
Snapshot snapshot.snapshot

IdentitySnapshotDetails (documentation link)

API data-type property Ruby equivalent (given `snapshot_details` instance of `IdentitySnapshotDetails`)
SnapshotId snapshot_details.snapshot_id
Username snapshot_details.username
TimestampUtc snapshot_details.timestamp_utc
WasTestUser snapshot_details.was_test_user

MiiApiCallStatus enumeration type (documentation link)

API data-type property Ruby equivalent
Success MiiApiCallStatus.SUCCESS
Failure MiiApiCallStatus.FAILURE

MiiApiErrorCode enumeration type (documentation link)

API data-type property Ruby equivalent
Success MiiApiCallStatus.SUCCESS
UnknownSearchCriterion MiiApiCallStatus.UNKNOWN_SEARCH_CRITERION
NoMatches MiiApiCallStatus.NO_MATCHES
AccessRevoked MiiApiCallStatus.ACCESS_REVOKED
UserSubscriptionLapsed MiiApiCallStatus.USER_SUBSCRIPTION_LAPSED
TransactionalSupportDisabled MiiApiCallStatus.TRANSATIONAL_SUPPORT_DISABLED
FinancialDataSupportDisabled MiiApiCallStatus.FINANCIAL_DATA_SUPPORT_DISABLED
DevelopmentTransactionalSupportOnly MiiApiCallStatus.DEVELOPMENT_TRANSACTIONAL_SUPPORT_ONLY
InvalidSnapshotId MiiApiCallStatus.INVALID_SNAPSHOT_ID
Blacklisted MiiApiCallStatus.BLACKLISTED
ProductDisabled MiiApiCallStatus.PRODUCT_DISABLED
ProductDeleted MiiApiCallStatus.PRODUCT_DELETED
Exception MiiApiCallStatus.EXCEPTION

MiiApiResponse (documentation link)

API data-type property Ruby equivalent (given `response` instance of `MiiApiResponse`)
Status response.status
ErrorCode response.error_code
ErrorMessage response.error_message
Data response.data
IsTestUser response.is_test_user

MiiUserProfile (documentation link)

API data-type property Ruby equivalent (given `profile` instance of `MiiUserProfile`)
Salutation profile.salutation
FirstName profile.first_name
MiddleName profile.middle_name
LastName profile.last_name
DateOfBirth profile.date_of_birth
Age profile.age
PreviousFirstName profile.previous_first_name
PreviousMiddleName profile.previous_middle_name
PreviousLastName profile.previous_last_name
LastVerified profile.last_verified
ProfileUrl profile.profile_url
ProfileShortUrl profile.profile_short_url
CardImageUrl profile.card_image_url
EmailAddresses profile.email_addresses
Identities profile.identities
PhoneNumbers profile.phone_numbers
PostalAddresses profile.postal_addresses
Qualifications profile.qualifications
WebProperties profile.web_properties
IdentityAssured profile.identity_assured
HasPublicProfile profile.has_public_profile
PublicProfile profile.public_profile
CreditBureauVerification profile.credit_bureau_verification

PhoneNumber (documentation link)

API data-type property Ruby equivalent (given `phone` instance of `PhoneNumber`)
DisplayName phone.display_name
CountryCode phone.country_code
NationalNumber phone.national_number
IsMobile phone.is_mobile
IsPrimary phone.is_primary
Verified phone.verified

PostalAddress (documentation link)

API data-type property Ruby equivalent (given `address` instance of `PostalAddress`)
House address.house
Line1 address.line1
Line2 address.line2
City address.city
Region address.region
Code address.code
Country address.country
IsPrimary address.is_primary
Verified address.verified

Qualification (documentation link)

API data-type property Ruby equivalent (given `qualification` instance of `Qualification`)
Type qualification.type
Title qualification.title
DataProvider qualification.data_provider
DataProviderUrl qualification.data_provider_url

QualificationType enumeration type (documentation link)

API data-type property Ruby equivalent
Academic QualificationType.ACADEMIC
Professional QualificationType.PROFESSIONAL

WebProperty (documentation link)

API data-type property Ruby equivalent (given `property` instance of `WebProperty`)
DisplayName property.display_name
Identifier property.identifier
Type property.type
Verified property.verified

WebPropertyType enumeration type (documentation link)

API data-type property Ruby equivalent
Domain WebPropertyType.DOMAIN
Website WebPropertyType.WEBSITE

Model\CreditBureauVerification (documentation link)

API data-type property Ruby equivalent (given `verification` instance of CreditBureauVerification)
Data verification.data
LastVerified verification.last_verified

Model\CreditBureauRefreshStatus (documentation link)

API data-type property Ruby equivalent (given `status` instance of `CreditBureauRefreshStatus`)
State status.state

Data types - Financial API

FinancialAccount (documentation link)

API data-type property Ruby equivalent (given `account` instance of `FinancialAccount`)
AccountName account.account_name
Holder account.holder
SortCode account.sort_code
AccountNumber account.account_number
Type account.type
FromDate account.from_date
LastUpdatedUtc account.last_updated_utc
ClosingBalance account.closing_balance
DebitsSum account.debits_sum
DebitsCount account.debits_count
CreditsSum account.credits_sum
CreditsCount account.credits_count
CurrencyIso account.currency_iso
Transactions account.transactions

FinancialCreditCard (documentation link)

API data-type property Ruby equivalent (given `credit_card` instance of `FinancialCreditCard`)
AccountName credit_card.account_name
Holder credit_card.holder
AccountNumber credit_card.account_number
Type credit_card.type
FromDate credit_card.from_date
LastUpdatedUtc credit_card.last_updated_utc
CreditLimit credit_card.credit_limit
RunningBalance credit_card.running_balance
DebitsSum credit_card.debits_sum
DebitsCount credit_card.debits_count
CreditsSum credit_card.credits_sum
CreditsCount credit_card.credits_count
CurrencyIso credit_card.currency_iso
Transactions credit_card.transactions

FinancialProvider (documentation link)

API data-type property Ruby equivalent (given `provider` instance of `FinancialProvider`)
ProviderName provider.provider_name
FinancialAccounts provider.financial_accounts

FinancialRefreshStatus (documentation link)

API data-type property Ruby equivalent (given `status` instance of `FinancialRefreshStatus`)
State status.state

FinancialTransaction (documentation link)

API data-type property Ruby equivalent (given `transaction` instance of `FinancialTransaction`)
Date transaction.date
AmountCredited transaction.amount_credited
AmountDebited transaction.amount_debited
Description transaction.description
ID transaction.id

MiiFinancialData (documentation link)

API data-type property Ruby equivalent (given `data` instance of `MiiFinancialData`)
FinancialProviders data.financial_providers

RefreshState enumeration type (documentation link)

API data-type property Ruby equivalent
Unknown RefreshState.UNKNOWN
DataAvailable RefreshState.DATA_AVAILABLE
InProgress RefreshState.IN_PROGRESS

Dependencies

The library takes a dependency on:

Contributing

  • Use GitHub issue tracking to report bugs in the library
  • If you're going to submit a patch, please base it off the development branch - the master reflects the latest version published to RubyGems.org but may not necessarily be bleeding-edge

Licence

Copyright (c) 2012, miiCard Limited All rights reserved.

http://opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of miiCard Limited nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Something went wrong with that request. Please try again.