MaxMD Auto Identity Proofing API v3.0

Restful Service for automatic LoA3 Identify Proofing Service. This page includes description about service actions and data types.

Functions

AuthenticationResponseType logIn (AuthenticationRequestType request)

URL

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/logIn

Description

Content-Type: application/json is required at request.

Authenticate using your Reseller or T-User username and password, and received a new sessionId in response. Each sessionId will expire in 10 minutes. You will use this sessionID in further function calls to complete the Identity Proofing.

DEPRECATED VerificationResponseType verifyAndAuthenticate (@PathParam("sessionId") String sessionId, IDPerson idp , @PathParam("autoSendOTP") boolean autoSendOTP )

Important Note: This function has been deprecated as of December 2021

URL

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/verifyAndAuthenticate/{sessionId}/{autoSendOTP}

Description

Content-Type: application/json is required at request.

Verify a unique individual. This creates a transaction with steps below to confirm accuracy of application data identifying a unique individual. This function creates a transaction to complete below steps one by one:

  1. Verify full name, address, date of birth
  2. Verify Government ID Number (Social Security Number). Individual has 3 chances to input correct information for step 1 and step 2
  3. If autoSendOTP is true, generate a One Time Password (OTP) for multi-fact authentication and sent it to individual's device.
Once the OTP is collected from user, call function verifyMFAOTP() to verify the OTP and finalize the LoA3 authentication. The OTP will expire in 10 minutes. If OTP is lost or timed out, call generateMFAOTP() to generate OTP.

IDProofingResponseType generateMFAOTP (@PathParam("sessionId") String sessionId, VerifyOTPRequestType request )

URL

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/generateMFAOTP/{sessionId}

Description

Content-Type: application/json is required at request.

Input full name, date of birth and last four digits of SSN to match a verified individual. Then generate a new OTP, and send it to the individual's device. The individual has 3 chances to generate a new OTP.

VerificationResponseType verifyMFAOTP (@PathParam("sessionId") String sessionId, VerifyOTPRequestType request )

URL

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/one-time-password-verify/{sessionId}

Description

Content-Type: application/json is required at request.

Multi-fact Authentication Input full name, date of birth and last four digits of SSN to match a verified individual. Then verify multi-factor authentication OTP for the individual to complete the LoA3 authentication. The individual has 3 chances to input the correct OTP.

VerificationResponseType verifyCreditCard (@PathParam("sessionId") String sessionId, VerifyCreditCardType request )

URL

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/verifyCreditCard/{sessionId}

Description

Content-Type: application/json is required at request.

Multi-fact Authentication Verify an individual's Credit Card. The credit card data will be transmitted securely, and they will not be saved on the server. The individual has 3 chances to input the correct credit card information.

VerificationResponseType verifyMobileNumber (@PathParam("sessionId") String sessionId, @PathParam("mobileNumber") String mobileNumber, @PathParam("replaceMobileNumber") boolean replaceMobileNumber, IDPersonMeta personMeta)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/verifyMobileNumber/{sessionId}/{mobileNumber}/{replaceMobileNumber}

Description

Content-Type: application/json is required at request.

Verify a mobile number for the MFA One Time Password verification, or if individual wants to change a mobile number for the OTP verification. The individual has 3 chances to input the correct mobile number.

IndividualHealthcareVerificationResponse VerifyProviderInformation (@PathParam("sessionId") String sessionId, VerifyIndividualHealthcareRequestType request)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/VerifyProviderInformation/{sessionId}

Description

Content-Type: application/json is required at request.

Verify the provider by NPI number, DEA number and medical credential.

GetRegisteredPersonsResponseType GetRegisteredPersons (@PathParam("sessionId") String sessionId, boolean LoA3CertifiedOnly)

URL [@GET]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/GetRegisteredPersons/{sessionId}/{LoA3CertifiedOnly}

Description

Content-Type: application/json is required at request.

Get a list of registered persons.

VerificationResponseType SaveIDProofedIndividual (@PathParam("sessionId") String sessionId, IDPerson person)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/SaveIDProofedIndividual/{sessionId}

Description

Content-Type: application/json is required at request.

TrustedAgent could call this funciton to save Identify Proofed Individual record.

VerificationResponseType CheckIDProofingStatus (@PathParam("sessionId") String sessionId, IDPerson person)

URL [@GET]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/CheckIDProofingStatus/{sessionId}

Description

Content-Type: application/json is required at request.

Check whether the ID proof process is completed

