This web site uses cookies to improve your experience. By viewing our content, you are accepting the use of cookies. To find out more and change your cookie settings, please view our cookie policy. Close

Claims API

Quick links

The miiCard Claims API v1 provides a simple interface for obtaining the set of identity details that a miiCard member has elected to share with your web application.

Access to the API requires the use of OAuth-authorised requests, and that the miiCard member has authorised your application to consume the relevant identity details. See the Authorising with OAuth 1.0a page for details about our OAuth 1.0a requirements, and the Authorisation Workflow page for details on end-user experience.

You'll need:

  • The OAuth consumer key and consumer secret that you obtained by requesting them from miiCard
  • Knowledge of how to make an OAuth 1.0a-authorised HTTP request and of parsing either SOAP, plain XML or JSON responses

We provide wrapper libraries in a number of programming languages that may speed up your implementation - see the Libraries & Components page. If there's a language that you're using that you think we should support then let us know on the Developer Forum.

Useful resources

Endpoints

Endpoint URL, notes
​SOAP https://sts.miicard.com/api/v1/Claims.svc​
​XML (POX) https://sts.miicard.com/api/v1/Claims.svc/xml​ HTTP POST only
Example: https://sts.miicard.com/api/v1/Claims.svc/xml/GetClaims
​JSON ​https://sts.miicard.com/api/v1/Claims.svc/json HTTP POST only
Example: https://sts.miicard.com/api/v1/Claims.svc/json/GetClaims
Important

Ensure that the Content-type header of the request is appropriate to the endpoint being consumed - for example, when consuming the JSON endpoint your request's Content-Type should be 'application/json'.

The XML endpoint expects a wrapped request if any parameters are to be sent - see the Sample API Output page for more details.

Note

The miiCard member whose details are returned by the Claims API is determined from the OAuth authorisation information supplied in the request. For the purposes of the rest of the documentation, 'current user', 'miiCard user' and 'miiCard member' should be considered to mean 'the user on whose behalf the OAuth request to the API was made'.

Methods

GetClaims method

Returns a subset of a miiCard member's identity information as agreed by them.​

Parameters none
​Return type MiiApiResponse of MiiUserProfile (described below)
The member whose information is to be returned is determined from the OAuth authorisation information supplied by the relying party in an HTTP Authorization header. On success, a structure is returned to the caller containing a subset of their identity information. The subset shall contain at minimum:
  • Their full name (e.g. 'John Doe')
  • A flag indicating whether they have a public profile page
  • A URL linking to their public profile page - this is supplied irrespective of the above flag
  • A URL linking directly to the member's miiCard-image as can be seen on the profile page for easy embedding - this will be inaccessible if the member doesn't have a public profile page

In addition, further information may be populated depending upon the set of claims that the relying party requested be sent, and the set of claims that the member ultimately agreed to share with the relying party. You can configure the set of claims you want or absolutely require from a miiCard member when your request your consumer key and secret or via the self-management Business Portal.

Important

The miiCard member can only elect to share identity information that has been verified by miiCard. However, once they've agreed to share that information it is possible that some or all of it may lapse into an unverified state.

For example, the level of assurance that you require may no longer be met, or the member might have changed their surname and needs now to re-validate all of their social media accounts. As such, it's possible that over time the Claims API yields unverified information. The consumer must make sure to check the Verified property on any phone-number, email address, identity or postal address, and further check the IdentityAssured property on the top-level MiiUserProfile object.

GetIdentitySnapshot method Transactional

Returns a subset of a miiCard member's identity information as agreed by them.​

Parameters snapshotId
  • The unique ID of the snapshot to be retrieved. You can discover what snapshots are available for a miiCard member by calling the GetIdentitySnapshotDetails method with empty snapshotId.
​Return type MiiApiResponse of an IdentitySnapshot object
When your application is configured for transactional model use, each time a miiCard member goes through the OAuth process a snapshot of their identity information is taken. You can then supply the unique identifier of that snapshot to the GetIdentitySnapshot method and obtain a point-in-time view of the subset of that member's identity data that they elected to share with your application.
 
This data:
  • Is available for 7 years from the point at which the snapshot was taken
  • Persists even if the miiCard member deletes their account or revokes access to their live identity data for your application
  • Is collected and is available for all miiCard members, even those without a premium subscription

GetIdentitySnapshotDetails method Transactional

Returns the metadata associated with every identity snapshot your application has obtained of a particular miiCard member​

Parameters snapshotId (optional)
  • The unique ID of the particular snapshot whose metadata is to be retrieved. If empty, details of all snapshots against the miiCard member are returned.
