OneSpan Sign Developer: Custom Fields – Part 2

“Custom Fields” is a powerful feature when defining additional binding fields for your senders and referencing them when designing transactions. These custom fields typically store fixed information which is uploaded by the sender once and referenced in multiple locations. This avoids forcing the sender to manually input the information each time when signing.

In the previous blog, we reviewed how to define a Custom Field and input values from each sender’s view from the UI portal. We will pick up right from there and discuss how you can leverage the SDK functions or the APIs to integrate with this feature. Let’s get started! 

Define Custom Fields

Besides creating custom fields straight from the UI, OneSpan Sign also exposes the API allowing you to create, edit, query, and delete the custom field definitions.

Explore our “Custom Fields” guide for detailed instructions and sample codes for both REST API and SDK approaches.

Update Sender Custom Field Values

In case you want to provide your own user interface to collect these custom field values or the values are loaded from database, you can utilize the sender update API and insert these values programmatically. 

Let’s check the “Sender” schema first. The custom fields are hosted at the “userCustomFields” node with the required fields of “id” and “value”. So you would organize your API requests as such: 

HTTP Request

POST /api/account/senders/{senderID}

HTTP Headers

Accept: application/json

Request Payload

{
  "userCustomFields": [
    {
      "id": "agent_number_id",
      "value": "sender's value of agent number"
    },
    {
      "id": "policy_number_id",
      "value": "sender's value of policy number"
    }
  ]
}

Retrieve Sender Custom Field Values

To pull the values programmatically, invoke a GET request and step through the “userCustomFields” node of the response entity.

HTTP Request

GET /api/account/senders/{senderID}

HTTP Headers

Accept: application/json

Response Payload

{
  "company": "OneSpan",
  "timezoneId": "America/Detroit",
  "email": "[email protected]",
  "firstName": "Duo",
  "lastName": "Liang",
  "language": "en",
  "userCustomFields": [
    {
      "id": "agent_number_id",
      "data": null,
      "translations": [
        {
          "description": "",
          "language": "en",
          "id": "",
          "data": null,
          "name": "Agent Number"
        }
      ],
      "value": "sender's value of agent number",
      "name": ""
    },
    {
      "id": "policy_number_id",
      "data": null,
      "translations": [
        {
          "description": "",
          "language": "en",
          "id": "",
          "data": null,
          "name": "Policy Number"
        }
      ],
      "value": "sender's value of policy number",
      "name": ""
    }
  ],
  ……
}

Below sample code could be useful if you are developing with .NET:

        public IDictionary<string,string> GetSenderCustomFieldValue(string api_key, string api_url, string senderId) {
            HttpClient myClient = new HttpClient();
            myClient.DefaultRequestHeaders.Add("Authorization", "Basic " + api_key);
            myClient.DefaultRequestHeaders.Add("Accept", "application/json");

            var senderResponse = myClient.GetAsync(new Uri(api_url + "/account/senders/" + senderId)).Result;

            if (!senderResponse.IsSuccessStatusCode) {
                throw new Exception(senderResponse.Content.ReadAsStringAsync().Result);
            }

            IDictionary<string, string> result = new Dictionary<string, string>();
            JObject senderJSON = JObject.Parse(senderResponse.Content.ReadAsStringAsync().Result);
            JArray userCustomFields = (JArray) senderJSON["userCustomFields"];

            foreach (var item in userCustomFields) {
                string id = (string) item["id"];
                string value = (string)item["value"];
                result.Add(id, value);
            }
      
            return result;
        }

Features Accompanying Custom Fields

If you want to seal the custom field values to the signature certificate or add the values to the audit trails, a feasible solution is to use the Session Fields feature. This allows you to store extra data in the evidence summary when creating a signing session. 

There it is. Above sections should be enough to integrate with the custom field feature. If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today