GetRegisteredPersonDetailsResponseType GetRegisteredPersonDetails (@PathParam("sessionId") String sessionId, @PathParam("organizationName") String organizationName, @PathParam("LoA3CertifiedOnly") boolean LoA3CertifiedOnly)

URL [@GET]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/personal/CheckIDProofingStatus/{sessionId}/{organizationName}/{LoA3CertifiedOnly}

Description

Content-Type: application/json is required at request.

Get a list of registered persons detail.

OrganizationVerificationResponseType verifyOrganization (@PathParam("sessionId") String sessionId, IDOrganization organization)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/organizations/verifyOrganization/{sessionId}

Description

Content-Type: application/json is required at request.

Verify submitted organization information through D&B database. organization.organizationType should be HE (Healthcare Entity) or BA (Business Associate) . organization.duns (D&B D-U-N-S number) is required.
The status will be returned as response.verificationStatus

OrganizationVerificationResponseType verifyHealthcareOrganization (@PathParam("sessionId") String sessionId, IDOrganization organization)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/organization/verifyHealthcareOrganization/{sessionId}

Description

Content-Type: application/json is required at request.

Verify health care information for the submitted organization through CMS NPI database. organization.organizationType should be CE (Covered Entity). organization.npi is required.
The status will be returned as response.healthcareVerificationStatus

OrganizationVerificationResponseType verifyOrganizationWithDetails (@PathParam("sessionId") String sessionId, IDOrganizationWithDetails organization)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/organizations/verifyOrganizationWithDetails/{sessionId}

Description

Content-Type: application/json is required at request.

Verify submitted organization information through D&B database. organization.organizationType should be HE (Healthcare Entity) or BA (Business Associate) . organization.duns (D&B D-U-N-S number) is required.
The status will be returned as response.verificationStatus

OrganizationVerificationResponseType verifyHealthcareOrganizationWithDetails (@PathParam("sessionId") String sessionId, IDOrganizationWithDetails organization)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/organization/verifyHealthcareOrganizationWithDetails/{sessionId}

Description

Content-Type: application/json is required at request.

Verify health care information for the submitted organization through CMS NPI database. organization.organizationType should be CE (Covered Entity). organization.npi is required.
The status will be returned as response.healthcareVerificationStatus

GetRegisteredOrganizationsResponseType GetRegisteredOrganizations (@PathParam("sessionId") String sessionId, boolean verifiedOnly)

URL [@GET]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/healthcare/GetRegisteredOrganizations/{sessionId}/{verifiedOnly}

Description

Content-Type: application/json is required at request.

Get a list of registered organizations.

OrganizationVerificationResponseType SaveCertifiedOrganizationWithDetails (@PathParam("sessionId") String sessionId, IDOrganizationWithDetails organization)

URL [@POST]

https://api.directmdemail.com/AutoProofingRESTful/rest/app/organizations/saveCertifiedOrganizationWithDetails/{sessionId}

Description

Content-Type: application/json is required at request.

Save certified organizations with customized parameters

Data types

IDProofingResponseType

