Enrollment Campaigns Api Create Campaign
Creates a campaign for the chosen scope; a scope that resolves to no hosts completes at once. Requires the ADMIN role.
The new enrollment campaign: name, scopeType and the scope it covers, with the optional concurrencyLimit, securityGroupId and autoStart. name and scopeType are required.
Show optional properties
{
"name": "string",
"scopeType": "string"
}
{
"name": "Enroll Production Cluster",
"scopeType": "CLUSTER",
"vcenterConnectionId": "db-1",
"clusterMoRef": "domain-c8",
"concurrencyLimit": 5,
"securityGroupId": 1,
"autoStart": false
}
Must not be blank
Which hosts a campaign targets.
FLEET: All registered hosts are resolved as targets, but each job fails with 'Fleet-wide enrollment is not supported' and nothing is enrolled; also the default of the stored campaignVCENTER: The hosts of the vCenter connection named in vcenterConnectionId; a job runs only while that vCenter has Auto Enrollment enabled and otherwise failsCLUSTER: The hosts whose parentLocator equals clusterMoRefSELECTION: The hosts named in hypervisorPksAUTO_DISCOVERY: Created by the Console for a vCenter with Auto Enrollment enabled; its jobs wait while automatic enrollment is paused
For scopeType VCENTER or CLUSTER
For scopeType CLUSTER
Most jobs of one vCenter that may be started at the same time for this campaign. 5 when absent or not above 0; the default is fixed and does not follow the configured per-vCenter limit (only automatic campaigns use that setting)
For scopeType SELECTION
Identifier of the Security Group to record with the campaign; null when none is given
Whether the campaign starts at creation; true when omitted, and when false the campaign stays CREATED until it is started
201 Created successful response envelope. The created campaign
{
"campaignId": 1,
"name": "Enroll Production Cluster",
"scopeType": "CLUSTER",
"vcenterConnectionId": "db-1",
"clusterMoRef": "domain-c8",
"status": "CREATED",
"totalHosts": 3,
"enrolledHosts": 0,
"failedHosts": 0,
"inProgressHosts": 0,
"concurrencyLimit": 5,
"securityGroupId": 1,
"createdAt": "2026-01-15T09:30:00Z",
"startedAt": null,
"completedAt": null,
"progressPercent": 0
}
Identifier of the campaign, assigned when it is created
Name given at creation, stored trimmed; an automatic campaign is named 'Auto Enrollment - ' followed by the vCenter display name and the creation time
Which hosts a campaign targets.
FLEET: All registered hosts are resolved as targets, but each job fails with 'Fleet-wide enrollment is not supported' and nothing is enrolled; also the default of the stored campaignVCENTER: The hosts of the vCenter connection named in vcenterConnectionId; a job runs only while that vCenter has Auto Enrollment enabled and otherwise failsCLUSTER: The hosts whose parentLocator equals clusterMoRefSELECTION: The hosts named in hypervisorPksAUTO_DISCOVERY: Created by the Console for a vCenter with Auto Enrollment enabled; its jobs wait while automatic enrollment is paused
Identifier of the vCenter connection given at creation: it selects the hosts of a VCENTER campaign and is the vCenter of an AUTO_DISCOVERY campaign; null when none was given
Cluster identifier given at creation; a CLUSTER campaign targets the hosts whose parentLocator equals it; null when none was given
Campaign state.
CREATED: The campaign exists and has not been started, which is the case for autoStart falseRUNNING: Jobs are being worked; set at creation with autoStart, by the start and resume operations, and for an automatic campaign at creationPAUSED: Paused by the pause operation, which accepts only a RUNNING campaign; jobs are not worked until it is resumedCOMPLETED: Every host has a result and at least one was enrolled, or no host needed enrolling at creationCANCELLED: Cancelled by the cancel operation or by the removal of its vCenter; its queued jobs are cancelledFAILED: Every host has a result and none was enrolled
Number of hosts the campaign has to enroll, one per queued job; hosts that were already ENROLLED at creation are not counted, and an AUTO_DISCOVERY campaign adds to it as jobs are appended
Number of hosts whose enrollment job completed successfully
Number of hosts whose enrollment job ended in a permanent failure; retrying the failed jobs lowers it
Number of enrollment jobs that have started and have not yet completed, failed permanently or been queued for a retry
Most jobs of one vCenter that may be started at the same time for this campaign; set from the request (5 when absent or not above 0), and for an automatic campaign from the maxConcurrentPerVcenter setting
Identifier of the Security Group given when the campaign was created; null when none was given
Time the campaign was created
Time the campaign was first started, at creation when autoStart applies or by the start operation; null while it has not been started
Time the campaign reached COMPLETED, FAILED or CANCELLED, including a campaign that found no host to enroll at creation; null otherwise
Share of totalHosts that has finished, enrolled or failed, as a whole percentage rounded and capped at 100; 0 when totalHosts is 0
400 Bad Request: MALFORMED_REQUEST when the body is not valid JSON or scopeType is not one of the listed values. A blank name or a missing scopeType is currently not rejected with a 400: the service throws an IllegalArgumentException and the server answers 500 INTERNAL_ERROR (established by reading the code, not run-tested)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string","scopeType":"string"}' https://{api_host}/api/v1/hypervisors/campaigns