​Return type MiiApiResponse of a collection of IdentitySnapshotDetails objects
When your application is configured for transactional model use, each time a miiCard member goes through the OAuth process a snapshot of their identity information is taken. You can discover the latest snapshots of a member's identity by calling this method when the member returns to your application from the OAuth process.
 

IsUserAssured method

Determines whether the miiCard member's identity has been assured to the level of assurance required by your developer profile.

​Parameters none
​Return type MiiApiResponse of ​boolean (described below)

IsUserAssured determines whether the current member's identity has been validated and assured by miiCard. The specific level of assurance will depend upon your use-case - by default we require that they have linked a single financial account to their profile to validate their name and identity.

It is anticipated that the caller will use this information to give some visual indication on their site that the member's identity has been verified by miiCard. For example, it might form the basis of a profile badge, or an overlay upon their profile image.

Returns

  • True if the member's identity has been assured
  • False otherwise

IsSocialAccountAssured method

Determines whether the miiCard member has verified ownership of a particular social network account.

​Parameters socialAccountId
  • The member's username on the social network for which data is required.

socialAccountType

  • The name of the social network to which the username belongs. A list of appropriate values is available in the remarks section below.
​Return type MiiApiResponse of ​boolean
IsSocialAccountAssured allows the caller to verify that a particular miiCard member owns an account on a social network, so long as they has elected to share those details with your application. The socialAccountId parameter is generally expected to be a username or public profile URL unless otherwise noted. The socialAccountType parameter can be one of the following:
  • Facebook
    • socialAccountId should be the URL of the public profile page of the member or their internal numerical ID as supplied by the Facebook API
  • Twitter
  • LinkedIn
  • Google (for Google+ accounts)
  • LiveID

The socialAccountType is treated case-insensitively. The set of values that can be supplied will expand as miiCard expands the number of social accounts that can be validated - check back often to find out the latest set, which will be updated above.

Returns

  • True if the miiCard member has verified that they own the social network account specified
  • False otherwise. Note, that if the member has elected not to share information about the requested social network with your application false shall also be returned.

AssuranceImage method

Gets an image representation of the identity assurance level of a miiCard member.

​Parameters
type
  • The kind of graphic to be returned. Must be one of:
    • badge
    • badge-small
    • banner
Return type Stream - a stream of bytes representing a PNG image, with content type 'image/png' if the request was made via the JSON or XML end-points. Importantly, there is no wrapping around the response of the method - expect raw image data, and not a MiiApiResponse object as with most of the other API methods

AssuranceImage allows you to quickly present a miiCard badge on a user profile or similar while simultaneously checking the miiCard member's identity assurance status. This method is intended for low-volume consumption, and isn't likely to be the best method for larger sites.

Note

The caller will have to relay the stream from the miiCard server to the client machine, as the request will not be serviced if it is not accompanied by an HTTP Authorization header as required by OAuth 1.0a and client machines will not have the requisite information to make such a request. This relaying is very straightforward in most applications, and allows you to perform caching or additional referrer checks as necessary.

Important

It is recommended that the caller cache the output of the call, or that they use the IsUserAssured method and manually render the correct assurance badge if they expect anything more than a modest amount of site traffic.

The following table shows the results of this call rendered as PNG images, for the cases where the miiCard member's identity matches your level of assurance requirements, and for the cases where it does not.
​Type parameter value User's identity is assured​ User's identity is not assured​
​badge-small ​40x18 px ​40x18 px
​badge ​118x53 px ​118x53px
​banner ​365x48px 365x48px

Returns

  • An image in line with the above table if the specified 'type' was recognised
  • A null stream otherwise

Data type definitions

Unless otherwise noted, these definitions indicate the structure of responses - the wire format of the response will depend on the API end-point being called (for example, the structure would be rendered to JSON if a JSON endpoint were consumed).

MiiApiResponse type

A wrapper that surrounds all responses to API calls detailing the success or failure of the call and containing additional information to help diagnosing issues.

Note

Unless otherwise indicated, all API calls return an object of type MiiApiResponse which wraps the actual response type of the API call.

Field Type Notes
Status MiiApiCallStatus enum A member of the MiiApiCallStatus enumeration that describes the overall status of the API call.
ErrorCode MiiApiErrorCode enum A member of the MiiApiErrorCode enumeration that describes the nature of any error that occurred while making the API call.
ErrorMessage string Additional error message that may optionally be supplied for certain types of API error. This is intended for caller diagnostics only, and should not be output to the user.
Data variant The payload of the response. The data type will depend upon the API method being called.
IsTestUser boolean

Specifies if the user on whose behalf you made the API call is currently marked as a 'tester' for your application. Test users always report as having valid identities - you should allow them to access your application only during development.

MiiApiCallStatus enumeration type

Enumeration type that describes the overall status of an API call.