Parameter Description
Boolean success Whether the operation successfully completed. Required
String code Response code:
  • WR:001 - Missing parameters
  • WR:002 - Session invalid or expired
  • WP:003 - Missing first name
  • WP:004 - Missing last name
  • WP:005 - Missing last 4 digits of SSN
  • WP:006 - Missing Date of Birth
  • Auth:001 - Authentication failed.
  • Auth:010 - Authorization failed.
  • Console:001 - Generate Password Hash failed.
  • Console:099 - Failed when executing bridge console.
  • AP:1 - Can not register the person. It is already registered.
  • AP:2 - No person is loaded. Please register a person or find a registered person first.
  • AP:66 - Unnecessary Healthcare Verification process. The person's healthcare information has already been verified.
  • AP:3 - Unnecessary Verification process. The person is already verified.
  • AP:4 - Unnecessary Authentication process. The person is already authenticated.
  • AP:5 - Unnecessary Multi-fact Authentication process. The person is already multi-fact authenticated.
  • AP:39 - Unnecessary Phone Verification process. This individual already has a mobile number been verified.
  • AP:6 - No person is found.
  • AP:7 - No transaction is found.
  • AP:8 - Person is not verified.
  • AP:40 - The person does not have a verified mobile number.
  • AP:9 - Person is not authenticated.
  • AP:10 - Person LexID is not found.
  • AP:11 - Missing parameter
  • AP:12 - Invalid parameter
  • AP:21 - Failed when calling Verification service.
  • AP:22 - Failed when calling Authentication service.
  • AP:23 - Failed when calling Multi-fact Authentication service EnrollSubject operation.
  • AP:24 - Failed when calling Multi-fact Authentication service QuerySubject operation.
  • AP:72 - One Time Password manager is not configured.
  • AP:73 - Failed when send SMS message. Unexpected HTTP Respnose Code
  • AP:25 - Failed to Generate One Time Password.
  • AP:26 - Failed to Verify One Time Password.
  • AP:27 - Failed when calling Multi-fact Authentication service Verify Phone number operation.
  • AP:31 - Too many Generate One Time Password requests.
  • AP:33 - Too many Verify One Time Password requests.
  • AP:32 - Too many Verification requests.
  • AP:34 - Too many Verify Credit Card requests.
  • AP:35 - Invalid credit card number
  • AP:36 - Unsupported credit card type
  • AP:37 - Failed when verifying Credit Card
  • AP:68 - Failed when verifying Healthcare information.
  • AP:38 - Too many Verify Phone number requests.
  • AP:51 - No organization is loaded. Please register an organization or find a registered organization first.
  • AP:52 - The submitted the healthcare information does not match the CMS NPI record.
  • AP:Notice:1 - The submitted organization name doesn't exactly match the CMS NPI record.
  • AP:Notice:3 - The submitted individual name doesn't exactly match the CMS NPI record.
  • AP:53 - The CMS NPI Database connection is not configured.
  • AP:54 - Failed when query CMS NPI database. No content is responded.
  • AP:55 - Failed when query CMS NPI database. Unexpected HTTP Respnose Code
  • AP:DnB:1 - Failed when query D&B API. No content is responded.
  • AP:DnB:2 - Failed when query D&B API database. Unexpected HTTP Respnose Code
  • AP:DnB:3 - Failed to parse the D&B API response
  • AP:DnB:4 - Failed to authentication to D&B API
  • AP:DnB:5 - Unrecognized D&B API response code
  • AP:DnB:6 - Failed to match organization through D&B API
  • AP:DnB:7 - Failed to get organization details from D&B API
  • AP:DnB:8 - No organization is matched through D&B API
  • AP:DnB:9 - D-U-N-S number is missing
  • AP:DnB:10 - The submitted the organization information does not match the D&B record.
  • AP:Notice:2 - The submitted organization name doesn't exactly match the D&B record.
  • AP:DnB:11 - No organization is matched by the submited DUNS number
  • AP:CNAM:1 - Failed to compose Mobile number verification query
  • AP:CNAM:2 - Failed when query CNAM API. No content is responded.
  • AP:CNAM:3 - Failed to parse CNAM Query Response.
  • AP:CNAM:4 - Verify Phone number failed.
  • AP:70 - Unable to save certified organization, the credential is not Trusted Agent.
  • AP:71 - Unable to save ID Proofed individual, the credential is not Trusted Agent.
  • AP:69 - Failed to parse the CMS NPI query response.
  • AP:56 - No NPI record is found for number
  • AP:57 - Invalid NPI Type
  • AP:58 - Unnecessary Healthcare Verification process. The organization is already verified as Healthcare provider.
  • AP:SYS:9 - CMS NPI verification module is not found.
  • AP:SYS:10 - Memory Cache module is not found.
  • AP:SYS:11 - Session id is invalid or expired.
  • AP:SYS:12 - D&B Organization verification module is not found.
  • AP:59 - Too many Organization Healthcare Verification requests.
  • AP:67 - Too many Individual Healthcare Verification requests.
  • AP:60 - Can not register the organization. It is already registered.
  • AP:61 - Unnecessary Verification process. The organization is already verified
  • AP:62 - Too many Organization Verification requests.
  • AP:63 - Organization Type is missing.
  • AP:64 - Unrecognized Organization Type
  • AP:65 - Unexptected Organization Type
  • AP:DB:2 - Unable to create transaction in Database.
  • AP:DB:3 - Unable to update transaction in Database.
  • AP:DB:4 - Unable to update user status to Verified.
  • AP:DB:5 - Unable to update user status to Authenticated.
  • AP:DB:6 - Unable to update user status to Verified and Authenticated.
  • AP:DB:11 - Unable to update user status to Provider Verified.
  • AP:DB:7 - Unable to update user status to Multi-fact Authenticated.
  • AP:DB:9 - Unable to update user status to Paid.
  • AP:DB:8 - Unable to update user configuration or profile.
  • AP:DB:10 - Unable to save confirmation code to Database.
  • AP:DB:11 - Unable to update organization verification status.
  • AP:SYS:1 - Unable to encrypt or decrypt SSN.
  • AP:SYS:2 - Missing system parameter [role].
  • AP:SYS:3 - Missing system parameter [agent].
  • AP:SYS:4 - Unable to find the Verification credential.
  • AP:SYS:5 - Unable to find the Multi-fact Authentication credential.
  • AP:SYS:6 - Unable to read and decript the Verification credential.
  • AP:SYS:7 - Unable to read and decript the Multi-fact Authentication credential.
  • AP:SYS:8 - Credit card verification module is not found.
  • BS:001 - Internal Error. No operation and data is found.
  • BS:002 - Internal Error. No input parameter file is found.
  • BS:003 - Internal Error. Invalid operation data.
  • BS:004 - Internal Error. Missing parameter.
  • BS:010 - Authentication failed. Username or password is incorrect.
  • BS:011 - Authentication failed. Invalid Session id.
  • BS:012 - Internal Error. Permission denied.
  • BS:013 - Internal Error. Unable to load Reseller object from the TUser.
  • BS:P:999 - Failed when running payment process.
 Required
