• iCIMS Corporate Site
  • iCIMS Partners
  • Additional Resources
  • Recent Updates
  • FAQ
  • Login
  • GETTING STARTED
    • Getting Started
    • Integration Approval Process
    • How-To Videos
    • Acceptable Use Policy
    • Terms of Use
    • Release Notes
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
    • Assessments
    • Candidate Matching
    • Candidate Ranking
    • Document Management
    • Data Analytics and Reporting
    • Human Capital Management
    • I-9 & E-Verify
    • Job Advertising
    • Job Posting
    • Partner Screening
    • Reference Checks
    • Tax Credits
    • Video Interviewing
  • Prime Integrations
    • Prime Assessments
    • Prime Background Screen
      • Implementation
  • Endpoints
    • Binary Collection Fields
    • Binary Files
    • Collection Fields
    • Customers
    • Direct Linking
    • iForms
    • Job Distributor
    • Job Portal API
    • List API
    • Offer API
    • Onboard API
    • Profiles
    • Schema API
    • Search API
    • Workflows
  • Streaming Endpoints
  • Data Models
    • iForms
    • Job
    • Location
    • New Hire Category
    • Onboarding Workflow
    • Person
    • Recruiting Workflow
    • Room
    • Sourcing Workflow
    • Talent Pool
    • Event
    • Validation
  • Integration Events
    • Best Practices
    • Application Complete
    • Job Edit
    • Job Posting
    • Job Unposting
    • Onboard Portal Task
    • Status Flow Update
  • OTHER TECH
    • File-Based Transfers
      • Scheduled Import/Export Licenses
      • Imports
      • Exports
      • File Formatting
      • Import File Examples
    • SAML
    • Standard XML Feed for Job Boards
  • Forum

Search form

Developer Resources
  • Getting Started
  • API
  • Standard Integrations
  • Prime Integrations
  • Endpoints
    • Binary Collection Fields
    • Binary Files
    • Collection Fields
    • Customers
    • Direct Linking
    • iForms
    • Job Distributor
    • Job Portal API
    • List API
    • Offer API
    • Onboard API
    • Profiles
    • Schema API
    • Search API
    • Workflows
    • Standard Apply Framework Questions
  • Streaming Endpoints
  • Data Models
  • Integration Events
  • OTHER TECHNOLOGY
  • FAQ

iForms

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.

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.

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.

Do you have any questions or feedback regarding iCIMS' API documentation? Email the team
See Recent Site Updates

© 2023 iCIMS, Inc. All rights reserved.
Privacy Notice | Terms of Use