☰ Close Sidebar
Description

iForms are electronic data collection forms housed within the iCIMS Talent Platform. All iForms are permanently stored within the Platform and are associated to Recruiting Workflow, Job, or Person Profiles.

    API Examples

    Supported commands for the iForms object type are as follows.

    List all iForms accessible via web services

    List all the iForms accessible via web services. Disabled and Archived iForms are NOT included.

    Note that there is no difference between the URLs provided below. Either is acceptable.

    URL:   

    https://api.icims.com/customers/{customerId}/forms/list
    OR
    https://api.icims.com/customers/{customerId}/forms

    Action Definition
    Get: 

    Returns a list of all the iForms accessible via web services. Disabled and Archived iForms are NOT included.

    {
      "forms": [
        {
          "id": 17,
          "formname": "Background_Check_Form",
          "type": "Person",
          "displayName": "*Background Check Form",
          "standardizedLevel": "CUSTOM",
          "isPublicAnswers": true
        }
      ]
    }

     

    List out all the questions for a specified iForm

    URL:   https://api.icims.com/customers/{customerId}/forms/{formname}/meta

    type - question field type

    data - details regarding the pre-population of the question field

    field - integration ID of the field that the question is synced with

    text - custom text for pre-population

    Action Definition
    Get: 

    Returns a list of all the questions for the iForm denoted by formName in the URL.

    {
      "q6": {
        "data": {
          "field": "federalexemptfromfit",
          "data": {
            "type": {
              "id": 1,
              "text": "Prepopulate with Search Column Value"
            }
          },
          "type": {
            "id": -3,
            "text": "Copy to Profile Field"
          }
        },
        "searchable": false,
        "required": false,
        "type": "TEXTFIELD"
      },
      "q5": {
        "data": {
          "field": "federaladditionalwithholding",
          "data": {
            "data": "sample custom text to be filled",
            "type": {
              "id": -1,
              "text": "Prepopulate with Custom Text"
            }
          },
          "type": {
            "id": -3,
            "text": "Copy to Profile Field"
          }
        },
        "searchable": false,
        "required": false,
        "type": "TEXTFIELD"
      },
      "q2": {
        "data": {
          "text": "sample custom text to be filled",
          "type": {
            "id": -1,
            "text": "Prepopulate with Custom Text"
          }
        },
        "searchable": false,
        "required": true,
        "type": "TEXTFIELD"
      },
      "q1": {
        "searchable": false,
        "required": false,
        "type": "TEXTFIELD",
        "section": "sample section",
        "searchable": true
      },
      "q4": {
        "data": {
          "field": "firstname",
          "type": {
            "id": -2,
            "text": "Sync with Profile Field"
          }
        },
        "searchable": false,
        "required": false,
        "type": "TEXTFIELD"
      },
      "q3": {
        "data": {
          "type": {
            "id": 1,
            "text": "Prepopulate with Search Column Value"
          }
        },
        "required": false,
        "type": "TEXTFIELD",
        "searchable": true
      }
    }

     

    Sample Response: 

    Possible responses include the following errors:

    • 404 Not Found - A form with the formName of sampleForm does not exist.
    • 403 Forbidden - This form has been disabled
      • Reason : Form is disabled or form is archived.
    • 403 Forbidden - This form's set up is incompatible with web services.
      • Reason : Some of the form question ids is not compatible for web services.

     

    Submit a filled out form

    A form can be filled out using POST or PUT. See below for a template and example for submitting a filled-out form using POST; the URL and format for PUT are the same.

    The behavior for creating new forms (i.e., owner has never filled out the form) is the same for POST and PUT. While POST /forms will fail if a form exists (i.e., the owner has previously filled out the form), PUT /forms will delete existing responses and replace them. Any non-required fields that are not included in the PUT /forms payload will be deleted; this cannot be undone. (Non-required fields that are not included in the POST /forms payload will be left blank.)

    Note:

    • When a form answer is replaced via PUT /forms, the existing formDataId does not change.
    • formname refers to the form’s internal name. It is also referred to as the Form ID within the Platform.
    • questionInternalName is also referred to as the Question ID within the Platform.

    URL: 

    POST or PUT: https://api.icims.com/customers/{customerId}/forms
    OR
    PUT only: https://api.icims.com/customers/{customerId}/forms/{formDataId}

    Action Definition
    Post:

    Template:

    {

        "owner": owner’sprofileID,

        "formname": "InternalFormName",

        "updatedfor<OnlyforprivateiForms>": associatedperson’sID,

        "QuestionInternalName": AnswerData,

        "GroupName": [

            {

                "GroupMemberInternalName": AnswerData,

                …

            },

            …

        ]

    }

     

    Example:

    {

        "owner": 18166,

        "formname": "people",

        "firstname": "John",

        "lastname": "McGee",

        "phone": [

            {

                "phonetype": {

                    "id": "D83001"

                },

                "phonenumber": "2228675309",

                "phoneextension": "1234"

            }

        ]

    }

     


    Error Case Response:
    HTTP\1.1 400 Bad Request

    {

        "errors": [

            {

                "errorMessage": "errormessage",

                "errorCode": errornumber

            },

            {

                "errorMessage": "errormessage",

                "errorCode": errornumber

            }

        ]

    }

     

    Success Case Response:

    HTTP\1.1 201 Created
    Link:<https://api.icims.com/customers/{customerId}/profileType/profileID>;rel=”owner”;title=”Go to this form’s owner”; 
    Location:https://api.icims.com/customers/{customerId}/forms/{formDataID}

     

    Get the filled out form data for the specified form

    Either URL provided below may be used to retrieve filled out form data for a specified Form. For both, only questions/fields that exist will be returned; for example, a form that has not been completed will not show a completedDate.

    URLs

    https://api.icims.com/customers/{customerId}/forms/{formDataID}

    • Note: If no questions are specified (via the format "?questions={question1},{question2}"), only the following items will be returned:  formname, status, owner, completeddate, updateddate,requesteddate, updatedby, requestedby, completedby, and updatedfor. Otherwise, these fields must be requested just like other questions.

    https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}

    • Note: All form questions will be returned by default if no questions are specified.
    Action Definition
    Get: 

    Get the filled out form data for a specific form

    GET https://api.icims.com/customers/123/forms/44?questions=owner,signature,addresses

    HTTP\1.1 200 OK
    {Cache-Control=[no-cache,no-store,no-transform,must-revalidate,max-age=0,s-maxage=0], 
    Content-Type=[application/json;charset=UTF-8], Content-Language=[en_US], 
    Content-Encoding=[UTF-8], 
    Link=[https://api.dev.icims.com/customers/448/forms/12;rel="self";title="the current form being viewed.", https://api.dev.icims.com/customers/448/applicantworkflows/214859;rel="formAbout";title="the profile this Form is owned by.",], 
    X-Content-Type-Options=[nosniff], 
    X-TRANSACTION=[{343B7D8D-BC77-C29B-CAD9-7FB2B561774A}], 
    X-RateLimit-Limit=[50000], 
    X-RateLimit-Remaining=[49996], 
    X-RateLimit-Reset=[19748], 
    Date=[Thu, 04 Oct 2012 18:30:53 GMT], 
    Content-Length=[497]}

    {

        "owner": {

            "id": 5,

            "title": "JohnBrown",

            "Profile": "https//api.icims.com/customers/1234/people/5"

        },

        "signature": true,

        "addresses": [

            {

                "address1": "123MainStreet",

                "city": "Matawan"

            }{

                "address1": "321MiddleRoad",

                "city": "Hazlet"

            }

        ]

    }
    Post: Source
    bodypb
    Switch to plain text editor
    More information about text formats
    Text format
    Lines and paragraphs break automatically.
    Delete: Not Supported

     

    Update the information for a specific form

    Either URL provided below may be used to update form data for a specified Form.

    When updating a group, users can specify which entry to update by adding an entry field to the object. Leaving entry blank will append an entry to the end of the collection. To delete an entire entry from a group, provide a field called delete as part of the entry for a collection. This will assume the last entry in the group loop if none is specified.

    Setting the value for a question to null will clear the information.

    URL: 

    https://api.icims.com/customers/{customerId}/forms/{formDataID}?questions={question1},{question2}
    OR
    https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}?questions={question1},{question2}

    Action Definition
    Patch: 

    Message Content from partner: PATCH https://api.icims.com/customers/123/forms/5

    {
        "middle_name": null,
        "first_name": "John",
        "addresses": [
            {
                "address1": "900BroadStreet",
                "city": "Chicago"
            }{
                "entry": 2,
                "delete": true
            }{
                "entry": 1,
                "city": "Aberdeen"
            }
        ]
    }

     

    Error Case Response
    HTTP\1.1 400 Bad Request

    {
        "errors": [
            {
                "errorMessage": "errormessage",
                "errorCode": errornumber
            },
            {
                "errorMessage": "errormessage",
                "errorCode": errornumber
            }
        ]
    }

     

    Success Case Response

    HTTP\1.1 204 NO CONTENT
    Link:https://api.icims.com/customers/{customerId}/forms/{formData ID}; rel=”self”; title=”this form”

       

      Return the binary Microsoft Word document version of a form

      URL: 

      https://api.icims.com/customers/{customerId}/forms/{formDataID}.doc
      OR
      https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.doc

      Action Definition
      Get: 

      Returns the binary Microsoft Word document version of the specified form

      https://api.icims.com/customers/123/forms/5.doc

      OR

      https://api.icims.com/customers/123/forms/Test_Form/data/5.doc

      Note that the longer URL allows an additional level of validation, as the Form Name and Form Data ID must match the same form.

       

      Return the binary PDF version of a form

      URL: 

      https://api.icims.com/customers/{customerId}/forms/{formDataID}.pdf
      OR
      https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.pdf

      Action Definition
      Get: 

      Returns the binary PDF version of the specified form

      https://api.icims.com/customers/123/forms/5.pdf

      OR

      https://api.icims.com/customers/123/forms/Form_Name/data/5.pdf

      Note that the longer URL allows an additional level of validation, as the Form Name and Form Data ID must match the same form.

       

      Get: Returns the binary PDF version of the specified form

      Return the text version of a form

      URL: 

      https://api.icims.com/customers/{customerId}/forms/{formDataID}.txt
      OR
      https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.txt

      Action Definition
      Get: 

      Returns the text version of the specified form

      https://api.icims.com/customers/123/forms/5.txt

      OR

      https://api.icims.com/customers/123/forms/New_Form/data/5.txt

      Note that the longer URL allows an additional level of validation, as the Form Name and Form Data ID must match the same form.
      Application
      ICIMS Applicant Tracking