Organization Registration v3.0

SOAP Service for provisioning, adding MaxMD Direct Hosted addresses for provider. This page includes description about service actions and data types.

MTOM is required by the SOAP server. Click here to access the WSDL

Organization Registration Service Functions

On-board instruction

To onboard a Direct organization through the Registration API, the Organization and each staff must be verified through MaxMD ID Proofing (Verification) API or ID Proofing (Verification) web-based workflow. The ID Proofing (Verification) API document can be found at: SOAP or REST. If you are interested in MaxMD ID Proofing (Verification) web-based workflow, please contact MaxMD support support@max.md

When an organization is verified, a unique numeric identifier “certified_id” will be assigned to the organization. When a staff (individual) is verified, a unique numeric identifier “idp_id” will be assigned to the ID Proofed individual. These Ids (certified_id and idp_id) are required when provision the Direct domain and Direct address for the organization and the individual.

To create Direct domain and certificate for a verified organization, call function: ProvisionCertifiedProvider . If the client is using MaxMD SMTP Hosted accounts, post the following information to the API, otherwise please contact MaxMD support support@max.md to get your specified settings and instruction.
  • sessionId (use Login function to authenticate and get a session Id in response)
  • DirectDomain (the Direct domain name)
  • DirectOfferType (Offer type based on the number of employees)
  • form:
    • organization: provide certified_id (or provide name, taxid and state)
    • organizationType: certificate type (CoveredEntity, BusinessAssociate or HealthEntity)
    • directAddresses: Direct addresses. In each Direct address object:
      • idp_id (ID Proofed Individual unique Id)
      • username: username of the Direct address
      • password: password of the Direct address
      • userType: SMTP
To add additional Direct address to an existing Direct Domain (organization), call function: AddDirectAddressesToCertifiedProvider. If the client is using MaxMD SMTP Hosted accounts, post the following information to the API, otherwise please contact MaxMD support support@max.md to get your specified settings and instruction.
  • sessionId (use Login function to authenticate and get a session Id in response)
  • DirectDomain (the Direct domain name)
  • form:
    • directAddresses: additional Direct addresses. In each Direct address object:
      • idp_id (ID Proofed Individual unique Id)
      • username: username of the Direct address
      • password: password of the Direct address
      • userType: SMTP
To add additional Authorized Users to an existing Direct Domain (organization), call function: AddAuthorizedUsersToCertifiedProvider
  • sessionId (use Login function to authenticate and get a session Id in response)
  • DirectDomain (the Direct domain name)
  • form:
    • authorizedUsers: authorized users. In each authorized user object:
      • idp_id (ID Proofed Individual unique Id)
To reset password of existing Direct address, call function: UpdateDirectAddressPassword.
  • sessionId (use Login function to authenticate and get a session Id in response)
  • DirectDomain (the Direct domain name)
  • form:
    • directAddresses: Direct addresses to be updated. In each Direct address object:
      • username: username of the Direct address
      • password: password of the Direct address

To get your created Direct Domains (organizations), call function: ListProvisionedOrganizations

To get information (authorized users, Direct address etc) about an existing Direct Domain (organization), call function: CheckProvisionedOrganizationWithOtherInfo

API Functions

LoginResponseType Login (String username, String password)

Login using your Reseller or T-User username and password, and received a new sessionId in response. Each sessionId will expire in 10 minutes.

SubmitDirectFormResponseType ProvisionCertifiedProvider (String sessionId, String DirectDomain, String DirectOfferType, CertifiedDirectForm form)

