---
title: "Create scan"
source_url: https://dev.digicert.com/certcentral-apis/discovery-api/scan-lifecycle/create-scan.html
api_method: POST
api_endpoint: "/apicontroller/v1/scan/create"
api_url: "https://daas.digicert.com/apicontroller/v1/scan/create"
---

**POST** `https://daas.digicert.com/apicontroller/v1/scan/create`

Use this endpoint to create a scan and get certificates and vulnerabilities.

## Related topic

For more information on discovery scan and its details, see <a href="https://docs.digicert.com/en/certcentral/certificate-tools/discovery-user-guide/set-up-and-run-a-scan.html" target="_blank" rel="noopener noreferrer">Set up and run a scan</a>.

## Example requests and responses

## cURL

```bash
curl --location --request GET 'https://daas.digicert.com/apicontroller/v1/scan/create' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "surveyName": "testingscan",
    "frequencyType": "onetime",
    "surveyConfigDTO": {
        "sensorWithIpPortDTO": [
            { 
                "portSelectionChoice": "default",
                "ipInclusionList": "www.digicert.com",
                "ipExclusionList": "",
                "includedPorts": [
                    "80",
                    "443",
                    "389",
                    "636",
                    "22",
                    "143",
                    "110",
                    "465",
                    "8443",
                    "3389"
                ],
                "licenseKey": "9E205E8B61130C32",
                "name": "14MaySensor Proxy3810 (Error)",
                "includeAllSubdomains": ["www.digicert.com"],
                "selectedSubdomains": [{
				"domain": "www.yahoo.com",
				"subdomains": ["accountlink.www.yahoo.com",                         
    						"secure.www.yahoo.com"]
	       }, {
				"domain": "www.google.com",
				"subdomains": ["www.google.com----------------- 
						r.reflectiz.com"]
	       }],
                "isIPv4Sensor": true,
                "openPorts": null
            }
        ],
        "startTime": 0,
        "timeToComplete": 0,
        "timezone": "5:30#chennai",
        "monthRecType": "1st",
        "speed": "medium",
        "refreshHPSInventory": "always",
        "isCreateFlow": true,
        "scanOption": "optimize",
        "tls13": false,
        "sshDiscovery": false,
        "sni": false,
        "vulnerabilityList": "Heartbleed,POODLE (SSLv3),FREAK,LogJam,DROWN,RC4,POODLE (TLS)",
        "isOsDiscoverable": false,
        "isServiceDiscoverable": false,
        "extraTlsProtocolsDiscovery": false,
        "ipv6": false,
        "disablePing": false,
        "emulationScans": false
    },
    "accountId": 5153184,
    "cipherScan": false,
    "divisionId": 677793,
    "emailAddresses": "cc.admin@cert-testing.com",
    "vulnerabilityScanOption": "critical",
    "listFilteredPorts": false,
    "tags": ""
}'
```

## 200 OK

```json
{
    "error": null,
    "data": {
        "accountId": "5153184",
        "divisionId": 677793,
        "surveyDefId": 294291,
        "surveyName": "testingscan",
        "message": "Scan created successfully"
    }
}
```

