White Label API

Overview

The White Label API service provides you with much more flexibility over the White Label Embed service, with the goal being that your visitors have no idea that your website or application is not providing the service. However, it requires coding skills, and it requires you to have your own database of customers.

Our White Label API is a stripped-down version of our legal document creation services. All surrounding logos, graphics, navigation buttons and links that take the user away from each service have been removed.

This allows you to embed our legal document creation services within your own branded website or application, making it appear as if these services are being provided by you.

Furthermore, you set your own pricing for all of these legal document creation services, and handle all payments from your customers yourself. (This is in contrast to the White Label Embed service, where we set the pricing, handle all payments, and all you can do is provide an optional discount to your customers and obtain a commission.)

Here's how it works:

• You either allow users to register on your website, or you have existing users in your database. The important thing is that you already know their: First Name, Last Name, Email Address, and Country.
• The user clicks on a link or button within your website or application, with the intention of accessing a specific legal document creation service, such as "mywill" (Last Will and Testament), "mypowerofattorney" (Power Of Attorney), etc..
• If this is the first time this user is accessing any of the services, then you must send a create_user API command to create a new user account in our database.
• If this is not a new user, then you should send a validate_login API command to check if any errors will be encountered if you try to login this user. This allows you to deal with any potential errors within your own code, instead of having the user see an error message on our website.
• An embedded frame or web browser is launched by you, which sends a login API command and takes the user to the following URL using POST: https://legalwills.services/whitelabel.
• The user is presented with a menu of options associated with the specific legal document creation service they wanted to access. This is provided by our website, and does not require any coding by you.
• The user can create, modify, view, download, and delete the specific legal document. This is provided by our website, and does not require any coding by you.
• If the legal document creation service being accessed has not been paid for, then the user can still create/modify the entire document, but they can only view/download the first page of the document. This is provided by our website, and does not require any coding by you.
• You might want to implement some way for the user to close or navigate away from the embedded frame/browser and get back to your website or application. It is up to you to figure out what works best for your solution.
• You must provide a way for the user to pay for one or more of the legal document creation services. This could be as simple as a PayPal "Buy Now" button. You set your own prices and take your own payments from users.
• When the user pays for specific legal document creation services, you send a modify_user API command to enable these services within their account. Note that this can also be done within the create_user API command.

In order to use the White Label API, you must store certain user information within your own database and provide a front end implementation for accessing our legal document creation services.

• At minimum, you must store each user's UserID and Password for accessing our services. These values are required in order to use the login API command. In practice, you will probably also want to store their First Name, Last Name, Email Address, and Country. These values are required in order to use the create_user API command to create a new user account in our database.
• Since the White Label API only allows the user to access a specific service at a time, the user cannot navigate to any kind of an "account status" page on our website. As a result, we recommend that you take it upon yourself to indicate to each user what services they have enabled, their current membership length, etc. This requires you to keep track of these items in your own database.
• If you are allowing your users to access more than one of our legal document creation services, then you should also provide some kind of menu or list of services from which your user can select which service to access. When they select a service, that is where our White Label API takes over.

Since the whole point of this API is that the user has no idea that they are being handled by the LegalWills.co.uk website, you must handle all payments and emails/communication with the users of these legal document creation services.

Customer support for these services can be handled by the LegalWills.co.uk support team, but you may want to remain as the primary contact, sending any such support requests to us for handling as required. Furthermore, your users must agree to the LegalWills.co.uk Terms of Use (which you could simply embed within your own Terms of Use) before accessing our services. The details of these arrangements are specified in your services agreement.

Using links provided below, you can obtain a list of all users that you have created, indicating the associated legal document creation services that you have enabled within their accounts and the length of their memberships. You are responsible for providing payment to PartingWishes Inc. for all such enabled services and membership lengths, as outlined in your services agreement contract.

Sample VB.NET Code