Provision a certified organization with specified offer type. Below are all valid offer types:

  • CDO1 - Direct Secure Messaging: Hosted mdEmail® for 1 Clinical Staff Employee
  • CDO2 - Direct Secure Messaging: Hosted mdEmail® for 2 Clinical Staff Employees
  • CDO3 - Direct Secure Messaging: Hosted mdEmail® for 3 Clinical Staff Employees
  • CDO4 - Direct Secure Messaging: Hosted mdEmail® for 4 Clinical Staff Employees
  • CDO5 - Direct Secure Messaging: Hosted mdEmail® for 5 Clinical Staff Employees
  • CDO6 - Direct Secure Messaging: Hosted mdEmail® for 6 Clinical Staff Employees
  • CDO7 - Direct Secure Messaging: Hosted mdEmail® for 7 Clinical Staff Employees
  • CDO8 - Direct Secure Messaging: Hosted mdEmail® for 8 Clinical Staff Employees
  • CDO9 - Direct Secure Messaging: Hosted mdEmail® for 9 Clinical Staff Employees
  • CDO10 - Direct Secure Messaging: Hosted mdEmail® for 10 Clinical Staff Employees
  • CDO15 - Direct Secure Messaging: Hosted mdEmail® for 11-15 Clinical Staff Employees
  • CDO20 - Direct Secure Messaging: Hosted mdEmail® for 16-20 Clinical Staff Employees
  • CDO30 - Direct Secure Messaging: Hosted mdEmail® for 21-30 Clinical Staff Employees
  • CDO40 - Direct Secure Messaging: Hosted mdEmail® for 31-40 Clinical Staff Employees
  • CDO50 - Direct Secure Messaging: Hosted mdEmail® for 41-50 Clinical Staff Employees
  • CDO75 - Direct Secure Messaging: Hosted mdEmail® for 51-75 Clinical Staff Employees
  • CDO100 - Direct Secure Messaging: Hosted mdEmail® for 76-100 Clinical Staff Employees
  • CDO150 - Direct Secure Messaging: Hosted mdEmail® for 101-150 Clinical Staff Employees
  • CDO300 - Direct Secure Messaging: Hosted mdEmail® for 151-300/51-101 Clinical Staff Employees/Beds
  • CDO450 - Direct Secure Messaging: Hosted mdEmail® for 301-450/101-150 Clinical Staff Employees/Beds
  • CDO600 - Direct Secure Messaging: Hosted mdEmail® for 451-600/151-200 Clinical Staff Employees/Beds
  • CDO750 - Direct Secure Messaging: Hosted mdEmail® for 601-750/201-250 Clinical Staff Employees/Beds
  • CDONLP1 - Direct Secure Messaging: Hosted mdEmail® with NLP for 1 Clinical Staff Employee
  • CDONLP2 - Direct Secure Messaging: Hosted mdEmail® with NLP for 2 Clinical Staff Employees
  • CDONLP3 - Direct Secure Messaging: Hosted mdEmail® with NLP for 3 Clinical Staff Employees
  • CDONLP4 - Direct Secure Messaging: Hosted mdEmail® with NLP for 4 Clinical Staff Employees
  • CDONLP5 - Direct Secure Messaging: Hosted mdEmail® with NLP for 5 Clinical Staff Employees
  • CDONLP6 - Direct Secure Messaging: Hosted mdEmail® with NLP for 6 Clinical Staff Employees
  • CDONLP7 - Direct Secure Messaging: Hosted mdEmail® with NLP for 7 Clinical Staff Employees
  • CDONLP8 - Direct Secure Messaging: Hosted mdEmail® with NLP for 8 Clinical Staff Employees
  • CDONLP9 - Direct Secure Messaging: Hosted mdEmail® with NLP for 9 Clinical Staff Employees
  • CDONLP10 - Direct Secure Messaging: Hosted mdEmail® with NLP for 10 Clinical Staff Employees
  • CDONLP15 - Direct Secure Messaging: Hosted mdEmail® with NLP for 11-15 Clinical Staff Employees
  • CDONLP20 - Direct Secure Messaging: Hosted mdEmail® with NLP for 16-20 Clinical Staff Employees
  • CDONLP30 - Direct Secure Messaging: Hosted mdEmail® with NLP for 21-30 Clinical Staff Employees
  • CDONLP40 - Direct Secure Messaging: Hosted mdEmail® with NLP for 31-40 Clinical Staff Employees
  • CDONLP50 - Direct Secure Messaging: Hosted mdEmail® with NLP for 41-50 Clinical Staff Employees
  • CDONLP75 - Direct Secure Messaging: Hosted mdEmail® with NLP for 51-75 Clinical Staff Employees
  • CDONLP100 - Direct Secure Messaging: Hosted mdEmail® with NLP for 76-100 Clinical Staff Employees
  • CDONLP150 - Direct Secure Messaging: Hosted mdEmail® with NLP for 101-150 Clinical Staff Employees
  • CDONLP300 - Direct Secure Messaging: Hosted mdEmail® with NLP for 151-300/51-100 Clinical Staff Employee/Beds
  • CDONLP450 - Direct Secure Messaging: Hosted mdEmail® with NLP for 301-450/101-150 Clinical Staff Employee/Beds
  • CDONLP600 - Direct Secure Messaging: Hosted mdEmail® with NLP for 451-600/151-200 Clinical Staff Employee/Beds
  • CDONLP750 - Direct Secure Messaging: Hosted mdEmail® with NLP for 601-750/201-250 Clinical Staff Employee/Beds

