Custom Web Form Fields

    List Custom Web Form Fields

    Lists all custom webform fields from the specified webform.

    Note: This operation does not support: pagination, filtering, or sorting parameters.

    Request

    • Method: GET
    • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
      • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
    • Path: /api/v1/admin/sites/[site_ID]/webforms/[webform_ID]/fields/custom
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Response

    An object with the following properties:

    • links - a collection of links (array)
      • self - the API URL that will return this result (string)
      • previous - the API URL that will return the previous page of results, if any (string)
      • next - the API URL that will return the next page of results, if any (string)
    • items - an array of Web Form objects with the following properties (array)
      • links - a collection of links (array)
        • self - the API URL that will return full details for this web form (string)
      • id - the ID of the web form field (integer)
      • name - the name of the web form field (string)
      • type - an object of the field's type
        • id - the ID of the web form field type (integer)
        • name - the name of the web form field type (string)
      • mandatory - if the web form is mandatory set this to true (bool)
      • order - the order of the field in the web form (integer)

    Accepts and returns JSON or XML as Content-Type.


    Sample request

    GET /api/v1/admin/sites/1767665/webforms/29382/fields/custom
    Authorization: 7e04176165cd4df7b628cc8ad022a8becf3bb84de44d480aadfae75e4fa07b56
    Content-Type: application/json

    Sample response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "links": [{
            "rel": "self",
            "uri": "https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/1767665\/webforms\/29382\/fields\/custom"
        }, {
            "rel": "previous",
            "uri": null
        }, {
            "rel": "next",
            "uri": null
        }],
        "items": [{
            "links": [{
                "rel": "self",
                "uri": "https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/1767665\/webforms\/29382\/fields\/custom\/131102"
            }],
            "id": 131102,
            "name": "Updated New Field",
            "type": {
                "id": 2,
                "name": "Number"
            },
            "mandatory": true,
            "order": 2
        }, {
            "links": [{
                "rel": "self",
                "uri": "https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/1767665\/webforms\/29382\/fields\/custom\/131101"
            }],
            "id": 131101,
            "name": "Test New Field",
            "type": {
                "id": 2,
                "name": "Number"
            },
            "mandatory": true,
            "order": 8
        }],
        "totalItemsCount": 2,
        "itemsPerPageCount": 1000,
        "currentPage": 1
    }

    Sample code

    var request = $.ajax({
        url: "/api/v1/admin/sites/1767665/webforms/29382/fields/custom",
        type: "GET",
        headers: {
            "Authorization": $.cookie('access_token')
        },
        contentType: "application/json"
    });
    request.done(function (msg) {
        console.log('Request successful, response is: ')
        console.log(msg);
    })
    request.fail(function (jqXHR) {
        console.log("Request failed. Error code: " + jqXHR.status);
    })

    Get Custom Web Form Field Details

    Gets the details of a custom webform field, specified by id

    Note: This operation does not support: pagination, filtering, or sorting parameters.

    Request

    • Method: GET
    • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
      • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
    • Path: /api/v1/admin/sites/[site_ID]/webforms/[webform_ID]/fields/custom/[field_ID]
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Response

    An object with the following properties:

    • links - a collection of links (array)
      • self - the API URL that will return full details for this web form (string)
    • id - the ID of the web form field (integer)
    • name - the name of the web form field (string)
    • type - an object of the field's type
      • id - the ID of the web form field type (integer)
      • name - the name of the web form field type (string)
    • mandatory - if the web form is mandatory set this to true (bool)
    • order - the order of the field in the web form (integer)

    Accepts and returns JSON or XML as Content-Type.


    Sample request

    GET /api/v1/admin/sites/1767665/webforms/29382/fields/custom/131102
    Authorization: 7e04176165cd4df7b628cc8ad022a8becf3bb84de44d480aadfae75e4fa07b56
    Content-Type: application/json

    Sample response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "links": [{         
            "rel": "self",          
            "uri": "https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/1767665\/webforms\/29382\/fields\/custom\/131102"     
        }],
        "id": 131102,
        "name": "Updated New Field",
        "type": {         
            "id": 2,          
            "name": "Number"     
        },
        "mandatory": true,
        "order": 2,
        "optionItems": null
    }
    

    Sample code

    var request = $.ajax({
        url: "/api/v1/admin/sites/current/webforms/1767665/webforms/10090/fields/system/-400",
        type: "GET",
        headers: {
            "Authorization": $.cookie('access_token')
        },
        contentType: "application/json"
    });
    request.done(function (msg) {
        console.log('Request successful, response is: ')
        console.log(msg);
    })
    request.fail(function (jqXHR) {
        console.log("Request failed. Error code: " + jqXHR.status);
    })

    Create Custom Field in Web Form

    Creates a new custom field.

    Note: This operation does not support: pagination, filtering, or sorting parameters.

    Request

    • Method: POST
    • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
      • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
    • Path: /api/v1/admin/sites/[site_ID]/webforms/[webform_ID]/fields/custom
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Parameters

    • name - display name of the web form field (string)
    • type - an object of the field's type
      • id - the ID of the web form field type (integer)
    • mandatory - if the web form is mandatory set this to true (bool)
    • order - the order of the field in the web form (integer)
    • optionItems - for field types that support items, otherwise is null
      • item.value - the value and text of the item that will be displayed on the field
      • item.selected - if the value is selected or checked by default for the field

    Field that support items

    Field types:

    { "id": 5, "name": "Category_DropDown" },
    { "id": 6, "name": "Category_CheckBox" },
    { "id": 7, "name": "Category_Radio" },
    { "id": 10, "name": "Category_ListBox" }
    

    Response

    Accepts JSON or XML as Content-Type.

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "links":[
        {
          "rel":"self",
          "uri":"https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/1767665\/webforms\/32480\/fields\/custom\/132319"
        }
      ],
      "id":132319
    }

    Sample request

    POST /api/v1/admin/sites/current/webforms
    Authorization: 7e04176165cd4df7b628cc8ad022a8becf3bb84de44d480aadfae75e4fa07b56
    Content-Type: application/json
    

    Sample code

    var request = $.ajax({
        url: "/api/v1/admin/sites/1767665/webforms/10090/fields/custom",
        type: "POST",
        headers: {
            "Authorization": $.cookie('access_token')
        },
        contentType: "application/json",
    	"processData": false,
        data: JSON.stringify({
          "name":"Test List Field",
          "type":{
            "id":10
          },
          "mandatory":true,
          "order":6,
          "optionItems":[
            {
              "value":"item1",
              "selected":false
            },
            {
              "value":"item2",
              "selected":true
            },
            {
              "value":"item3",
              "selected":false
            }
          ]
        })
    });
    request.done(function (msg) {
        console.log('Request successful, response is: ')
        console.log(msg);
    })
    request.fail(function (jqXHR) {
        console.log("Request failed. Error code: " + jqXHR.status);
    })

    Update Custom Web Form Field

    Updates an existing custom field.

    Request

    • Method: PUT
    • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
      • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
    • Path: /api/v1/admin/sites/[site_ID]/webforms/[webform_ID]/fields/custom/[field_ID]
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Parameters

    • name - display name of the web form field (string)
    • type - an object of the field's type
      • id - the ID of the web form field type (integer)
    • mandatory - if the web form is mandatory set this to true (bool)
    • order - the order of the field in the web form (integer)
    • optionItems - for field types that support items, otherwise is null
      • item.value - the value and text of the item that will be displayed on the field
      • item.selected - if the value is selected or checked by default for the field

    Field that support items

    Field types:

    { "id": 5, "name": "Category_DropDown" },
    { "id": 6, "name": "Category_CheckBox" },
    { "id": 7, "name": "Category_Radio" },
    { "id": 10, "name": "Category_ListBox" }

    WARNING: When editing a custom field that has option items, and you update the field without the including the items in the request, the old items will be removed.
    E.g You have a field that has item1 and item2 in a ListBox and you want to change the type of the field to something else. You need to send the item1 and item2 data again in addition to the changed type.id

    Response

    Returns an empty body if successful or a detailed error message.

    Accepts JSON or XML as Content-Type.

    HTTP/1.1 200 OK
    Content-Length: 0

    Sample request

    var access_token = BCAPI.Helper.Site.getAccessToken();
    
    var request = $.ajax({
        url: "/api/v1/admin/sites/1767665/webforms/10090/fields/custom/323505",
        type: "PUT",
        connection: "keep-alive",    
        contentType: "application/json",headers: {
            "Authorization": $.cookie('access_token')
        },   
        processData: false,
        data: JSON.stringify({
          "name":"Updated List Field",
          "type":{
            "id":8
          },
          "mandatory":false,
          "order":6,
          "optionItems":[
            {
              "value":"updated item1",
              "selected":true
            },
            {
              "value":"updated item2",
              "selected":false
            },
            {
              "value":"updated item3",
              "selected":false
            }
          ]
        })
    });
    request.done(function (msg) {
        console.log(msg);
    });
    request.fail(function (jqXHR) {
        console.log("Request failed.");
        console.log("Error code: " + jqXHR.status);
        console.log("Error text: " + jqXHR.statusText);
        console.log("Response text: " + jqXHR.responseText);
    });
        

    Delete Custom Web Form Field

    Delete custom field from the web form.

    Request

    • Method: DELETE
    • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
      • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
    • Path: /api/v1/admin/sites/[site_ID]/webforms/[webform_ID]/fields/custom/[field_ID]
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json
    DELETE /api/v1/admin/sites/1767665/webforms/10851/fields/custom/323505 HTTPS/1.1
    Content-Type: application/json; charset=utf-8

    Response

    Returns an empty body if successful or a detailed error message.

    HTTP/1.1 200 OK
    Content-Length: 0

    Sample request

    var access_token = BCAPI.Helper.Site.getAccessToken();
    
    var request = $.ajax({
        url: "/api/v1/admin/sites/1767665/webforms/10090/fields/custom/323505",
        type: "DELETE",
        connection: "keep-alive",    
        contentType: "application/json",headers: {
            "Authorization": $.cookie('access_token')
        }
    });
    request.done(function (msg) {
        console.log(msg);
    });
    request.fail(function (jqXHR) {
        console.log("Request failed.");
        console.log("Error code: " + jqXHR.status);
        console.log("Error text: " + jqXHR.statusText);
        console.log("Response text: " + jqXHR.responseText);
    });