DokuWiki

This is an old revision of the document!

Web Service: submitterRequest

The submitterRequest web service is used to send a 'new' submitter request to CeRTNA.

As with other CeRTNA web services, you must use the login workflow to obtain a soft-token that can be used when calling the submitterRequest web service.

Click this link (Login Workflow Example) to review the Login workflow.

Your user credentials allow the backend web service to ensure that your user request is properly assigned to your organization.

This web service was updated in the CeRTNA January 2024 APEX update. It was expanded to support properties that indicate whether a MOU or COI or both will be submitted in support of this submitterRequest. Set the property values to true or false to indicate if an MOU or COI or both should be expected to follow via the postDocument request.

Additionally, in order to support follow-up resubmissions for requests that are in Failed or Rejected status, this web service now supports the ability for the end-user to provide a Request ID when calling the submitterRequest web service. If providing the Request ID for a resubmission (corrected issue) the current status must be in Failed or Rejected status for the request to be accepted.

Request Endpoint

Method	URL
POST	https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/submitterRequest

Request Body

This endpoint accepts request parameters using an text/plain format. (They are part of the endpoint URL)

Request Headers

Key	Value
Content-Type	application/json
access_token	{soft-token}

Request Parameters

Parm Name	Req/Opt	Format	Description
RequestID	Required	[string]	Use 0 when for the intial submitterRequest or use a Request ID when re-submitting a corrected submitterRequest. Including instances where an updated MOU or COI will be provided.
SubmitterTypeID	Required	[string]	Must be on of the following numeric codes: 1 (Title Company) 2 (Lender) 8 (Government) 32 (Other)
PrimaryName	Required	[string]	(Max Len: 255) This name must be unique by Submitter Name, City, State. Please provide name in uppercase. Be sure to escape this value for special characters.
Address1	Required	[string]	(Max Len: 100) Street address 1. Be sure to escape this value for special characters.
Address2	Required	[string]	(Max Len: 100) Street address 2. This can be an empty string. Be sure to escape this value for special characters.
City	Required	[string]	(Max Len: 100) City name.
StateName	Required	[string]	Two character state id.
PostalCode	Required	[string]	Zip code. 5 or 9 character.
COIExpirationDate	Required	[string]	If the SubmitterTypeID is 32 (Other) then a COI Expiration Date is required otherwise an empty string can be provided.
UpdateMOU	Required	[string]	Indicates if a MOU will be uploaded with the postDocument call. (true or false.)
UpdateCOI	Required	[string]	Indicates if a COI will be uploaded with the postDocument call. (true or false.)

JSON Response Parameters

Parm Name	Format	Description
result	[string]	If the submitterRequest is successfully created, the RequestID will be returned in the result property of the response. The RequestID is needed when sending along the associateed MOU and/or COI documents for the New Submitter Request.
code	[string]	Exception conditions will result in code/message being returned.
message	[string]	Longer description of exception condition.

As noted, any condition that results in an unsuccessful call to the submitterRequest web service will produce a JSON formatted response with a code and message property populated. Successful calls will result in the RequestID property being returned. The RequestID is a required parameter of the postDocument web service.

Sample Request

Endpoint: (With Parameters)

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/submitterRequest?RequestID=0&SubmitterTypeID=32&PrimaryName=EXAMPLE PRIMARY NAME&Address1=123 EXAMPLE ST.&Address2=&City=EXAMPLE CITY&StateName=CA&PostalCode=12345&COIExpirationDate=12/25/2024

Headers:

Content-Type: application/json (For the login process)

Content-Type: text/plain (For the web service call)

Body:

Body content is not required because the parameters are pass as text/plain content as part of the Endpoint URL.

Sample Response

Status Code: 200

{
    "result": "15"
}

OR

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "SubmitterRequestExists",
        "Message": "12|EXAMPLE PRIMARY NAME|EXAMPLE CITY, CA|EXAMPLE AGENT"
    }
}

Additional Comments

Comments and sample code are provided for reference purposes only and are not intended to show production quality code or all exception handling conditions and/or completed code blocks.

Comment 1:

The submitterRequest web service is the first step in a New Submitter Request workflow as documented in the following C# snippet.

private void btnNewSubmitterRequest_Click(object sender, RoutedEventArgs e)
{
	// New Submtter Request Workflow:
	// Create New Submitter Request - Request ID is retured.
	// Send the MOU PDF document associated with the Request ID.
	// If Submitter Type is 'Other (32) send the COI PDF document associated with the Request ID.
 
	createNewSubmitterRequest(); // If successfull the tbRequestID.Text field will have the new Request ID.
 
	sendPDFFile("MOU");
 
	if (tbSubmitterTypeValue.Text == "32")
	{
		sendPDFFile("COI");
	}
}

