Creates a new delegated form if the delegated form GUID is left empty. Updates an existing delegated form record if the passed identifier matches an existing delegated form record.
Request
Request URI
| Method | Request URI |
|---|---|
| POST | https://{company-name}.helloid.com/api/v1/delegatedforms |
Request parameters
| Parameter | Description |
|---|---|
| {company-name} | The company name of the target company |
Request headers
| Parameter | Description |
|---|---|
| Content-Type | Must be set to application/json. |
Sample request body
{
"adConfigurationGUID": "6a74fa33-4b1c-410a-a97d-907e3da0ade7",
"name": "Disable account clone",
"slug": "disable-account-clone",
"dynamicFormGUID": null,
"templateID": "ad-account-disable",
"isEnabled": true,
"useManagedUsers": true,
"useUsersFromGroups": false,
"useFaIcon": true,
"faIcon": "fa-credit-card",
"task": {
"script": "Write-Information \"HelloID\"",
"runInCloud": false,
"agentPoolId": "FA06DFA3-F47E-4058-8E8D-AD144AA11490"
},
"sourceGroups": [],
"accessGroups": [
"f3e0d8ba-dd08-4a0e-bf6d-df89ec02de11"
],
"adCommentAttribute": "description"
}
Request body parameters
| Parameter | Description | Required/Optional | Default value |
|---|---|---|---|
| {Name} | Name of the form. Must be unique when no slug was provided. | Required | - |
| {delegatedFormGUID} | The GUID of the form. If specified, it will check if the GUID belongs to an existing form. If so, it will update that form. If not, it will add a new form with the specified GUID. A new GUID is generated if no GUID is provided. | Optional | - |
| {adConfigurationGUID} | The GUID of the AD integration to execute the action on. This is only used for delegated forms based on a standard TemplateID. | Optional | |
| {slug} | A short slug that contains no spaces. If left empty, a slug will be generated based on the name. Must be unique. | Optional | - |
| {dynamicFormGUID} | Guid of the dynamic form you want to use for this delegated form | Optional | - |
| {templateID} | Identifier of an existing delegated form template, such as "Disable account". Leave empty if creating a delegated form based on a dynamic form. | Optional | |
| {isEnabled} | boolean that indicates if the form is enabled | Optional | true |
| {useManagedUsers} | Boolean that indicates if the form dropdown (if available) should only be filled with users managed by the logged in user. This is for form using a standard TemplateID only. | Optional | - |
| {useUsersFromGroups} | Boolean that indicates if the form dropdown (if available) should only be filled with users form specific groups. This is for form using a standard TemplateID only. | Optional | - |
| {useFaIcon} | Boolean that indicates if the configured Font Awesome icon should be used. | Optional | false |
| {faIcon} | The Font Awesome icon that will be used when showing the form in the overview. The value of this parameter should be in the form "fa <icon identifier>". | Optional | - |
| {task} | A task containing the script and whether to run in the cloud or not. AgentPoolId is optional when run in cloud is set to true. This value is required when run in cloud is set to false. | Optional | - |
| {sourceGroups} | List of specified groups to use when {useUsersFromGroups} is set to true | Optional | - |
| {accessGroups} | List of group guids that can use the delegated form | Optional | - |
| {adCommentAttribute} | AD attribute to write comments to about the actions executed by the delegated form. For example: Account disabled on 20-3-20 | Optional | - |
Response
Response status
| Code | Description |
|---|---|
| 200(OK) | Indicates that the operation was successful. |
| 400(BAD REQUEST) | Indicates that the operation was not successful. There were validation errors or the request body was malformed. |
| 401(UNAUTHORIZED) | Indicates that no authentication header was given or the api key and secret were invalid. If the api key and secret were valid check the configuration in your portal, it is possibilty these were IP restricted or are disabled. |
Please also see error result.
Please also see common HTTP status codes.
Sample response body
{
"delegatedFormGUID": "c8e477f3-9e38-45a4-94fd-f9e25864ee85",
"adConfigurationGUID": "6a74fa33-4b1c-410a-a97d-907e3da0ade7",
"name": "Disable account clone",
"slug": "disable-account-clone",
"dynamicFormGUID": null,
"templateID": "ad-account-disable",
"isEnabled": true,
"useManagedUsers": true,
"useUsersFromGroups": false,
"useFaIcon": true,
"faIcon": "fa-credit-card",
"task": {
"script": "Write-Information \"HelloID\"",
"runInCloud": false,
"agentPoolId": "FA06DFA3-F47E-4058-8E8D-AD144AA11490"
},
"sourceGroups": [],
"accessGroups": [],
"adCommentAttribute": "description"
}
Example request with cURL
Replace placeholder values surrounded by { } with the actual values.
curl -u {api-key}:{api-secret} -X POST https://{company-name}.helloid.com/api/v1/forms -H "Content-Type:application/json" -d
"{
'adConfigurationGUID': '6a74fa33-4b1c-410a-a97d-907e3da0ade7',
'name': 'Disable account clone',
'slug': 'disable-account-clone',
'dynamicFormGUID': null,
'templateID': 'ad-account-disable',
'isEnabled': true,
'useManagedUsers': true,
'useUsersFromGroups': false,
'useFaIcon': true,
'faIcon': 'fa-credit-card',
'task': {'script': 'Write-Information "HelloID"', 'runInCloud': true}
'sourceGroups': [],
'accessGroups': [
'f3e0d8ba-dd08-4a0e-bf6d-df89ec02de11'
],
'adCommentAttribute': 'description'
}"