SubmitDirectFormResponseType AddAuthorizedUsersToCertifiedProvider (String sessionId, String DirectDomain, CertifiedDirectForm form)

Register Identity Proofed individuals to a provisioned organization as authorized users.

SubmitDirectFormResponseType AddDirectAddressesToCertifiedProvider (String sessionId, String DirectDomain, CertifiedDirectForm form)

Create Direct addresses to a provisioned organization.

SubmitDirectFormResponseType UpdateDirectAddressPassword (String sessionId, String DirectDomain, CertifiedDirectForm form)

Create Direct addresses to a provisioned organization.

GetProvisionedOrganizationsResponseType ListProvisionedOrganizations (String sessionId, boolean minimumMetadata)

List provisioned organization.

GetProvisionedOrganizationsResponseType CheckProvisionedOrganization (String sessionId, String directDomain,
boolean getAuthorizedUsers, boolean getAddresses boolean getDefaultSettings)

Get information of a provision organization.

GetProvisionedOrganizationsWithOtherInfoResponseType CheckProvisionedOrganizationWithOtherInfo (String sessionId, String directDomain,
boolean getAuthorizedUsers, boolean getAddresses boolean getDefaultSettings)

Get information of a provision organization.

GetMessageStatusReportResponseType GetMonthlyDirectMessageReport (String sessionId, String organizationFqdn,
Date date, boolean getReportAsCsv)

Get Monthly message status report.

GetMessageStatusReportResponseType GetWeeklyDirectMessageReport (String sessionId, String organizationFqdn,
Date date, boolean getReportAsCsv)

Get Weekly message status report.

GetMessageStatusReportResponseType GetDailyDirectMessageReport (String sessionId, String organizationFqdn,
Date date, boolean getReportAsCsv)

Get Daily message status report.

Organization Registration Service Data types

ResellerAPIResponse

Parameter Description
String code Response code:
000 - success
002 - invalid user when provisioning new Direct mdEmail account
003 - registrar offer error
010 - invalid api argument or argument missing
011 - authentication failed
012 - organization missing
013 - organization permission denied
014 - direct user account error
021 - debit account authorize failed
022 - debit account capture failed
099 - other error
201 - Direct domain $domain has been used.
202 - No verified organization record is found $info
203 - The organization is not verified as healthcare provider. $info
204 - Invalid state name $info
205 - Failed to validate ID proofed individuals $info
206 - Invalid organization type $info
207 - Unsupported address type $info
208 - No organization is found for domain($domain).
209 - Direct Organization object is empty $info
210 - Direct addresso ($address) is not found.
999 - other error
Required
Boolean success Required
String errorMessage Error message
Top

LoginResponseType ( extends ResellerAPIResponse )

Parameter Description
String sessionId Session Id which expires in 10 minutes.
Top

UserPassword

Parameter Description
String username Username Required
String password Password Required
Top

SubmitDirectFormResponseType ( extends ResellerAPIResponse )

Parameter Description
PaymentConfirmation paymentConfirmation Payment confirmation.
UpdatedDirectAddressType[ ] updatedAddresses Updated Direct addresses.
UpdatedAuthorizedUserType[ ] updatedAuthorizedUsers Updated authorized users.
Top

GetProvisionedOrganizationsResponseType ( extends ResellerAPIResponse )

Parameter Description
ProvisionedOrganizationDetailType[ ] organizations Provisioned organizations
Top

GetProvisionedOrganizationsWithOtherInfoResponseType ( extends ResellerAPIResponse )