Member Numeric code Description
Success 0 The API call succeeded - the associated result information can be found in the Data property of the response object.
Failure 1 The API call failed. You can get more information about the nature of the failure by examining the ErrorCode field.

MiiApiErrorCode enumeration type

Enumeration type that details a specific problem that occurred when accessing the API.

Member Numeric code Description
Success 0 The API call succeeded.
AccessRevoked 100 The user has revoked access to your application. The user would have to repeat the OAuth authorisation process before access would be restored to your application.
UserSubscriptionLapsed 200 The user's miiCard subscription has elapsed. Only users with a current subscription can share their data with other applications and websites.
TransactionalSupportDisabled 1000 Your application has not been enabled for transactional support but you are attempting to make a call to a part of the API that relates to the transactional charging model
DevelopmentTransactionalSupportOnly 1010 Your application has been configured for transactional usage for nominated test accounts, and the user attempting to perform an OAuth exchange is not one of those test accounts.
InvalidSnapshotId 1020 The snapshot ID provided to a method that expects a snapshot ID does not exist, or does not belong to the user on whose behalf you are making an OAuth call
Blacklisted 2000 Your application has been suspended and no API access can take place until miiCard releases the suspension on your application.
ProductDisabled 2010 Your application has been disabled, either by your request or by miiCard. miiCard members will be unable to go through the OAuth process for your application, though you will still be able to access the API.
ProductDeleted 2020 Your application has been deleted. miiCard members will be unable to go through the OAuth process for your application, nor will you be able to access identity details through the API.
Exception 10000 A general exception occurred during processing - details may be available in the ErrorMessage property of the response object depending on the nature of the exception.

WebPropertyType enumeration type

Enumeration type that details the kind of web property a user has linked to their miiCard profile - used by the WebProperty object type.

Member Numeric code Description
Domain 0 A domain name has been linked.
Website 1 A website or page has been linked by its URL.

MiiUserProfile type

A structured representation of the subset of a miiCard member's identity that they have agreed to share with the relying party.

Field​ Type Notes
Salutation string 'Mr', 'Mrs' etc.
FullName string Verified full name of the user.
FirstName string  
MiddleName​ string If applicable​.
LastName string  
DateOfBirth optional DateTime The miiCard member's verified date of birth.
United Kingdom miiCard members only - worldwide support coming soon
PreviousFirstName string​ If the user has legally changed their name, their first name prior to the change​ - otherwise empty.
​PreviousMiddleName ​string ​If the user has legally changed their name, their middle name prior to the change​ - otherwise empty.
PreviousLastName string If the user has legally changed their name, their last name prior to the change - otherwise empty.
LastVerified DateTime Date and time that the user's financial (or equivalent) validation was last performed. Systems demanding a high level of assurance in the user's identity should consider interrogating this field and implementing a staleness check.
ProfileUrl string A URL to the user's public miiCard profile page. Note that this is a calculated value, and is always supplied even if the user doesn't have a public profile. The caller should check the HasPublicProfile field in tandem with this field.
ProfileShortUrl string The shortened URL of the user's miiCard profile page. Note that this is a calculated value, and is always supplied even if the user doesn't have a public profile. The caller should check the HasPublicProfile field in tandem with this field.
​CardImageUrl ​string ​A URL to the user's miiCard image as is shown on their profile page. This image is dynamically generated and the URL provided for easy embedding. Note that this is a calculated value, and is always supplied even if the user doesn't have a public profile. The caller should check the HasPublicProfile field in tandem with this field.
EmailAddresses Collection of EmailAddress ​A collection of email addresses associated with the user.
​Identities ​Collection of Identity ​A collection of alternative identities for the user - for example, on social media sites.
​PhoneNumbers ​Collection of PhoneNumber ​A collection of phone numbers associated with the user.
​PostalAddresses ​Collection of PostalAddress ​A collection of postal addresses associated with the user.
WebProperties Collection of WebProperty A collection of web properties associated with the user, such as domain names or URLs.
​IdentityAssured boolean​ ​Whether the information about the user meets the level of assurance you configured in your developer profile. You should always check the value of this property to ensure that you are only using validated information.
HasPublicProfile boolean Indicates whether the user has published any of their identity information publicly on their public profile page. This isn't a mandatory step for a user, so the consumer should check the value of this field before linking to the URL supplied in the ProfileUrl field
PublicProfile MiiUserProfile If the user has published any portion of their identity on their public profile page, and if the user has elected to share that information with your application, that same set of details shall be accessible via this field.

EmailAddress type

Represents an email address that the user has linked to their miiCard profile, and for which ownership has been verified.

