Discussions
Eloqua Application API Form endpoints – New “archived” property, new endpoints, and Update / Retriev
Update (April 16, 2020): Notice updated to include details on updates to Retrieve a list of forms endpoint, and details on the specifying a folder when archiving or unarchiving a form.
Overview
With the arrival of Eloqua release 20B (May 2020), a new property, archived, that indicates if the form is archived, will be added to the Application API Form endpoints, the Update a form endpoints will have new validation to prevent updating archived forms, and there will be changes to the Retrieve a list of forms endpoint. There will also be two new endpoints to archive and unarchive forms.
What's Changing
With 20B, we are adding archived to the Application API Form endpoints, which will impact the following endpoints:
- 1.0
o Retrieve a list of forms: GET /api/REST/1.0/assets/forms
- Default depth is minimal
o Retrieve a form: GET /api/REST/1.0/assets/form/{id}
- Default depth is complete
o Create a form: POST /api/REST/1.0/assets/form
- Default depth is complete
o Update a form: PUT /api/REST/1.0/assets/form/{id}
- Default depth is complete
- 2.0
o Retrieve a list of forms: GET /api/REST/2.0/assets/forms
- Default depth is minimal
o Retrieve a form: GET /api/REST/2.0/assets/form/{id}
- Default depth is complete
o Create a form: POST /api/REST/2.0/assets/form
- Default depth is complete
o Update a form: PUT /api/REST/2.0/assets/form/{id}
- Default depth is complete
o Partially update a form: PATCH /api/REST/2.0/assets/form/{id}
- Default depth is complete
Notes:
- archived is returned at all depths: minimal, partial, and complete, when retrieving, updating, or creating a form
- archived is returned as a string, with the only possible values being "true" or "false"
- archived is a read-only property, and if including it when creating or updating a form it will be ignored
- When creating a new form, whether via API or in Eloqua, the default for archived is “false”
- If a Form has archived set to “true”, Form submissions will still be accepted, including via both the 1.0 and 2.0 Create form data for a single form API endpoints
- Forms created prior to 20B, or any Forms created prior to enabling this feature, will have archived set to "false"
- Archiving / Unarchiving:
o In Eloqua:
- To archive a form, open the form, select File > Archive > Click Archive Asset
- To unarchive a form, open the archived form, select File > Unarchive > Click Unarchive Asset
o Via API:
- To archive a form use the following endpoint: POST /api/REST/2.0/assets/form/{id}/archive
- If asset is currently archived, a “304 NotModified” response will be returned
- To unarchive a form use the following endpoint: POST /api/REST/2.0/assets/form/{id}/unarchive
- If asset is currently unarchived, a “304 NotModified” response will be returned
- If a Form has archived set to “true”, the form cannot be updated, and validation error will be returned if attempting to update or partially update an archived form
- If a Form has archived set to “true”, it will not be returned by default with the Retrieve a list of forms endpoint
- Two new URL parameters are being introduced for the Retrieve a list of forms endpoint:
- includeAvailable: Set to “true” to include unarchived forms. Set to “false” to not include unarchived forms. If not specified, the default is “true”.
- includeArchived: Set to “true” to include archived forms. Set to “false” to not include archived forms. If not specified, the default is “false”.
- Here is a summary of responses based on the new URL parameters includeAvailable and includeArchived for the Retrieve a list of forms endpoint:
| includeAvailable | includeArchived | Response |
| true / null | false / null | Only unarchived |
| true / null | true | Both archived and unarchived |
| false | false / null | No forms |
| false | true | Only archived |
- When archiving or unarchiving a form a destination folder can be specified in the request body with the targetFolderId property
- If unarchiving:
- If target folder is archived, a “400 Validation” response will be returned, with details on the validation error in the body of the response
- If archiving:
- If target folder is not archived, a “400 Validation” response will be returned, with details on the validation error in the body of the response
- If unarchiving:
- This update applies to both 1.0 and 2.0; however, all examples are using the Form 2.0 endpoints, and it’s recommended to use 2.0, as some features are only available on 2.0
Examples:
After 20B, archived is returned when retrieving Forms at any depth:
Request:
GET /api/REST/2.0/assets/form/35730?depth=minimal
Response: 200 OK
{
"type": "Form",
"currentStatus": "Draft",
"id": "35730",
"createdAt": "1584999843",
"createdBy": "4",
"depth": "minimal",
"folderId": "581901",
"name": "Form-archived-true",
"permissions": [
"Retrieve",
"SetSecurity",
"Delete",
"Update"
],
"updatedAt": "1585000188",
"updatedBy": "4",
"archived": "true",
"htmlName": " Form-archived-property",
"isResponsive": "true"
}
Let’s Unarchive the form we just retrieved, and move it into the unarchived folder id 778496:
Request:
POST /api/REST/2.0/assets/form/35730/unarchive
{
"targetFolderId": "778496"
}
Response: 201 Created
{
"type": "Form",
"currentStatus": "Draft",
"id": "35730",
"createdAt": "1584999843",
"createdBy": "4",
"depth": "minimal",
"folderId": "778496",
"name": "20B_set_to_archive",
"permissions": [
"Retrieve",
"SetSecurity",
"Delete",
"Update"
],
"updatedAt": "1585000188",
"updatedBy": "4",
"archived": "false",
"htmlName": "UntitledForm-1584999824627",
"isResponsive": "true"
}
Let’s Archive the form we just unarchived, and move it into the archived folder id 778497:
Request:
POST /api/REST/2.0/assets/form/35730/archive
{
"targetFolderId": "778497"
}
Response: 201 Created
{
"type": "Form",
"currentStatus": "Draft",
"id": "35730",
"createdAt": "1584999843",
"createdBy": "4",
"depth": "minimal",
"folderId": "778497",
"name": "20B_set_to_archive",
"permissions": [
"Retrieve",
"SetSecurity",
"Delete",
"Update"
],
"updatedAt": "1585000188",
"updatedBy": "4",
"archived": "true",
"htmlName": "UntitledForm-1584999824627",
"isResponsive": "true"
}
Let’s try to update the name using the Partially update a form endpoint to see the validation error:
Request:
PATCH /api/REST/2.0/assets/form/35730
Response: 400 Validation Error
[
{
"type": "ObjectValidationError",
"container": {
"type": "ObjectKey",
"objectId": "35730",
"objectType": "Form"
},
"property": "Archived",
"requirement": {
"type": "StatusRequirement",
"allowedStatusForOperation": "False"
},
"value": "True"
}
]
Let’s try archiving this form to see the “304 NotModified” response:
Request:
POST /api/REST/2.0/assets/form/35730/archive
Response: 304 NotModified
Let’s try unarchiving this form with a folder that’s archived to see the validation response:
Request:
POST /api/REST/2.0/assets/form/35730/unarchive
{
"targetFolderId": "778497"
}
Response: 400 Validation Error
[
{
"type": "ObjectValidationError",
"container": {
"type": "ObjectKey",
"objectId": "778497",
"objectType": "Folder"
},
"property": "archive",
"requirement": {
"type": "StatusRequirement",
"allowedStatusForOperation": "False"
},
"value": "True"
}
]
Retrieving only unarchived forms with the Retrieve a list of forms endpoint will be the default when not including any URL parameters:
Request:
GET /api/REST/2.0/assets/forms
Retrieving both archived and unarchived forms with the Retrieve a list of forms endpoint:
Request:
GET /api/REST/2.0/assets/forms?includeArchived=true
Retrieving only archived forms with the Retrieve a list of forms endpoint:
Request:
GET /api/REST/2.0/assets/forms?includeArchived=true&includeAvailable=false
Timeline
With the arrival of Eloqua release 20B (May 2020), a new property, archived, that indicates if the form is archived, will be added to the Application API Form endpoints, the Update a form endpoints will have new validation to prevent updating archived forms, and there will be changes to the Retrieve a list of forms endpoint. There will also be two new endpoints to archive and unarchive forms. Check the Eloqua Release Center for specific dates and times.
Next Steps
If retrieving, updating, or creating Forms via the Application API, prepare for the archived property to be returned at all depths, for the Update a form endpoints will have new validation to prevent updating archived forms, and for the Retrieve a list of forms endpoint to only return unarchived forms by default.
Prepare for the following responses based on the new URL parameters includeAvailable and includeArchived for the Retrieve a list of forms endpoint:
| includeAvailable | includeArchived | Response |
| true / null | false / null | Only unarchived |
| true / null | true | Both archived and unarchived |
| false | false / null | No forms |
| false | true | Only archived |
If requiring the ability to programmatically archive or unarchive forms, note the addition of these two endpoints:
- POST /api/REST/2.0/assets/form/{id}/archive
- POST /api/REST/2.0/assets/form/{id}/unarchive
Additional Resources
View changes for Eloqua's APIs including, new features, significant recent changes, and platform notices, on the Eloqua Developer Changelog.
If you have questions, post a discussion on Code It!
FAQ
Q: What endpoints are impacted by this change?
A: The following endpoints are impacted:
- 1.0
o Retrieve a list of forms: GET /api/REST/1.0/assets/forms
- Default depth is minimal
o Retrieve a form: GET /api/REST/1.0/assets/form/{id}
- Default depth is complete
o Create a form: POST /api/REST/1.0/assets/form
- Default depth is complete
o Update a form: PUT /api/REST/1.0/assets/form/{id}
- Default depth is complete
- 2.0
o Retrieve a list of forms: GET /api/REST/2.0/assets/forms
- Default depth is minimal
o Retrieve a form: GET /api/REST/2.0/assets/form/{id}
- Default depth is complete
o Create a form: POST /api/REST/2.0/assets/form
- Default depth is complete
o Update a form: PUT /api/REST/2.0/assets/form/{id}
- Default depth is complete
o Partially update a form: PATCH PUT /api/REST/1.0/assets/form/{id}
- Default depth is complete
Q: Will form submissions still be successful if the Form is archived?
A: Yes.
Q: Can I Archive / Unarchive Forms using the Bulk API?
A: Bulk API access to Archive / Unarchive Forms is not available at this time, but it's something we plan to consider in the future.