---
title: Creating a scan using the API
slug: asm/creating-a-scan-using-the-api
description: The API endpoints required to create and start a scan are highlighted in the API documentation, but this page details those steps
docTags: 
createdAt: 2023-11-10T14:08:48.452Z
---

:::hint{type="info"}
This feature is not available to all tiers, please contact us if you would like to discuss adding this feature to your Hexiosec ASM account.
:::

The API endpoints required to create and start a scan are highlighted in the API documentation, but this page details those steps:

1. Creating a scan
2. Adding seeds to a scan
3. Starting a scan
4. Check a scan's state

In the following steps, an example scan ID, `00000001-0001-0001-0001-000000000001` and API token, `XYZ` have been used, and will need to be replaced with the valid values.

# Create and start

## 1. Creating a scan

**API - **[https://asm.hexiosec.com/api/ui#post-/v1/scans](https://asm.hexiosec.com/api/ui#post-/v1/scans)

Information required\*:

- `name`: The name of the scan, as you would see in the app
- `scan_group_id`: The ID of the group to add the scan to
- `type`: The type of the scan to create, either:
  - `adhoc`: Ad Hoc scan
  - `continuous_own`: Own Asset Monitoring scan
  - `continuous_vendor`: Third Party Monitoring scan

\*Other settings are available, see API documentation.

Example:

:::BlockQuote
POST https\://asm.hexiosec.com/api/v1/scans
accept: application/json
content-type: application/json
x-hexiosec-api-key: XYZ

\{
  "name": "API Example Scan",
  "scan\_group\_id": "00000001-0001-0001-0001-000000000001",
  "type": "adhoc",
  "dns\_namelist": true,
  "ignore\_ip\_nodes": false
}
:::

The response from this request will include the scan `id` value, to be used in step 2.

## 2. Adding seeds to a scan

**API - **[https://asm.hexiosec.com/api/ui#post-/v1/scans/-id-/seeds](https://asm.hexiosec.com/api/ui#post-/v1/scans/-id-/seeds)

When the scan has been created, you can add seeds. This endpoint will need to be called for each seed to be added.

Information required\*:

- `id`: The ID of the scan created, from step 1
- In request body, for the seed:
  - `name`: The domain name, IP address or IP range
  - `type`: Either:
    - `domain`
    - `ipv4`
    - `ipv6`
    - `iprange`

\*Other settings are available, see API documentation.

Example:

:::BlockQuote
POST https\://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001/seeds
accept: application/json
content-type: application/json
x-hexiosec-api-key: XYZ

\{
  "name":"example.com",
  "type":"Domain"
} 
:::

## 3. Starting a scan

**API - **[https://asm.hexiosec.com/api/ui#patch-/v1/scans/-id-](https://asm.hexiosec.com/api/ui#patch-/v1/scans/-id-)

Once the scan has been created and seeds added, you use the update endpoint to start the scan running.

Information required\*:

- `id`: The ID of the scan created, from step 1
- In request body, set the state:
  - `enabled`: true

\*Other settings are available, see API documentation.

Example:

:::BlockQuote
PATCH https\://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001
accept: application/json
content-type: application/json
x-hexiosec-api-key: XYZ

\{
  "enabled"\:true
}
:::

# Check state

## 4. Check a scan's state

**API -** [https://asm.hexiosec.com/api/ui#get-/v1/scans/-id-](https://asm.hexiosec.com/api/ui#get-/v1/scans/-id-)

Once a scan has completed you will receive an email notification (if enabled).

You can also use the GET 'scans' endpoint to periodically query the state of the scan.

Information required\*:

- `id`: The ID of the scan created, from step 1
- `expand`: iteration - To ensure you get the state

Example:

:::BlockQuote
GET https\://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001?expand=iteration

acceptapplication/json
x-hexiosec-api-key: XYZ
:::

In the response, the `iteration` object contains the `state` of the latest iteration.

Example response when in progress:

:::BlockQuote
"iteration": \{
  "state": "in\_progress"
}
:::

Example response when complete:

:::BlockQuote
"iteration": \{
  "state": "completed"
}
:::