Parameter Description
ProvisionedOrganizationDetailWithOtherInfoType[ ] organizations Provisioned organizations
Top

PaymentConfirmation

Parameter Description
int orderId Order number
float amount Total amount of the order
Date orderTime Order time
Product[ ] products Purchased products
String detail Order details
Top

Product

Parameter Description
String name Product name
String description Product description
int quantity Product quantity
float offerPrice Offer price
float salePrice Calculated sale price. When purchasing Direct addresses, the expire date of the new address will be same as purchased Direct certificate product. The sale price will be offeerPrice * (expireDate - today) / (one year).
float amount Amount = salePrice * quantity
String startDate Product start date
String expireDate Product expire date
Top

UpdatedDirectAddressType ( extends UpdatedItemType )

Parameter Description
String username User part of the Direct address.
Top

UpdatedAuthorizedUserType ( extends UpdatedItemType )

Parameter Description
long idp_id Unique ID of the identity proofed individual record.
Top

UpdatedItemType

Parameter Description
ProvisionStatusType status
  • Provisioned
  • ProvisionFailed
  • Updated
  • UpdateFailed
  • Disabled
  • DisableFailed
  • Deleted
  • DeleteFailed
  • LitigationHoldEnabled
  • EnableLitigationHoldFailed
  • LitigationHoldDisabled
  • DisableLitigationHoldFailed
String message
boolean success Whether the update is successfully completed.
Top

CertifiedDirectForm

Parameter Description
CertifiedOrganization organization Certified organization information
String departmentName departmentName
IDProofedIndividual[ ] administrators Direct administrators.
IDProofedIndividual[ ] authorizedUsers Authorized users.
DirectAddress[ ] directAddresses Direct addresses.
DirectAddressSettingType[ ] organizationDefaultSettings Organization default settings.
CertificateCategoryType organizationType
  • CoveredEntity (For all healthcare providers)
  • BusinessAssociate
  • HealthEntity
Top

CertifiedOrganization

Parameter Description
long certified_id Unique ID of certified organization record. If this parameter is not provided, the other parameters (name, taxid, state) are required.
String name Organization name
String taxid Organization Tax ID
String state State of organization address in two character format (ex: NJ)
Top

IDProofedIndividual

Parameter Description
long idp_id Unique ID of identity proofed individual record. If this parameter is not provided, the other parameters (firstName, lastName, ssn4, dob) are required.
String firstName First name
String lastName Last name
String ssn4 Last four digits of SSN
String dob Date of birth
Top

DirectAddress ( extends IDProofedIndividual )

Parameter Description
String username User part of the Direct address. Username is unique in Direct domain. Required
String password Password of the Direct address. The server will ignore empty password.
DirectUserType userType
  • SMTP
  • XD
  • FTP
  • FTPS
  • SFTP
int endpointId Endpoint ID for XD, FTP/FTPS/SFTP addresses.
String endpointUsername Endpoint access username for FTP/FTPS/SFTP addresses.
String endpointPassword Endpoint access password for FTP/FTPS/SFTP addresses.
String endpointDirectory Default delivery directory FTP/FTPS/SFTP addresses.
DirectAddressSettingType[ ] addressSettings Direct address settings.
Top

DirectAddressSettingType

Parameter Description
String settingName Setting name. Available settings:
  • notify_flag ( true | false ) - Whether send an alert to registered email when an inbound Direct message is delivered or failed to deliver to Mailbox. (Default: true)
  • timely_and_reliable_flag ( true | false ) - Whether request the receiver Security and Trust Agent (STA) to reply "Dispatched" Message Delivery Notification(MDN) or negative Delivery Status Notification (DSN) when sending outbound Direct message. (Default: false)
  • comsume_mdn_flag ( true | false ) - When comsume the Notificatioins (including MDNs and negative DSN). If comsume_mdn_flag is true, MaxMD will still monitor the MDN/DSN to track the outgoing Direct message, but will not deliver it to user. (Default: false)
  • is_private_flag ( true | false ) - When commit the Direct address to DirectTrust national directory. (Default: true)
Any other setting name will be ignored. 		Required
String settingValue Setting value Required
Top

ProvisionedOrganizationDetailType ( extends ProvisionedOrganizationMetadataType )

