Web Forms

    List Web Forms

    Get a list of web forms which exist on the current site.

    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
      • Alternatively use "current" in place of site_ID for current login token's site
    • 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 for the current site (integer)
      • name - the name of the web form (string)
      • workflowId - the ID of the workflow. Defaults to 0 if "Don't use a workflow" is selected (integer)
      • zoneId - the ID of the secure zone. Defaults to -1 if "Don't subscribe to a Secure Zone" is selected (integer)
      • affiliateId - affiliate program ID. Defaults to -1 if "Don't subscribe to an Affiliate Program" is selected (integer)
      • createOpportunity - true if sales opportunity is used, false is otherwise (bool)
      • opportunityTypeId - opportunity type ID (integer)
      • stageTypeId - opportunity stage ID (integer)
      • probability - default probability (float)
      • amount - the estimated value of this sale opportunity (integer)
      • cycleTypeId - cycle type ID (integer)
        • 0 - createOpportunity is false
        • 3 - In a week
        • 4 - In a fortnight
        • 5 - In a month
        • 6 - In 3 months
        • 7 - In 6 months
        • 8 - In 1 year
      • setWholesale - wholesale subscription enabled (bool)
      • sendAutoresponder - to send or not the autoresponder email to the customer filling out the web form (bool)
      • siteId - site ID (integer)

    Accepts and returns JSON or XML as Content-Type.


    Sample request

    GET /api/v1/admin/sites/current/webforms
    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\/38583\/webforms"
        },
        {
          "rel":"previous",
          "uri":null
        },
        {
          "rel":"next",
          "uri":null
        }
      ],
      "items":[
        {
          "links":[
            {
              "rel":"self",
              "uri":"https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/38583\/webforms\/29161"
            }
          ],
          "id":29161,
          "name":"My Web Form",
          "workflowId":0,
          "zoneId":0,
          "affiliateId":0,
          "createOpportunity":false,
          "opportunityTypeId":null,
          "stageTypeId":null,
          "probability":null,
          "amount":null,
          "cycleTypeId":null,
          "setWholesale":false,
          "sendAutoresponder":false
        },
        {
          "links":[
            {
              "rel":"self",        
    			"uri":"https:\/\/api.worldsecuresystems.com\/api\/v1\/admin\/sites\/38583\/webforms\/29164"
            }
          ],
          "id":29164,
          "name":"permission web form",
          "workflowId":0,
          "zoneId":0,
          "affiliateId":0,
          "createOpportunity":false,
          "opportunityTypeId":null,
          "stageTypeId":null,
          "probability":null,
          "amount":null,
          "cycleTypeId":null,
          "setWholesale":false,
          "sendAutoresponder":false
        }
      ],
      "totalItemsCount":2,
      "itemsPerPageCount":1000,
      "currentPage":1
    }

    Sample code

    var request = $.ajax({
        url: "/api/v1/admin/sites/current/webforms",
        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 Web Form Details

    Get details of a web form.

    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]
      • Alternatively use "current" in place of site_ID for current login token's site
    • 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)
      • list - the API URL that will return a list of all the web forms on this site (string)
      • customFields - the API URL that will return the custom fields resource for this web form (string)
      • systemFields - the API URL that will return the system fields resource for this web form (string)
      • autoresponder - the API URL that will return the autoresponder resource for this web form (string)
    • id - the ID of the web form (integer)
    • name - the name of the web form (string)
    • workflowId - the ID of the workflow. Defaults to 0 if "Don't use a workflow" is selected (integer)
    • zoneId - the ID of the secure zone. Defaults to -1 if "Don't subscribe to a Secure Zone" is selected (integer)
    • affiliateId - affiliate program ID. Defaults to -1 if "Don't subscribe to an Affiliate Program" is selected (integer)
    • createOpportunity - true if sales opportunity is used, false is otherwise (bool)
    • opportunityTypeId - opportunity type ID (integer)
    • stageTypeId - opportunity stage ID (integer)
    • probability - default probability (float)
    • amount - the estimated value of this sale opportunity (integer)
    • cycleTypeId - cycle type ID (integer)
      • 0 - createOpportunity is false
      • 3 - In a week
      • 4 - In a fortnight
      • 5 - In a month
      • 6 - In 3 months
      • 7 - In 6 months
      • 8 - In 1 year
    • setWholesale - wholesale subscription enabled (bool)
    • sendAutoresponder - to send or not the autoresponder email to the customer filling out the web form (bool)
    • siteId - site ID (integer)

    Accepts and returns JSON or XML as Content-Type.


    Sample request

    GET /api/v1/admin/sites/current/webforms
    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/10851"
        },
        {
          "rel": "list",
          "uri": "https://api.worldsecuresystems.com/api/v1/admin/sites/1767665/webforms"
        },
        {
          "rel": "customFields",
          "uri": "https://api.worldsecuresystems.com/api/v1/admin/sites/1767665/webforms/10851/fields/custom"
        },
        {
          "rel": "systemFields",
          "uri": "https://api.worldsecuresystems.com/api/v1/admin/sites/1767665/webforms/10851/fields/system"
        },
        {
          "rel": "autoresponder",
          "uri": "https://api.worldsecuresystems.com/api/v1/admin/sites/1767665/webforms/10851/autoresponder"
        }
      ],
      "id": 10851,
      "name": "Online Shop Quote Form",
      "workflowId": 0,
      "zoneId": -1,
      "affiliateId": -1,
      "createOpportunity": false,
      "opportunityTypeId": null,
      "stageTypeId": null,
      "probability": null,
      "amount": null,
      "cycleTypeId": null,
      "setWholesale": false,
      "sendAutoresponder": true,
      "siteId": 1767665,
      "hasSubmissions": false
    }

    Sample code

    var request = $.ajax({
        url: "/api/v1/admin/sites/current/webforms/10851",
        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 Web Form

    Create a web form.

    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
      • Alternatively use "current" in place of site_ID for current login token's site
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Parameters

    • name - the name of the web form (string) (required)
    • workflowId - the ID of the workflow. Defaults to 0 if "Don't use a workflow" is selected (integer)
    • zoneId - the ID of the secure zone. Defaults to -1 if "Don't subscribe to a Secure Zone" is selected (integer)
    • affiliateId - affiliate program ID. Defaults to -1 if "Don't subscribe to an Affiliate Program" is selected (integer)
    • createOpportunity - true if sales opportunity is used, false is otherwise (bool)
    • opportunityTypeId - opportunity type ID (integer)
    • stageTypeId - opportunity stage ID (integer)
    • probability - default probability (float)
    • amount - the estimated value of this sale opportunity (integer)
    • cycleTypeId - cycle type ID (integer)
      • 0 - createOpportunity is false
      • 3 - In a week
      • 4 - In a fortnight
      • 5 - In a month
      • 6 - In 3 months
      • 7 - In 6 months
      • 8 - In 1 year
    • setWholesale - wholesale subscription enabled (bool)
    • sendAutoresponder - to send or not the autoresponder email to the customer filling out the web form (bool)

     

    Response

    Accepts JSON or XML as Content-Type.

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

    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/current/webforms",
        type: "POST",
        headers: {
            "Authorization": $.cookie('access_token')
        },
        contentType: "application/json",
    	"processData": false,
        data: JSON.stringify({
            "name": "Newly created Web Form using v1 API"  
        })
    });
    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);
    })

    Edit a Web Form

    Update an existing web form.

    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]
      • Alternatively use "current" in place of site_ID for current login token's site
    • Authorization header: This should contain the authorization token. Here is how to obtain the token.
    • Accept header: application/xml or application/json

    Parameters

    • name - the name of the web form (string)
    • workflowId - the ID of the workflow. Defaults to 0 if "Don't use a workflow" is selected (integer)
    • zoneId - the ID of the secure zone. Defaults to -1 if "Don't subscribe to a Secure Zone" is selected (integer)
    • affiliateId - affiliate program ID. Defaults to -1 if "Don't subscribe to an Affiliate Program" is selected (integer)
    • createOpportunity - true if sales opportunity is used, false is otherwise (bool)
    • opportunityTypeId - opportunity type ID (integer)
    • stageTypeId - opportunity stage ID (integer)
    • probability - default probability (float)
    • amount - the estimated value of this sale opportunity (integer)
    • cycleTypeId - cycle type ID (integer)
      • 0 - createOpportunity is false
      • 3 - In a week
      • 4 - In a fortnight
      • 5 - In a month
      • 6 - In 3 months
      • 7 - In 6 months
      • 8 - In 1 year
    • setWholesale - wholesale subscription enabled (bool)
    • sendAutoresponder - to send or not the autoresponder email to the customer filling out the web form (bool)

     

    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/current/webforms/10851",
        type: "PUT",
        connection: "keep-alive",    
        contentType: "application/json",headers: {
            "Authorization": $.cookie('access_token')
        },   
        processData: false,
    	data: JSON.stringify({
            "name": "updated web form",
            "workflowId": -1,
            "zoneId": -1,
            "affiliateId": 0,
            "createOpportunity": false,
            "opportunityTypeId": null,
            "stageTypeId": null,
            "probability": null,
            "amount": null,
            "cycleTypeId": null,
            "setWholesale": false,
            "sendAutoresponder": true
        })
    });
    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 a Web Form

    Delete an existing 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]
      • Alternatively use "current" in place of site_ID for current login token's site
    • 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/current/webforms/10851 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

    Sample request

    var access_token = BCAPI.Helper.Site.getAccessToken();
    
    var request = $.ajax({
        url: "/api/v1/admin/sites/current/webforms/10851",
        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);
    });

    Error codes

    • HTTP 400 Bad Request
      • 115000 generic error (when the required parameters are not specified)
    • HTTP 404 Not Found
      • 115001 when web form with specified ID is not found
    • HTTP 401 Unauthorized
      • 101000 when the request is not authorized (check server/path and Authorization header)
      • 115002 when the field is not found
      • 115003 when adding CRM related fields and site's plan does not include CRM
      • 115004 when adding eCommerce related fields and site's plan does not include eCommerce
      • 115005 when you request to delete a mandatory system field
    • HTTP 403 Forbidden
      • 115006 when creating a system field with a type that already exists on the webform; there can be no 2 fields of the same type on a webform
      • 115007 when adding Email marketing related fields and site's plan does not include Email Marketing
      • 115008 when you reach maximum number of web forms
    • HTTP 500 On other errors