String message message
Top

AuthenticationResponseType ( extends IDProofingResponseType )

Parameter Description
String sessionId A new sessionId that binding to the credential. Each sessionId will expire in 10 minutes. Required
Top

IDOrganization ( extends IDOrganizationMeta )

Parameter Description
String npi NPI number of the organization. (without dash or space) Required
String duns D&B D-U-N-S® Number Required
String organizationType
  • CE - Covered Entity
  • HE - Healthcare Entity
  • BA - Business Associate
 Required
String street1 Street line 1 Required
String street2 Street line 2
String city City Required
String zip5 Zipcode of home address in five-character format (ex: 07024). Required
String country Country code in two-character format (ex: US). Required
String dea DEA number without dash or space
String medicalLicense reserved parameter
String medicalLicenseState reserved parameter
Top

IDOrganizationWithDetails ( extends IDOrganization )

Parameter Description
Map<String, String> verifiedDetails Customized organization settings using key value pair
Map<String, String> providerVerifiedDetails Customized provider settings within the organization using key value pair
Top

GetRegisteredOrganizationsResponseType ( extends IDProofingResponseType )

Parameter Description
IDOrganizationInfoCollection[ ] organizations Matched organization records
Top

IDOrganizationInfoCollection ( extends IDOrganizationMeta )

Parameter Description
String npi NPI number of the organization. Required
String duns D&B D-U-N-S® Number Required
String organizationType
  • CE - Covered Entity
  • HE - Healthcare Entity
  • BA - Business Associate
 Required
String recordCreatedDate Create date (YYYY-MM-DD) Required
String recordUpdatedDate Create date (YYYY-MM-DD) Required
IDProofingStatusType status Status of the ID Proofing flow with below possible values:
  • Registered - Organization record is saved into MaxMD database
  • HealthcareVerified - Organization healthcare information is verified
 Required
Top

IDOrganizationMeta

Parameter Description
long id unique id of the organization record
String name Organization name
String taxid Organization TaxID without dash or space
String state State of the organization location in two characters format (ex: NJ)
Top

OrganizationVerificationResponseType ( extends IDProofingResponseType )

Parameter Description
IDPersonMeta personMeta Reserved parameter.
IDOrganizationMeta organizationMeta Organization information. This parameter will be empty if it's verifying personal health care information
OrganizationVerificationStatusType healthcareVerificationStatus Status of the healthcare information verification with the following values:
  • Init - Initial
  • Registered - Organization record is saved into MaxMD database
  • NameFuzzyMatched - Organization name doesn't exactly match the D&B record. Other information is all verified.
  • Verified - Organization information is verified
OrganizationVerificationStatusType verificationStatus Status of the organization verification with the following values:
  • Init - Initial
  • Registered - Organization record is saved into MaxMD database
  • NameFuzzyMatched - Organization name doesn't exactly match the D&B record. Other information is all verified.
  • Verified - Organization information is verified
String confirmationCode Confirmation code
String expectedOrganizationName Exact organization name in the CMS NPI database or D&B database. This parameter is returned when verificationStatus/healthcareVerificationStatus is NameFuzzyMatched.
Top

GetRegisteredPersonsResponseType ( extends IDProofingResponseType )

