Value Add Services



Value Add Services API Overview

NameDescription

IDVS API

The Identity Validation Service (IDVS) allows for programmatic ID validation and Direct Provisioning.



Have questions? Please contact us for further assistance.

Identity Validation Service (IDVS)

The DataMotion IDVS is a set of web services used to integrate identity validation and Direct address provisioning into applications. The IDVS uses tokens for authentication, which you can get from the Token method. This token should then be used in every IDVS request.

Authentication

The following method handles authentication to the DataMotion IDVS API

box icon

GET A TOKEN

This method authenticates a user and returns a bearer token to be passed as a header value in all subsequent IDVS requests.

URL

{BaseURL}/Token

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/x-www-form-urlencodedThe content-type of the request

Request Body Parameters

KeyValueDescription
grant_typepasswordThis value should be set to "password" to obtain a token
usernamesampleuser@email.comThe email address as established with the IDVS
passwordS@mpleP@$$w0rdThe password as established with the IDVS

Request Body Formats

JSON


grant_type=password&username=sampleuser%40email.com&password=S%40mpleP%40%24%24w0rd

Response Body Parameters

NameDescriptionType
access_tokenThe bearer token used to authenticate to the DataMotion IDVSString
token_typeThe type of token returnedString
expires_inTime (seconds) until token expirationInteger
userNameThe username used to authenticateString
.issuedDate/Time of token issuanceString
.expiresDate/Time of token expirationString

Response Body Formats

JSON


{
   "access_token": "12345ABCDE",
   "token_type": "bearer",
   "expires_in": 719,
   "userName": "sampleuser@email.com",
   ".issued": "Thu, 25 Aug 2016 15:03:01 GMT",
   ".expires": "Thu, 25 Aug 2016 15:15:01 GMT"
 }

Identity Validation

These methods are used to perform core identity validation transactions.

box icon

EXTRACT ID INFO

This method submits an ID image to the IDVS for data extraction.

URL

{BaseURL}/api/IdValidation/ExtractIdInfo

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
AuthorizationBearer 12345ABCDEThe bearer token used to authenticate

Image Guidelines & Recommendations