Parameter Description
String taxid Tax ID
String npi NPI number
String address Address street
String city Address city
String state Address state
String country Address country
String zipcode Address zipcode
OrganizationStatusType organizationStatus Organization status:
  • Registered The organization is registered.
  • CertificatePending The organization registered, the Direct certificate request is submitted, but the certificate is not issued yet.
  • Activated The Direct certificate is signed. The organization is activated.
  • Disabled The Direct Organization is disabled.
  • CertificateExpired The Direct certificate is expired. User will be able to connect to the mailbox, but inbound/outbound messages will be rejected due to the invalid Direct certificate.
  • CertificateRevoked The Direct certificate is revoked. User will be able to connect to the mailbox, but inbound/outbound messages will be rejected due to the invalid Direct certificate.
  • Unknown Error when check organization status..
CertificateCategoryTypecertificateCategory Direct certificate category. Select one of below certificate type:
  • CoveredEntity: Covered Entity (NPI is required). Direct Trust OID: 1.3.6.1.4.1.41179.2.1
  • BusinessAssociate: Business Associate. Direct Trust OID: 1.3.6.1.4.1.41179.2.2
  • HealthEntity: Health Entity. Direct Trust OID: 1.3.6.1.4.1.41179.2.3
 Required
IDProofedIndividual[ ] authorizedUsers Authorized users.
DirectAddress[ ] directAddresses Direct addresses.
DirectAddressSettingType[ ] organizationDefaultSettings Organization default settings.
Top

ProvisionedOrganizationDetailWithOtherInfoType ( extends ProvisionedOrganizationDetailType )

Parameter Description
Map otherInfo otherInfo: Map. Available map keys are:
  • hasTrustedAgent: 0 | 1. Whether the organization has signed trusted agent agreement.
Top

ProvisionedOrganizationMetadataType ( extends ProvisionedOrganizationMiniMetaType )

Parameter Description
String name Organization name
String createdDate Organization provisioned date (in format: YYYY-MM-DD)
int numOfAddresses Number of provisioned Direct addresses
int numOfAuthorizedUsers Number of provisioned authorized users
Top

ProvisionedOrganizationMiniMetaType

Parameter Description
long certified_id Unique ID of certified organization record.
String directDomain Direct domain name
Top

GetMessageStatusReportResponseType

Parameter Description
String code Response code:
000 - success
002 - invalid user when provisioning new Direct mdEmail account
003 - registrar offer error
010 - invalid api argument or argument missing
011 - authentication failed
012 - organization missing
013 - organization permission denied
014 - direct user account error
021 - debit account authorize failed
022 - debit account capture failed
099 - other error
201 - Direct domain $domain has been used.
202 - No verified organization record is found $info
203 - The organization is not verified as healthcare provider. $info
204 - Invalid state name $info
205 - Failed to validate ID proofed individuals $info
206 - Invalid organization type $info
207 - Unsupported address type $info
208 - No organization is found for domain($domain).
209 - Direct Organization object is empty $info
210 - Direct addresso ($address) is not found.
999 - other error
Boolean success
String message Error or Exception messages
Boolean hasCvData true: csvData is responsed, messageLogs is empty
false: messageLogs is responsed, csvData is empty
DataHandler csvData csv formatted message status report data with below columns:
  1. From Sender direct address
  2. To Recipient direct address
  3. Message ID SMTP Message ID of the message
  4. Message Size Size of the message
  5. Status Status of the message
    • Delivered* Delivered to receiver
    • Waiting* Waiting confirmation from receiver HISP
    • Locally Failed* Rejected or failed when sending it out.
    • Remotely Failed* Rejected or failed by receiver HISP
    • NO MDN Received* Timed out. No confirmation received from receiver HISP within one hour
  6. Sent Time Sent time of the message
  7. XDR Message ID XDR Message ID
  8. XDR Source ID XDR Source ID
  9. XDR Unique ID XDR Unique ID
  10. XDR Patient ID XDR Patient ID

This variable is empty if hasCvData==false or no message was found in the certain date range.
DirectMessageLogCollection messageLogs And list of message log object. This variable is empty if hasCvData==true or no message was found in the certain date range.
Top