AttachmentScanner
API docs by Redocly

AttachmentScanner API (1.0)

URL: https://www.attachmentscanner.com/contact_us

The AttachmentScanner API lets you scan files for viruses and malware. Submit a file or URL, get back a scan result.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

You'll find your API token on your scanner page after signing up.

Regions

Your scanner runs in one of three regions. Use the matching base URL for all requests:

  • US (AWS us-east-1) — https://us-east-1.attachmentscanner.com
  • EU (AWS eu-west-1) — https://eu-west-1.attachmentscanner.com
  • AUS (AWS ap-southeast-2) — https://ap-southeast-2.attachmentscanner.com

API Versioning

Prefix requests with /v1.0/ (recommended) or /v0.1/. Calling without a version prefix also works but is not recommended.

Callbacks

You can pass a callback URL when creating a scan. AttachmentScanner will POST the full scan result to that URL each time the scan status is updated.

For the best experience, combine callback with async: true — your request returns immediately and your callback URL receives the result when the scan completes. Without async, the request blocks until the scan finishes so you already have the result in the response, though the callback will still fire.

Callbacks will not fire for pending status or more than 1 hour after scan creation. You may receive multiple callbacks for the same scan — use the updated_at field to handle duplicates.

Scan Statuses

Every scan returns a status field indicating the result:

  • ok — Clean, no threats detected.
  • found — Malware detected. Check the matches array for threat names.
  • warning — Suspicious content such as macros or encrypted archives. May be legitimate depending on your use case — review the matches array for details.
  • pending — Scan is still in progress. Use callbacks or poll the get endpoint for the final result.
  • failed — Scan could not complete. The matches array contains the reason (e.g. "Unable to fetch URL").

Rate Limiting

Requests are limited to 10 req/min by default. Contact us if you need a higher limit.

Scan Size

Maximum file size is 256 MB for both uploads and URL fetches. Contact support if you need to scan larger files.

Redirects

If the API returns a redirect, follow it. Note that the scanning system itself will not follow redirects when fetching URLs.

Scans

Create and retrieve malware scans.

Create a scan

Submit a file or URL for malware scanning. You can either:

  • Pass a url as application/json — AttachmentScanner will fetch the file and scan it.
  • Upload a file as multipart/form-data.

We recommend passing async: true with a callback URL. Your request returns immediately and AttachmentScanner POSTs the result to your callback when the scan completes.

Without async, the request blocks until the scan finishes (up to 30 seconds). If the scan takes longer, the response will have status: "pending" and you should use callbacks or poll the fetch endpoint for the result.

Authorizations:
bearerAuth
Request Body schema:
required
url
required
string <uri>

Publicly accessible URL of the file to scan.

callback
string <uri>

URL to receive scan result via HTTP POST when the scan completes.

async
boolean
Default: false

If true, return immediately with pending status instead of waiting for the scan to complete.

Responses

Callbacks

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "id": "b9ffd653-2ae2-4d02-b60a-283ca2e238e8",
  • "status": "found",
  • "url": "https://www.attachmentscanner.com/eicar.com",
  • "filename": "eicar.com",
  • "content_length": 70,
  • "md5": "e7e5fa40569514ec442bbdf755d89c2f",
  • "sha256": "8b3f191819931d1f2cef7289239b5f77c00b079847b9c2636e56854d1e5eff71",
  • "matches": [
    ],
  • "callback": null,
  • "created_at": "2026-03-07T14:49:02.570Z",
  • "updated_at": "2026-03-07T14:49:04.945Z"
}

Callback payload samples

Callback
POST: Scan result callback
Content type
application/json
{
  • "id": "b9ffd653-2ae2-4d02-b60a-283ca2e238e8",
  • "status": "found",
  • "url": "https://www.attachmentscanner.com/eicar.com",
  • "filename": "eicar.com",
  • "content_length": 70,
  • "md5": "e7e5fa40569514ec442bbdf755d89c2f",
  • "sha256": "8b3f191819931d1f2cef7289239b5f77c00b079847b9c2636e56854d1e5eff71",
  • "matches": [
    ],
  • "callback": "https://your-app.com/webhooks/scan-complete",
  • "created_at": "2026-03-07T14:49:02.570Z",
  • "updated_at": "2026-03-07T14:49:04.945Z"
}

List scans

Returns a paginated list of scans for your scanner. Pagination links are returned in the Link response header.

You can filter results by passing a query parameter, which searches across scan fields.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number for pagination.

query
string

Search query to filter scans.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a scan

Retrieve the details of a single scan by ID. Use this to poll for results when a scan returns pending status.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: b9ffd653-2ae2-4d02-b60a-283ca2e238e8

The scan ID.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "ok",
  • "url": "http://example.com",
  • "filename": "string",
  • "content_length": 0,
  • "md5": "string",
  • "sha256": "string",
  • "matches": [
    ],
  • "callback": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get scan counts

Returns the total number of scans for your scanner, broken down by time period.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "totals": {
    }
}

Get scan stats

Returns scan statistics as a time series, grouped into intervals. Useful for charting scan volume over time.

Authorizations:
bearerAuth
query Parameters
days
string
Default: "1"
Enum: "1" "7" "30" "90"

Number of days to look back.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]