Some text about the image requirements here. Range of factors including setup and image quality. Here are our recommendations that we've experienced the best results with


  • 1

    Background & Lighting

    One of the main factors that can influence the quality of an image is what happens before a picture is taken. Contrast between the ID card and the background of the full image helps our service detect the boundaries of the card more efficiently. Proper lighting also helps the device camera capture any fine details in the ID, however glares/holograms that overlap text can interfere with the accuracy of the data extraction. We recommend a well-lit environment with the ID card placed on a dark and highly contrasting background. The ID card should take up about 80% of the area of the image with minimal glares/holograms.
  • 2

    Image Size

    The IDVS will not accept images smaller than 1012 x 635 pixels, or larger that 2048 x 2048 pixels. Images should also be less than 5MB each.
  • 3

    Image Format

    The IDVS only accepts base64 encoded strings of JPEG images.
  • 4

    Image Quality

    We recommend at least 80% quality for the JPEG images (100% quality is preferred, if it's possible to keep the image within the sizing constraints). DPI is another factor that influences not only the quality of the data, but the processing time. The higher the quality and/or DPI of the image, the easier it is for our service to extract data quickly and accurately.

Request Body Parameters

NameDescriptionTypeRequired
DocumentsA JSON object containing the following values per accountObject ArrayY

Request Body Formats

JSON


{
   "Documents": [
     {
       "Type": 0,
       "Front": "asdasdasdasd",
       "Back": "asdasdasdasd"
     },
     {
       "Type": 1,
       "Front": "asdasdasdasd",
       "Back": "asdasdasdasd"
     }
   ]
 }

Response Body Values

The parameters in the table below will be present in each response, regardless of the type of document submitted. Only the relevant values that have been extracted will be populated in the response. The remaining values will be returned as null.

NameDescriptionType
AddressStringThe street address as extracted from the document
Address2StringThe second line of the street address as extracted from the document
Address3StringThe third line of the street address as extracted from the document
Address4StringThe fourth line of the street address as extracted from the document
Address5StringThe fifth line of the street address as extracted from the document
Address6StringThe sixth line of the street address as extracted from the document
CityStringThe city as extracted from the document
ClassStringThe class as extracted from the document
ContractCodeStringThe contract code as extracted from the document
CopayERStringThe ER copay as extracted from the document
CopayOVStringThe OV copay as extracted from the document
CopaySPStringThe SP copay as extracted from the document
CopayUCStringThe UC copay as extracted from the document
CountryStringThe country as extracted from the document
CoverageStringThe coverage as extracted from the document
CSCStringThe CSC as extracted from the document
DateOfBirthStringThe date of birth as extracted from the document
DeductibleStringThe deductible as extracted from the document
EffectiveDateStringThe effective date as extracted from the document
EmployerStringThe employer as extracted from the document
EndorsementsStringThe endorsements as extracted from the document
ExpirationDateStringThe expiration date as extracted from the document
EyeColorStringThe eye color as extracted from the document
FatherNameStringThe father name as extracted from the document
FirstNameStringThe first name as extracted from the document
GroupNameStringThe group name as extracted from the document
GroupNumberStringThe group number as extracted from the document
HairColorStringThe hair color as extracted from the document
HeightStringThe height as extracted from the document
IDStringThe ID as extracted from the document
IssueDateStringThe issue date as extracted from the document
IssuerNumberStringThe issuer number as extracted from the document
LastNameStringThe last name as extracted from the document
LicenseStringThe license as extracted from the document
MemberIDStringThe member ID as extracted from the document
MemberNameStringThe member name as extracted from the document
MiddleNameStringThe middle name as extracted from the document
MotherNameStringThe mother name as extracted from the document
NationalityStringThe nationality as extracted from the document
OtherStringOther information as extracted from the document
PassportNumberStringThe passport number as extracted from the document
PayerIDStringThe payer ID as extracted from the document
PersonalNumberStringThe personal number as extracted from the document
PlaceOfBirthStringThe place of birth as extracted from the document
PlaceOfIssueStringThe place of issuance as extracted from the document
PlanAdminStringThe plan admin as extracted from the document
PlanProviderStringThe plan provider as extracted from the document
PlanTypeStringThe plan type as extracted from the document
PrefixStringThe prefix as extracted from the document
RawTextStringThe raw text as extracted from the document
RestrictionsStringThe restrictions as extracted from the document
RXBinStringThe RX Bin as extracted from the document
RXGRoupStringThe RX group as extracted from the document
RXIDStringThe RX ID as extracted from the document
RXPCNStringThe RX PCN as extracted from the document
SexStringThe sex as extracted from the document
StateStringThe state as extracted from the document
SuffixStringThe suffix as extracted from the document
TemplateTypeStringThe template type as extracted from the document
Text1StringMisc. text field as extracted from the document
Text2StringMisc. text field as extracted from the document
Text3StringMisc. text field as extracted from the document
TypeStringThe type as extracted from the document
WeightStringThe weight as extracted from the document
ZipStringThe zip code as extracted from the document

Response Body Formats

JSON


[
   {
      "Address": "123 MAIN STREET",
      "Address2": null,
      "Address3": null,
      "Address4": null,
      "Address5": null,
      "Address6": null,
      "City": "NEW YORK",
      "Class": "D",
      "ContractCode": null,
      "CopayER": null,
      "CopayOV": null,
      "CopaySP": null,
      "CopayUC": null,
      "Country": "United States",
      "Coverage": null,
      "CSC": null,
      "DateOfBirth": "01-01-1975",
      "Deductible": null,
      "EffectiveDate": null,
      "Employer": null,
      "Endorsements": "NONE",
      "ExpirationDate": "01-01-2020",
      "EyeColor": "HZL",
      "FatherName": null,
      "FirstName": "MARY",
      "GroupName": null,
      "GroupNumber": null,
      "HairColor": "",
      "Height": "5'-5",
      "ID": "S1234567890",
      "IssueDate": "01-01-2015",
      "IssuerNumber": null,
      "LastName": "SMITH",
      "License": "S1234567890",
      "MemberID": null,
      "MemberName": null,
      "MiddleName": "",
      "MotherName": null,
      "Nationality": null,
      "Other": null,
      "PassportNumber": null,
      "PayerID": null,
      "PersonalNumber": null,
      "PlaceOfBirth": null,
      "PlaceOfIssue": null,
      "PlanAdmin": null,
      "PlanProvider": null,
      "PlanType": null,
      "Prefix": null,
      "RawText": null,
      "Restrictions": "",
      "RXBin": null,
      "RXGRoup": null,
      "RXID": null,
      "RXPCN": null,
      "Sex": "F",
      "State": "NY",
      "Suffix": "",
      "TemplateType": null,
      "Text1": null,
      "Text2": null,
      "Text3": null,
      "Type": null,
      "Weight": "",
      "Zip": "00000-1111"
    }
]
box icon

SUBMIT ID INFO

This method submits a user's identity for validation.

URL

{BaseURL}/api/IdValidation/SubmitIdInfo

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
AuthorizationBearer 12345ABCDEThe bearer token used to authenticate

Request Body Parameters

NameDescriptionTypeRequired
AddressThe current street address of the individual's residence. Do not include any apartment numbers, suites, etc.StringY
BackImageThe base64 encoded image of the back of the ID. This is only required if your account is enabled to validate government-issued IDs.StringN
CityThe current city of the individual's residence.StringY
CountryCodeThe 3-digit ISO 3166 country codeStringY
DateOfBirth_DayThe two-digit day of birth of the individualStringY
DateOfBirth_MonthThe two-digit month of birth of the individualStringY
DateOfBirth_YearThe four-digit year of birth of the individualStringY
EmailAddressThe email address of the individual. This is only required for Direct address provisioningStringY
FaceImageThe base64 encoded image of the individual's 'selfie.' This is only required if your account is enabled to perform facial comparison.StringN
FirstNameThe first name of the individual. Do not include any middle names/initialsStringY
IdImageThe base64 encoded image of the front of the ID. This is only required if your account is enabled to validate government-issued IDs.StringN
KBAIndicates whether the transaction should return KBA questions. Note: KBA questions must be enabled for your account.BooleanY
LastNameThe last name of the individual. Do not include any suffix, etcStringY
NotifyUserIndicates whether the IDVS should notify the user of the validation results (phone only)BooleanY
PhoneNumberThe phone number of the user to receive a phone call notification of the validation resultsStringY
ScanDocumentTypeThe type of government-issued ID submitted for validation (either 'driverLicense' or 'idCard'). This is only required if your account is enabled to validate government-issued IDs.StringN
StateThe current state of the individual's residence.StringY
ZipThe current zip code of the individual's residence.StringY

Request Body Formats

JSON


{
   "Address": "123 Main Street",
   "City": "New York City",
   "CountryCode": "USA",
   "DateOfBirth_Day": "01",
   "DateOfBirth_Month": "01",
   "DateOfBirth_Year": "1975",
   "EmailAddress": "sample@email.com",
   "FirstName": "Mary",
   "KBA": true,
   "LastName": "Smith",
   "NotifyUser": true,
   "PhoneNumber": "5555555555",
   "State": "NY",
   "SSN4": "0000",
   "Zip": "11101",
   "ScanDocumentType": "driverLicense",
   "IdImage": "Base64StringHere",
   "BackImage": "Base64StringHere",
   "FaceImage": "Base64StringHere"
}

Response Body Values

NameDescriptionType
IdNumberUnique transaction identifier generated by the IDVS. This number should be used for any associated transactionsString
IdResultThe result of initial identity validation. If the result is PASS, the transaction will proceed with KBAs and ID Document validation.String
IssuesAn array of any issues found on the initial lookup of the identityString Array
ErrorsAny errors associated with the transactionString Array
QuestionsIf applicable, the response will include a Question object that contains an array of the following objects These questions should be answered using the SubmitKBA method below.Object Array

Response Body Formats

JSON


{
  "IdNumber": "1234567890",
  "IdResult": "PASS",
  "Issues": [
    "Single Address in File"
  ],
  "Errors": [
    null
  ],
  "Questions": [
    {
      "prompt": "At which of the following addresses have you lived?",
      "type": "previous.address",
      "answer": [
        "4344 BACKTRAIL DR",
        "1084 PEACHTREE CT",
        "5015 B U BOWMAN DR",
        "None of the above"
      ]
    },
    {
      "prompt": "Which person is not a relative or someone that you know?",
      "type": "person.not.known",
      "answer": [
        "DAINE SMITH",
        "ANTHONY BROWN",
        "DAVID BROWN",
        "None of the above"
      ]
    },
    {
      "prompt": "What is the approximate square footage of the property at 222333 PEACHTREE PLACE?",
      "type": "property.size",
      "answer": [
        "1,000 or less",
        "1,001 - 1,500",
        "1,501 - 2,000",
        "2,001 - 2,500",
        "Over 2,500",
        "None of the above"
      ]
    },
    {
      "prompt": "Between 1979 and 1980, in which State did you live?",
      "type": "prior.residence.state.multiyear",
      "answer": [
        "NEW MEXICO",
        "NEW YORK",
        "ALASKA",
        "None of the above"
      ]
    }
  ]
}
box icon

SUBMIT KBA ANSWERS

This method is used to submit KBA answers, if applicable

URL

{BaseURL}/api/IdValidation/SubmitKBA

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
AuthorizationBearer 12345ABCDEThe bearer token used to authenticate

Request Body Parameters

NameDescriptionTypeRequired
IdNumberThe ID# of the corresponding SubmitIdInfo transactionStringY
QuestionsAn array of objects containing the "Type" and "Answer" strings for each given questionObject ArrayY

Request Body Formats

JSON


{
  "IdNumber": "1234567890",
  "Questions": [
    {
      "Type": "previous.address",
      "Answer": "None of the above"
    },
    {
      "Type": "person.not.known",
      "Answer": "DAVID BROWN"
    },
    {
      "Type": "property.size",
      "Answer": "2,001 - 2,500"
    }
  ]
}

Response Body Values

NameDescriptionType
IdNumberUnique transaction identifierString
IdResultResult of the basic identity validation transactionString
IssuesAny issues discovered during identity lookupString Array
ErrorsAny errors encountered during identity lookupString Array
AnswersReceivedThe number of answers submitted to the IDVSString
KBAAnswerResultIndicates how many answers were correctString
KBAResultsPass/Fail of KBA questions, as determined by the IDVSString

Response Body Formats

JSON


{
   "IdNumber": "1234567890",
   "IdResult": "PASS",
   "Issues": [
      "Single Address in File"
   ],
   "Errors": [
      null
   ],
   "AnswersReceived": "3",
   "KBAAnswerResult": "All answers correct",
   "KBAResult": "pass"
}

Direct Provisioning

The following method handles provisioning patient Direct addresses for individuals who have been ID validated by the IDVS.

box icon

PROVISION A PATIENT DIRECT ADDRESS

This method provisions a patient Direct address for a validated individual.

URL

{BaseURL}/api/IdValidation/ProvisionUser

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
AuthorizationBearer 12345ABCDEThe bearer token used to authenticate

Request Body Parameters

NameDescriptionTypeRequired
IdNumberThe transaction ID fromStringY
OrganizationNameThe legal business name of the organization of the certificate recipientStringY
OrganizationCategoryFor patient certificates, this should be set to the value 4IntegerY
CountryThe country where the recipient is located (ie: "US")StringY
CityThe city where the patient is locatedStringY
StateThe state where the patient is locatedStringY
LifetimeThe duration of the Direct address certificateIntegerY
FirstNameThe first name of the patient receiving a Direct addressStringY
LastNameThe last name of the patient receiving a Direct addressStringY
CommonNameThe first and last name of the certificate recipientStringY
SubjectAltNameThe Direct messaging address for which the certificate request is created. This must be an FRC822 compliant addressStringY
EmailAddressThe email address of the patient where they can receive notifications about their Direct activity (ie: new messages, account registration, etc)StringY
PasswordThe password to set for the new Direct address. Note: this field is optional, and if not set, the user will receive an email to the email address included above with instructions to set up a password.StringN
AutoRenewIndicates whether or not the certificate should be automatically renewed upon expirationBooleanY
DelegatedIdProofingIndicates that the Trusted Agent accepts delegating the identity proofing to the IDVSBooleanY
NotesAny optional notes to include to the DataMotion validation teamStringN
TAUserNameThe username of the Trusted Agent on the DataMotion HISPStringY
TAPasswordThe password of the Trusted Agent on the DataMotion HISPStringY

Request Body Formats

JSON


{
   "IdNumber": "1234567890",
   "OrganizationName": "MyTown Hospital",
   "OrganizationCategory": 4,
   "Country": "US",
   "City": "MyTown",
   "State": "MyState"
   "Lifetime": 1,
   "FirstName": "Mary",
   "LastName": "Smith",
   "CommonName": "Mary Smith",
   "SubjectAltName": "Mary.Smith@mytowndirect.com",
   "EmailAddress": "sample@email.com",
   "AutoRenew": true,
   "DelegateIdProofing": true,
   "Notes": "",
   "TAUserName": "TAuser1",
   "TAPassword": "TAP@$$w0rd1",
   "Password": "M@rySm!th123
}

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

Note

It is required that the idNumber correspond to successful KBA validation, ID document validation, and facial comparison transactions. If the ID number has not passed these validation points, the IDVS will return a 403: Forbidden HTTP status code.