Sending data using POST and reading the response data can be done in any popular coding language. Below is some sample VB.NET code for achieving this purpose. When sending the POST, remember to URL-encode each value in the name-value pairs.

Dim strNVP As String = "CMD=create_user" + _
    "&AFFILIATE_ID=123456789" + _
    "&AFFILIATE_SIGNATURE=Z9SFMNM5V9BYTWPRBOJK" + _
    "&USERID=" + Server.UrlEncode("janedoe") + _
    "&PASSWORD=" + Server.UrlEncode("abc123") + _
    "&FIRST_NAME=" + Server.UrlEncode("Jane") + _
    "&LAST_NAME=" + Server.UrlEncode("Doe") + _
    "&EMAIL=" + Server.UrlEncode("[email protected]") + _
    "&COUNTRY=" + Server.UrlEncode("Canada") + _
    "&ADDRESS_LINE1=" + Server.UrlEncode("123 Main Street") + _
    "&ADDRESS_LINE2=" + Server.UrlEncode("Suite 400") + _
    "&CITY=" + Server.UrlEncode("Toronto") + _
    "&STATEPROV=" + Server.UrlEncode("Ontario") + _
    "&POSTALCODE=" + Server.UrlEncode("M5P 3X9") + _
    "&GENDER=" + Server.UrlEncode("F") + _
    "&MYWILL=" + Server.UrlEncode("Y") + _
    "&MEM_YEARS=" + Server.UrlEncode("5") + _
    "&TEST_USER=" + Server.UrlEncode("Y")

'Create web request and web response objects
Dim hwrWebRequest As System.Net.HttpWebRequest = DirectCast(System.Net.WebRequest.Create("https://legalwills.services/whitelabel"), System.Net.HttpWebRequest)
hwrWebRequest.Method = "POST"
hwrWebRequest.ContentType = "application/x-www-form-urlencoded"
Dim requestWriter As New System.IO.StreamWriter(hwrWebRequest.GetRequestStream())

'Send the web request
requestWriter.Write(strNVP)
requestWriter.Close()

'Get the response
Dim hwrWebResponse As System.Net.HttpWebResponse = DirectCast(hwrWebRequest.GetResponse(), System.Net.HttpWebResponse)
Dim responseReader As New System.IO.StreamReader(hwrWebRequest.GetResponse().GetResponseStream())

'Read the response
Dim strResponseData As String = responseReader.ReadToEnd()
responseReader.Close()
hwrWebResponse.Close()

'URL-decode the response
Dim strResultCode As String = Server.UrlDecode(strResponseData)

'Handle any errors
If strResultCode <> "OK" Then
    ...
End If

Sample HTML Code

To allow a user to access the White Label version of a particular legal document creation service, simply send your user to https://legalwills.services/whitelabel using POST, and specify the login API command. To avoid exposing our https://legalwills.services/whitelabel URL to your visitors, we recommend that the POST be sent to an embedded iframe on your website, instead of to a new web browser window.

<form id="form1" action="https://legalwills.services/whitelabel" method="POST" target="iframe1">
        <input type="hidden" name="CMD" value="login" />
        <input type="hidden" name="AFFILIATE_ID" value="123456789" />
        <input type="hidden" name="USERID" value="9BHpRteLnjHl4KikmJwvVfPPZeOy1vSc3yauTjJT_3Edk5jT8CYQxZF3BxaZuuerxvzmYxZa5aDVaWM2DuU_7ayJoVGtswf7_VfvvG2XqO41" />
        <input type="hidden" name="PASSWORD" value="ARVC2MS_roiFasiiZNQZQMWwrcrN9jMje9GpjLpPWwAtHgoLVy7mz9Dtfjos48QiY8lAokUWeuvAQZuyicxpQf09dvlWxp58imKx4gZUCns1" />
        <input type="hidden" name="SERVICE_NAME" value="mywill" />
</form>

<iframe name="iframe1" id="iframe1" src="https://legalwills.services/whitelabel" width="100%" height="1000"></iframe>