Comment 2:

The following C# snippet shows how to login and call the submitterRequest web service. In this example, the parameters that are being supplied to the web service are copied from the fields on WPF form.

private void createNewSubmitterRequest()
{
            string strNewRequestID = "0";
 
            RestClient client = null;
            RestRequest request = null;
            IRestResponse response = null;
 
            string strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/user/login";
 
            // Password has to be hashed.
            // New convention uses a Salt value from the user record
 
            string strSalt = GetSalt(tbUserName.Text);
            string strPassword = tbPassword.Password.ToString();
 
            string strHashedPassword = HashPassword(strPassword, strSalt);
 
            string strParms = "{\n\t\"user_name\" : \"";
            strParms += tbUserName.Text;
            strParms += "\",\n\t\"password\" : \"";
            strParms += strHashedPassword;
            strParms += "\"\n}";
 
            client = new RestClient(strURL);
            request = new RestRequest(Method.POST);
 
            request.AddHeader("Cache-Control", "no-cache");
            request.AddHeader("Content-Type", "application/json");
 
            request.AddParameter("Login", strParms, ParameterType.RequestBody);
            response = client.Execute(request);
 
            if (response.IsSuccessful)  // Successfully logged in and a token has been provided
            {
                var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
                string token = jsonResult1.access_token;
 
                strURL = null;
                client = null;
                request = null;
                response = null;
 
                // Note: Be sure to escape your PrimaryName, Address1, and Address2 values to avoid issues associated with invalid HTML characters appearing in the URL.
 
                strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/submitterRequest";
 
                if (tbRequestID.Text == "" || tbRequestID.Text == " " || tbRequestID.Text == "0")
                {
                    strURL = strURL + "?" + "RequestID=0";
                }
                else
                {
                    strURL = strURL + "?" + "RequestID=" + tbRequestID.Text;
                }
 
                strURL = strURL + "&" + "SubmitterTypeID=" + tbSubmitterTypeValue.Text;
                strURL = strURL + "&" + "PrimaryName=" + Uri.EscapeDataString(tbSubmitterName.Text);
                strURL = strURL + "&" + "Address1=" + Uri.EscapeDataString(tbAddress1.Text);
                strURL = strURL + "&" + "Address2=" + Uri.EscapeDataString(tbAddress2.Text);
                strURL = strURL + "&" + "City=" + tbCity.Text;
                strURL = strURL + "&" + "StateName=" + tbState.Text;
                strURL = strURL + "&" + "PostalCode=" + tbZipCode.Text;
                strURL = strURL + "&" + "COIExpirationDate="+tbCOIExpires.Text;
 
                // The following 2 properties have been added since the original release of the web service
                // If customers using the web service do not include these properties, their service call may not complete.
 
                if (tbSubmitterTypeValue.Text == "32")
                {
                    strURL = strURL + "&" + "UpdateMOU=true";
                    strURL = strURL + "&" + "UpdateCOI=true";
                }
                else
                {
                    strURL = strURL + "&" + "UpdateMOU=true";
                    strURL = strURL + "&" + "UpdateCOI=false";
                }
 
                client = new RestClient(strURL);
                request = new RestRequest(Method.POST);
 
                request.AddHeader("Cache-Control", "no-cache");
                request.AddHeader("access_token", token);
                request.AddHeader("content-type", "text/plain");
                //request.AddHeader("content-type", "application/x-www-form-urlencoded");
                response = client.Execute(request);
 
                if (response.IsSuccessful)
                {
                    var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
 
                    strNewRequestID = jsonResult2.result;
                    tbRequestID.Text = strNewRequestID;
                }
            }
 
            return;
}

Comment 3:

A zip file with a VisualStudio 2019, C#, .NET/WPF project is available for download. The project uses NuGet packages RestSharp (Version 106.15.0) and Newtonsoft.Json (Version 13.0.1). This project will not build with RestSharp versions later than 106 due to changes in the library.

You do not have to build this project, the source code files can just be referenced for how to complete tasks associated with obtaining a soft-token so that the other web services can be called. The soft-token is a requirement on all the CeRTNA web services.

Comment 4:

As per the workflow snippet, CeRTNA expects that the required MOU and/or COI will be submitted as part of the workflow for creating a New Submitter Request. If the MOU and/or COI is not provide, the New Submitter Request will be rejected by CeRTNA staff.