Field Type Notes
DisplayName ​string The name that the user has used to describe this email address. The consuming party should consider using this name when referring to the email address, as it may have specific meaning for the user. Equally the consuming party should not try to infer the kind of email address from the display name.
Address string The email address.
IsPrimary boolean If true, the user has specified that this is their primary email address. If multiple email addresses are supplied to the consumer, they should consider preferring the one marked as 'IsPrimary'.
Verified boolean If true, the email address has been verified as linked to this miiCard user. The consumer should always check the Verified field as while the user cannot initially share information that hasn't been verified, it's possible that the information subsequently lapses into an unverified state.

Identity type

Represents the user's account details on another website, such as a social-media site.

Field Type​ Notes
Source string

The name of the site to which the identity pertains. This is not an enumeration-type field and may grow to include more values in the future. Current possible values include:

  • Facebook
  • Google
  • LinkedIn
  • LiveID
  • Twitter
  • eBay

Consumers should not rely on the casing of the returned value, and perform all comparisons case-insensitively.
UserId string The user's username or user ID on the site.
​ProfileUrl string If one exists and is available, the URL to the user's public profile page on the site.
Verified boolean​ If true, the social media identity has been verified as linked to this miiCard user. The consumer should always check the Verified field as while the user cannot initially share information that hasn't been verified, it's possible that the information subsequently lapses into an unverified state.

PhoneNumber type

Represents a phone number that the user has linked to their miiCard profile, and for which ownership has been verified.
Field​ Type Notes
DisplayName string The name that the user has used to describe this phone number. The consuming party should consider using this name when referring to the phone number, as it may have specific meaning for the user. Equally the consuming party should not try to infer the kind of phone number from the display name.
CountryCode string The ITU-T E.164 country code of the phone number.
NationalNumber string The national component of the phone number.
IsMobile boolean True if the phone number is linked to a mobile telephone.
IsPrimary boolean If true, the user has specified that this is their primary phone number. If multiple phone numbers are supplied to the consumer, they should consider preferring the one marked as 'IsPrimary'.
Verified boolean​ If true, the phone number has been verified as linked to this miiCard user. The consumer should always check the Verified field as while the user cannot initially share information that hasn't been verified, it's possible that the information subsequently lapses into an unverified state.

PostalAddress type

Represents a postal address that the user has linked to their miiCard profile, and at which the user has demonstrated they are resident.

Field​ Type​ Notes
House string The name or number of the building referred to by the address.
Line1 string The first line of the address.
​Line2 string The second line of the address.
City string The city of the address.
Region string The region (for example county, state or department) of the address.
Code string The postal code of the address.
Country string The country of the address.
IsPrimary boolean If true, the user has specified that this is their primary address (i.e. the address to which correspondence would ordinarily be sent). If multiple addresses are supplied to the consumer, they should consider preferring the one marked as 'IsPrimary'.
Verified boolean​ If​ true, the postal address has been verified as linked to this miiCard user. The consumer should always check the Verified field as while the user cannot initially share information that hasn't been verified, it's possible that the information subsequently lapses into an unverified state.

WebProperty type

Represents a web property that the user has linked to their miiCard profile, for example a domain name or a web page.

Field​ Type​ Notes
DisplayName string The display name that the user has given the web property. When referring to the property in your own applications, it is recommended that you use or at least include this display name as it may have specific meaning to the user.
Identifier string The identifier of the web property, which will be specific to the type of property being described. For domain-type properties this will be the domain name, while for site-type properties this will be a URL to the page or site.
Type WebPropertyType enum The type of web property that has been linked.
​Verified boolean​ If​ true, the web property has been verified as linked to this miiCard user. The consumer should always check the Verified field as while the user cannot initially share information that hasn't been verified, it's possible that the information subsequently lapses into an unverified state.

IdentitySnapshotDetails type

Represents the metadata associated with a single point-in-time snapshot of a miiCard member's identity data.

Field​ Type​ Notes
SnapshotId string The unique identifier for the snapshot - you can record this for auditing purposes.
Username string The username of the miiCard member whose identity data is contained within the snapshot.
TimestampUtc DateTime The date and time (in UTC) at which the snapshot was created - you can record this for auditing purposes. You should examine this field before pushing a miiCard member through the OAuth process to avoid unexpected charges on your account.
WasTestUser boolean​ If​ true, indicates that the miiCard member was marked as a 'tester' for your application at the point at which the snapshot of their identity was taken - as such, the stored identity verification details cannot be trusted. Your production code should disregard snapshots of this type.

IdentitySnapshot type

Represents a single point-in-time snapshot of a miiCard member's identity data.

Field​ Type​ Notes
Details IdentitySnapshotDetails An IdentitySnapshotDetails object containing a description of the snapshotted data.
Snapshot MiiUserProfile A MiiUserProfile object that contains the subset of the miiCard member's identity data that they agreed to share at the point in time the snapshot was taken.