<script type="text/javascript">
    document.forms['form1'].submit();
</script>

Demo Website

We have created a fully functional website that uses the White Label API to provide online estate planning services: FinalWills.com. Feel free to try it out!

We are even providing you with the full source code for this demo website. This allows you to examine all aspects of the code, should you have any questions about how to make use of the White Label API. Be sure to read the README.txt file for important information about understanding the code.

Download FinalWills.com Source Code

This demo website is implemented using ASP.NET Web Forms and VB.NET. It is for demonstration purposes only, showing how easy it is to make use of the White Label API within an existing website. Of course, this source code can be modified by you to use any web server technology and programming language.

Adding the "Online Estate Planning" section (which uses the White Label API) to this existing website took 1 developer less than 2 weeks of effort.

API Reference

The https://legalwills.services/whitelabel URL accepts the below name-value pairs in the POST. If any name-value pairs are sent that are not part of the API command, they will simply be ignored. All values should be URL-encoded so that any special characters are transmitted properly. An HTTP form is automatically URL-encoded by most browsers.

create_user - Create a new user account

modify_user - Modify an existing user account

query_if_expired - Check if an account has expired

query_mywill - Return status of MyWill document for a given user

Instead of a single Result Code, the query_mywill API command returns a JSON object in the following format:

{
    "ResultCode": "OK",
    "UserID": "janedoe",
    "MyWillEnabled": true,
    "MyWillStarted": true,
    "MyWillComplete": false,
    "MyWillNumDownloads": 2,
    "MyWillLastUpdated": "2022-03-16T09:30:28",
    "MyWillFirstDownloaded": "2022-03-17T14:21:04",
    "MyWillLastDownloaded": "2022-03-17T23:15:55"
}

ResultCode (string) - The returned ResultCode could be any of the codes in the "Result Codes" table below. "OK" indicates no errors.
UserID (string) - The USERID that was provided for this CMD.
MyWillEnabled (boolean) - Whether or not the MyWill service has been enabled for the given USERID.
MyWillStarted (boolean) - Whether or not this user has started to create a MyWill document. If they delete the document this goes back to 'false'.
MyWillComplete (boolean) - Whether or not all of the required questions have been answered for this user's MyWill document.
MyWillNumDownloads (integer) - Number of times the user has downloaded their MyWill document.
MyWillLastUpdated (datetime) - Date and time that the current MyWill document was last updated by the user, in Central Standard Time zone.
MyWillFirstDownloaded (datetime) - Date and time that the MyWill document was first downloaded by the user, in Central Standard Time zone.
MyWillLastDownloaded (datetime) - Date and time that the MyWill document was last downloaded by the user, in Central Standard Time zone.

encrypt - Encrypt a sensitive value if required by the API

The encrypt API command does not return a Result Code. It returns the encrypted string. If an error occurred, then an empty string is returned. Note that the encrypted value must be used right away, since it expires and becomes invalid within 60 seconds.

validate_login - Check if the given values will result in a login error

When sending a user to the White Label API URL with a login API command, if there is an error with any of the values given, then the error will be displayed on the page instead of granting access to the given user. It is recommended that you send a validate_login API command first, to verify that there are no errors, before sending the user to the White Label API URL with a login command. This allows you to deal with any potential errors within your own code, instead of having the user see an error message on our website.

login - Log in a user

When sending a user to the White Label API URL with a login API command, if there is an error with any of the values given, then the error will be displayed on the page instead of granting access to the given user. It is recommended that you send a validate_login API command first, to verify that there are no errors, before sending the user to the White Label API URL with a login command. This allows you to deal with any potential errors within your own code, instead of having the user see an error message on our website.

The login API command does not return a Result Code. It displays a User Interface for the selected legal document creation service.

logout - Logout the current user

The logout API command should be sent to the same window (e.g. iframe) as was used for the login API command.

Result Codes

The following list shows the possible Result Codes that can be returned by the White Label API.