## Request parameters

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Req/Opt</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>surveyName</td>
<td>required</td>
<td>string</td>
<td>Friendly name provided for the scan.<br><strong>Max length:</strong>80 characters.</td>
</tr>
<tr>
<td>frequencyType</td>
<td>required</td>
<td>string</td>
<td>How often the scan will run.<br><strong>Allowed values:</strong> <code>One Time</code>, <code>Daily</code>, <code>Weekly</code>, <code>Monthly</code>, <code>Cloud</code></td>
</tr>
<tr>
<td>surveyConfigDTO</td>
<td>required</td>
<td>object</td>
<td>Object container for scan configuration details.</td>
</tr>
<tr>
<td>.. sensorWithIpPortDTO</td>
<td>required</td>
<td>array</td>
<td>Array of objects with IP/port configuration details.</td>
</tr>
<tr>
<td>.. .. portSelectionChoice</td>
<td>required</td>
<td>string</td>
<td>Select the default port or choose from all/custom ports.</td>
</tr>
<tr>
<td>.. .. ipInclusionList</td>
<td>required</td>
<td>string</td>
<td>IPs to include in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.<br><strong>Example for IP format:</strong> <code>104.20.67.46</code><br><strong>Example for FQDN format:</strong> <code>digicert.com</code><br><strong>Note:</strong>Loopback IP "127.0.0.1" is not allowed to scan.</td>
</tr>
<tr>
<td>.. .. ipExclusionList</td>
<td>optional</td>
<td>string</td>
<td>IPs to exclude in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.</td>
</tr>
<tr>
<td>.. .. includedPorts</td>
<td>required</td>
<td>array</td>
<td>Ports to include in the scan. It can be individual ports or port range.</td>
</tr>
<tr>
<td>.. .. licenseKey</td>
<td>required</td>
<td>string</td>
<td>Sensor license key to create scan.</td>
</tr>
<tr>
<td>.. .. name</td>
<td>required</td>
<td>string</td>
<td>Name of the sensor selected.</td>
</tr>
<tr>
<td>.. .. includeAllSubdomains</td>
<td>required</td>
<td>array</td>
<td>List of domains to scan all subdomains for. If a domain is in this list, the scan includes all subdomains of that domain.</td>
</tr>
<tr>
<td>.. .. selectedSubdomains</td>
<td>required</td>
<td>array</td>
<td>List of objects that define which subdomains of a given domain are included in the scan.</td>
</tr>
<tr>
<td>.. .. .. domain</td>
<td>required</td>
<td>string</td>
<td>Name of the domain.</td>
</tr>
<tr>
<td>.. .. .. subdomains</td>
<td>required</td>
<td>array</td>
<td>List of subdomains included in the scan for the given domain.</td>
</tr>
<tr>
<td>.. .. isIPv4Sensor</td>
<td>required</td>
<td>boolean</td>
<td>Use <code>true</code> if the operating system of the installed sensor runs on IPv4.</td>
</tr>
<tr>
<td>.. .. openPorts</td>
<td>required</td>
<td>array</td>
<td>A list of the open ports scanned. Used in scenarios where the host is unresponsive to ping.</td>
</tr>
<tr>
<td>.. startTime</td>
<td>optional</td>
<td>integer</td>
<td>Start time for the scheduled scan.<br><strong>Format:</strong>epoch in millisecond.<br>Epoch corresponds to 0 hours, 0 minutes, and 0 seconds (00:00:00) Coordinated Universal Time (UTC) on a specific date, which varies from system to system.<br><strong>Example: <code>1596781119</code></strong><br><strong>Note:</strong> <code>startTime</code> value should be <code>0</code> when the <code>frequencytype</code> is <code>onetime</code></td>
</tr>
<tr>
<td>.. timeToComplete</td>
<td>optional</td>
<td>integer</td>
<td>Wait time to complete the scan. <strong>0</strong> implies no timeout.</td>
</tr>
<tr>
<td>.. timezone</td>
<td>optional</td>
<td>string</td>
<td>Time zone for the scan.<br><strong>Format:</strong> GMT + your timezone offset.<br><strong>Example:</strong> <code>-8#pacifictime</code></td>
</tr>
<tr>
<td>.. monthRecType</td>
<td>optional</td>
<td>string</td>
<td>Day of the month specified for recurring scan.<br><strong>Allowed values:</strong> <code>1st</code>, <code>2nd</code>, <code>3rd</code>, <code>4th</code>, <code>5th</code><br><strong>Note:</strong> <code>1st</code> being the first day of the month.</td>
</tr>
<tr>
<td>.. speed</td>
<td>optional</td>
<td>string</td>
<td>How fast the scan completes.<br><strong>Default:</strong> <code>medium</code><br><strong>Allowed values:</strong> <code>slow</code>, <code>medium</code>, <code>fast</code></td>
</tr>
<tr>
<td>.. refreshHPSInventory</td>
<td>required</td>
<td>string</td>
<td>How often the host inventory will refresh. <code>1</code>- always,<code>2</code> - monthly, <code>0</code>- never</td>
</tr>
<tr>
<td>.. isCreateFlow</td>
<td>required</td>
<td>boolean</td>
<td>Use <code>true</code> when creating a new scan, and <code>false</code> when updating an existing scan.</td>
</tr>
<tr>
<td>.. scanOption</td>
<td>optional</td>
<td>string</td>
<td>Configure the scan settings either to <code>custom</code> / <code>optimize</code>.</td>
</tr>
<tr>
<td>.. tls13</td>
<td>optional</td>
<td>boolean</td>
<td>Enable scan of TLS v1.3 protocol.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. sshDiscovery</td>
<td>optional</td>
<td>boolean</td>
<td>Enable SSH key to be discovered.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. sni</td>
<td>optional</td>
<td>boolean</td>
<td>Enable the Server Name Indication (SNI) for your scan.</td>
</tr>
<tr>
<td>.. vulnerabilityList</td>
<td>required</td>
<td>string</td>
<td>This is a comma separated list of the vulnerabilities to scan for.<br><strong>Allowed values:</strong> <code>Heartbleed</code>, <code>POODLE(SSLv3)</code>, <code>FREAK</code>, <code>LogJam</code>, <code>DROWN</code>, <code>RC4</code>, <code>POODLE(TLS)</code>, <code>BEAST</code>, <code>CRIME</code>, <code>BREACH</code>, <code>SWEET32</code>.</td>
</tr>
<tr>
<td>.. isOsDiscoverable</td>
<td>optional</td>
<td>boolean</td>
<td>Include or exclude OS information.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. isServiceDiscoverable</td>
<td>required</td>
<td>boolean</td>
<td>Include or exclude server application information.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. extraTlsProtocolsDiscovery</td>
<td>optional</td>
<td>boolean</td>
<td>Enable discovery of extra TLS protocol.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. ipv6</td>
<td>optional</td>
<td>boolean</td>
<td>Use true if IPv6 addresses are used.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>.. disablePing</td>
<td>optional</td>
<td>boolean</td>
<td>Enable hosts discovery that do not respond to ping.<br><strong>Note:</strong> If <code>true</code>, <code>openPorts</code> should be provided.</td>
</tr>
<tr>
<td>.. emulationScans</td>
<td>optional</td>
<td>boolean</td>
<td>If <code>true</code>, it will exclude <code>Heartbleed</code> and <code>POODLE (TLS)</code> from vulnerability discovery.</td>
</tr>
<tr>
<td>accountId</td>
<td>required</td>
<td>string</td>
<td>Account ID.</td>
</tr>
<tr>
<td>divisionId</td>
<td>required</td>
<td>long</td>
<td>Division ID.</td>
</tr>
<tr>
<td>cipherScan</td>
<td>optional</td>
<td>boolean</td>
<td>Enable scan for ciphers configured on server.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>emailAddress</td>
<td>optional</td>
<td>string</td>
<td>Email address for the contact associated with the scan.</td>
</tr>
<tr>
<td>vulnerabilityScanOption</td>
<td>optional</td>
<td>string</td>
<td>Setting that defines which vulnerabilities to scan for.<br><strong>Allowed values:</strong> <code>all</code>, <code>critical</code>.</td>
</tr>
<tr>
<td>listFilteredPorts</td>
<td>optional</td>
<td>boolean</td>
<td>If enabled, scan will list all the closed and filtered ports.<br><strong>Default:</strong> <code>false</code></td>
</tr>
<tr>
<td>tags</td>
<td>optional</td>
<td>string</td>
<td>Add tags to the scan. Tags can be a combination of letters (a-z or A-Z), numbers (0-9), number signs (#), or spaces. Entries must be comma-separated. (Maximum 512 characters).<br><strong>Note</strong>: Alphanumeric characters like #, @ and _ are allowed.</td>
</tr>
</tbody>
</table>

## Response parameters

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>error</td>
<td>object</td>
<td>Includes the error code if any.</td>
</tr>
<tr>
<td>data</td>
<td>object</td>
<td>Object container for response.</td>
</tr>
<tr>
<td>.. accountId</td>
<td>string</td>
<td>Account ID.</td>
</tr>
<tr>
<td>.. divisionId</td>
<td>integer</td>
<td>Division ID.</td>
</tr>
<tr>
<td>.. surveyName</td>
<td>string</td>
<td>Friendly name provided for the scan.<br><strong>Max length:</strong>80 characters.</td>
</tr>
<tr>
<td>.. message</td>
<td>string</td>
<td>Updated message for scan creation.</td>
</tr>
</tbody>
</table>