- Data types
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.
- 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.
- Requesting a consumer key and secret
- Authorising with OAuth 1.0a
- Authorisation workflow
- Libraries and Components
- Developer forum
https://sts.miicard.com/api/v1/Claims.svc/xml HTTP POST only
https://sts.miicard.com/api/v1/Claims.svc/json HTTP POST only
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.
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'.
Returns a subset of a miiCard member's identity information as agreed by them.
|Return type||MiiApiResponse of MiiUserProfile (described below)|
- 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.
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.
Returns a subset of a miiCard member's identity information as agreed by them.
|Return type||MiiApiResponse of an IdentitySnapshot object|
- 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
Returns the metadata associated with every identity snapshot your application has obtained of a particular miiCard member
|Return type||MiiApiResponse of a collection of IdentitySnapshotDetails objects|
Determines whether the miiCard member's identity has been assured to the level of assurance required by your developer profile.
|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.
- True if the member's identity has been assured
- False otherwise
Determines whether the miiCard member has verified ownership of a particular social network account.
|Return type||MiiApiResponse of boolean|
- socialAccountId should be the URL of the public profile page of the member or their internal numerical ID as supplied by the Facebook API
- Google (for Google+ accounts)
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.
- 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.
Gets an image representation of the identity assurance level of a miiCard member.
|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.
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.
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.
|Type parameter value||User's identity is assured||User's identity is not assured|
|badge-small||40x18 px||40x18 px|
- 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).
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.
Unless otherwise indicated, all API calls return an object of type MiiApiResponse which wraps the actual response type of the API call.
|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.|
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.
Enumeration type that describes the overall status of an API call.
|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.|
Enumeration type that details a specific problem that occurred when accessing the API.
|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.|
Enumeration type that details the kind of web property a user has linked to their miiCard profile - used by the WebProperty object type.
|Domain||0||A domain name has been linked.|
|Website||1||A website or page has been linked by its URL.|
A structured representation of the subset of a miiCard member's identity that they have agreed to share with the relying party.
|Salutation||string||'Mr', 'Mrs' etc.|
|FullName||string||Verified full name of the user.|
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.|
Represents an email address that the user has linked to their miiCard profile, and for which ownership has been verified.
|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.|
Represents the user's account details on another website, such as a social-media site.
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:
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.|
|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.|
Represents a postal address that the user has linked to their miiCard profile, and at which the user has demonstrated they are resident.
|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.|
Represents a web property that the user has linked to their miiCard profile, for example a domain name or a web page.
|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.|
Represents the metadata associated with a single point-in-time snapshot of a miiCard member's identity data.
|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.|
Represents a single point-in-time snapshot of a miiCard member's identity data.
|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.|