Parameter Description
IDPersonInfo[ ] persons Matched person records.
Top

IDPersonInfo ( extends IDPersonMeta )

Parameter Description
String recordCreatedDate Create date (YYYY-MM-DD) Required
String recordUpdatedDate Create date (YYYY-MM-DD) Required
IDProofingStatusType status Status of the ID Proofing flow with below possible values:
  • Registered - User information is registered, but has not verified or authenticated
  • Verified - User is verified but has not authenticated
  • VerifiedAndAuthenticated - User is verified and authenticated, but has not passed the multi-fact authentication process
  • VerifiedAndAuthenticatedAndMobileVerified - User is verified and authenticated, but has not passed the multi-fact authentication process. The mobile number is verified and ready to be used for multi-fact One Time Password verification
  • LoA3Certified - User is verified, authenticated and multi-fact authenticated. User is LoA3 Certificated.
 Required
Top

VerificationResponseType ( extends IDProofingResponseType )

Parameter Description
IDPersonMeta personMeta Individual's information. Required
IDProofingStatusType verificationStatus Status of the ID Proofing flow with below possible values:
  • Init - Initial
  • Registered - User information is registered, but has not verified or authenticated
  • Verified - User is verified but has not authenticated
  • VerifiedAndAuthenticated - User is verified and authenticated, but has not passed the multi-fact authentication process
  • VerifiedAndAuthenticatedAndMobileVerified - User is verified and authenticated, but has not passed the multi-fact authentication process. The mobile number is verified and ready to be used for multi-fact One Time Password verification
  • MFAOTPGenerated - User is verified and authenticated, multi-fact authentication One Time Password has been sent to user's device
  • LoA3Certified - User is verified, authenticated and multi-fact authenticated. User is LoA3 Certificated.
 Required
String confirmationCode Confirmation code

GetRegisteredPersonDetailsResponseType ( extends IDProofingResponseType )

Parameter Description
ArrayList<IDPersonInfoDetail> persons Matched person detail records.

IndividualHealthcareVerificationResponse ( extends VerificationResponseType )

Parameter Description
boolean providerVerified Show whether the provider has been verified
String npi NPI number of the individual.

IDPersonInfoDetail ( extends IDPerson )

Parameter Description
String value
String description
boolean completed
Top

VerifyIndividualHealthcareRequestType

Parameter Description
IDPersonMeta personMeta
String npi NPI number of the individual.
String dea
String medicalCredentials
Top

IDPersonMeta

Parameter Description
String firstName First Name Required
String lastName Last Name Required
String ssn4 Last four digits of SSN Required
String dob Date of birth in format: YYYY-MM-DD (ex: 1900-01-31) Required
Top

IDPerson ( extends IDPersonMeta )

Parameter Description
String ssn Social security number in 9 digits format. Required
String prefixName Prefix of name
String suffixName Suffix of name
String mobilePhone Mobile phone number. Multi-fact authentication one time password will be sent to the mobile phone via SMS Text. Required
String workPhone Work phone number.
String email Email address. Required
String street1 Street (line 1) of home address. Required
String street2 Street (line 2) of home address.
String city City of home address. Required
String state State of home address in two-character format (ex: NJ). Required
String country Country of home address in two-character format (ex: US). Required
String zip5 Zipcode of home address in five-character format (ex: 07024). Required
Top

AuthenticationRequestType

Parameter Description
String username Reseller or TUser username Required
String password Reseller or TUser password Required
Top

VerifyPersonRequestType

Parameter Description
IDPerson person The individual to be LoA3 authenticated. Required
Top

VerifyOTPRequestType

Parameter Description
IDPersonMeta personMeta First name, last name, last four digits of SSN and date of birth of the individual.
The information will be used to match a verified individual. 		Required
String otp The one time password. Required
Top

VerifyCreditCardType

Parameter Description
IDPersonMeta person First name, last name, last four digits of SSN and date of birth of the individual.
The information will be used to match a verified individual. 		Required
IDCreditCard creditCard Credit card information. Required
Top

IDCreditCard

Parameter Description
String cardNumber Card number
For testing purpose, users can use:
  • 4111 1111 1111 1111 to test valid credit card
  • 4999 9999 9999 9990 to test invalid card number
  • 4999 9999 9999 9991 to test invalid exp date
  • 4999 9999 9999 9992 to test invalid cvv code or address
 Required
String cvv CVV code. Required
String expireYear Expiration date year (YYYY). Required
String expireMonth Expiration date month (MM). Required
Top