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 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.
https://api.icims.com/customers/{customerId}/forms/list
OR
https://api.icims.com/customers/{customerId}/forms
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
}
]
}
https://api.icims.com/customers/{customerId}/forms/{formname}/meta
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
}
}
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.
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.
POST or PUT: https://api.icims.com/customers/{customerId}/forms
OR
PUT only: https://api.icims.com/customers/{customerId}/forms/{formDataId}
Error Case Response:
HTTP\1.1 400 Bad Request
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}
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.
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]}
Source
bodypb
Switch to plain text editor
More information about text formats
Text format
Lines and paragraphs break automatically.
Not Supported
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.
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}
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”
https://api.icims.com/customers/{customerId}/forms/{formDataID}.doc
OR
https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.doc
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.
https://api.icims.com/customers/{customerId}/forms/{formDataID}.pdf
OR
https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.pdf
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.
https://api.icims.com/customers/{customerId}/forms/{formDataID}.txt
OR
https://api.icims.com/customers/{customerId}/forms/{formname}/data/{formDataId}.txt
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.