PCI DSS 4.0 readiness for one site

GET

/v1/compliance/pci-dss

const url = 'https://api.us.headerhawk.com/v1/compliance/pci-dss?siteId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.us.headerhawk.com/v1/compliance/pci-dss?siteId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --header 'Authorization: Bearer <token>'

Requirements 6.4.3 (payment page scripts) and 11.6.1 (change and tamper detection) for one site: each one’s verdict, the facts it rests on, what is missing, and the evidence rows. Every plan can read it: where a plan cannot meet a requirement, plan.requiredFor names the plan that can. Reads reported data, so it spends the tenant’s budget too.

The script evidence covers your plan’s whole retention period, named in evidence.window, and the change evidence the last 30 days: the same reads as the dashboard’s Compliance page, so the two verdicts agree. A shorter window would leave out a rejected script last reported on a payment page before it. Measured worst case: 11–36 ms reading 16,395 script reports of one site in 90 days, the longest retention on a published plan (an Enterprise contract can set its own).

Authorizations

apiKey

Parameters

Query Parameters

siteId

required

string format: uuid

The site. A verdict is per site, never across sites.

Responses

200

The site’s readiness

application/json

object

data

required

object

siteId

required

string

siteName

required

string

generatedAt

required

string format: date-time

requirements

required

6.4.3, then 11.6.1.

Array

One of:

object
object

object

required

string

Allowed values: 6.4.3

status

required

A PCI DSS requirement’s verdict.

string

Allowed values: met partial not_met

facts

required

object

paymentPages

required

integer

scripts

required

Scripts reported from the payment pages.

integer

authorized

required

integer

unreviewed

required

integer

rejected

required

integer

integrity

required

object

protected

required

integer

unprotected

required

Includes scripts reported without integrity metadata that the inventory does not hold.

integer

unknown

required

integer

measured

required

The site reports integrity violations, so protected means something. False while every script is unknown.

boolean

gaps

required

Array<object>

One reason a requirement is not met. count is set for unreviewed_scripts, rejected_scripts_running, unprotected_scripts, integrity_unmeasured (the scripts whose integrity nothing has measured) and no_recent_scan (the payment pages without a complete scan in the last 7 days), eventType for no_rule; each is null otherwise.

object

kind

required

string

Allowed values: no_payment_pages scripts_not_on_plan inventory_truncated no_scripts_seen unreviewed_scripts rejected_scripts_running unprotected_scripts integrity_unmeasured no_recent_scan no_rule

count

required

integer

nullable

eventType

required

string

nullable

object

required

string

Allowed values: 11.6.1

status

required

A PCI DSS requirement’s verdict.

string

Allowed values: met partial not_met

facts

required

object

paymentPages

required

integer

scanCadence

required

daily while the plan scans payment pages and every one had a complete scan in the last 7 days.

string

Allowed values: daily none

lastScanAt

required

The least recent of the payment pages’ last complete scans; null while any payment page has none.

string format: date-time

nullable

ruleCoverage

required

Array<object>

object

eventType

required

string

label

required

The alert catalog’s name for the change type.

string

rules

required

Enabled rules with a destination whose scope reaches the site’s payment pages.

Array<object>

object

required

string

name

required

string

changesDetected30d

required

integer

changesAlerted30d

required

Of those, how many had an immediate alert delivered.

integer

gaps

required

Array<object>

object

kind

required

string

Allowed values: no_payment_pages scripts_not_on_plan inventory_truncated no_scripts_seen unreviewed_scripts rejected_scripts_running unprotected_scripts integrity_unmeasured no_recent_scan no_rule

count

required

integer

nullable

eventType

required

string

nullable

evidence

required

object

scripts

required

The scripts reported from the payment pages.

Array<object>

object

required

string

url

required

string

status

required

A script’s current decision. unreviewed until someone authorizes or rejects it.

string

Allowed values: unreviewed authorized rejected

integrityMode

required

any_content or pinned_hashes for an authorized script; null otherwise.

string

nullable

justification

required

string

nullable

decidedBy

required

object

name

required

string

nullable

email

required

string

decidedAt

required

string format: date-time

nullable

coverage

required

string

Allowed values: protected unprotected unknown

stillRunning

required

Rejected, and reported on a payment page since the rejection.

boolean

paymentPages

required

Array<object>

object

pageId

required

string

label

required

string

uninventoriedUnprotected

required

integer

pages

required

The site’s payment pages and their last complete scan.

Array<object>

object

required

string

label

required

string

scanUrl

required

string

nullable

lastScanAt

required

string format: date-time

nullable

grade

required

string

nullable

watched

required

The plan scans payment pages and this one’s last complete scan is under 7 days old.

boolean

changes

required

Scans of a payment page in the last 30 days that found a watched header changed or the grade dropped, newest first.

Array<object>

object

scanId

required

string

pageId

required

string

pageLabel

required

string

scannedAt

required

string format: date-time

headers

required

Array<string>

gradeDroppedFrom

required

string

nullable

grade

required

string

nullable

alerted

required

An immediate alert about this page’s change was delivered within a day. A digest is never matched: its delivery record cannot say which change it carried.

boolean

window

required

The window the script inventory was read over: your plan’s whole retention period. Null when the site has no payment page, so no inventory was read.

object

from

required

string format: date-time

required

string format: date-time

suggestions

required

With no payment page, the busiest pages the site reported from in the last 30 days, as candidates. Empty otherwise.

Array<object>

object

url

required

string

suggestedPattern

required

string

plan

required

object

current

required

A HeaderHawk plan. An open enum.

string

Allowed values: free team professional business enterprise

requiredFor

required

The plan each step needs, or null when the current plan has it.

object

paymentPages

required

A plan id.

string

nullable

scans

required

A plan id.

string

nullable

decisions

required

A plan id.

string

nullable

Example

{
  "data": {
    "requirements": [
      {
        "id": "6.4.3",
        "status": "met",
        "gaps": [
          {
            "kind": "no_payment_pages"
          }
        ]
      }
    ],
    "evidence": {
      "scripts": [
        {
          "status": "unreviewed",
          "coverage": "protected"
        }
      ]
    },
    "plan": {
      "current": "free"
    }
  }
}

Headers

RateLimit-Limit

integer

The budget nearest to running out, per minute.

RateLimit-Remaining

integer

What is left of that budget this minute.

RateLimit-Reset

integer

Seconds until that budget starts again.

400

A parameter was refused, or one the operation does not take was sent. The message names it.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

401

invalid_api_key: no key, or one that is malformed, unknown, revoked or expired. One answer for all of them.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

403

plan_upgrade_required: the tenant’s plan does not include API access (the key works again when it does), or does not include what this operation reads.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

404

No such resource in your tenant.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

429

rate_limited: over a budget. Wait Retry-After seconds.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.

503

rate_limit_unavailable or upstream_unavailable: HeaderHawk could not serve this now. Nothing is wrong with the request; try again after Retry-After seconds.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.