1Overview & design principle

The Inspect API answers one question a lead buyer asks at the moment of purchase or onboarding: “Is this record real, and what do you know about it?”

Its guiding principle is one call, everything you need. A buyer never has to chain requests — they name the record and optionally pass hashed PII to be matched, all in a single POST. The response always carries everything: the record (its ID, issue time, expiration, and when you stored it), the account and form that produced the record, a true/false per PII field, and the session — the page, where the visitor was, their network and device, the consent and how it was shown, how they interacted and how the form was filled — so the buyer can decide from one round trip.

2Base URL & versioning

All requests use HTTPS and are versioned in the path.

The API is served on its own api. subdomain, separate from the app and the tracker.

3Authentication

Every request authenticates with an API key, sent as a bearer token. A key is created once, shown once, and pasted into the buyer’s CRM or integration tool. It never expires and can be revoked at any time — revocation takes effect on the next request. Attestio stores only a hash of the key, and records who created it and when it was last used.

Create your key in the dashboard under Settings → API keys; the same key works for Inspect, Store and Integrate. A key acts as the account that created it, and can inspect any record by its record ID (the ID is what proves you were given the record). An unknown record ID returns 404.

Authorization: Bearer atk_live_7f3aQm2Xk9…

A session token from a signed-in dashboard user is also accepted in the same header. A session token can inspect the records that account can open in the dashboard; for integrations, always use an API key.

Testing without writing code

Two ways to make a first call before wiring up an integration:

• Attestio Testing Tool. In the dashboard, open Account settings → API Functions, click Open Attestio Testing Tool and choose the Advertiser Testing Tools tab. Pick Inspect, enter a record ID and, optionally, an email, phone or full name to match (each value is hashed in your browser and sent as email_hash, phone_hash or name_hash), then press Send request. Paste your API key to call the API with it, or leave the key blank to call as your signed-in account. The status, timing and JSON response appear alongside, and the cURL tab gives the equivalent command to copy for a developer.
• Session token. While signed in to the dashboard, the value of the attestio_session cookie is a valid bearer token for the same endpoint. Useful for a quick check from a terminal or API client without minting a key; it expires with the session, so integrations should always use an API key.

A missing or invalid token returns 401. An unknown record returns 404; with a session token, so does a record that account cannot open in the dashboard — identical on purpose, so a token cannot be used to probe which records exist.

4The Inspect endpoint

Request body

Response fields

Always returned complete, in this order. Every timestamp is a *_timestamp field in UTC, ISO 8601 with milliseconds (e.g. 2026-10-20T22:05:34.456Z).

Errors

Every error is one error object with a message saying what went wrong; the HTTP status tells the kind of failure. No record is returned with an error. A request fails for one reason, so one error is returned; if a case ever needs several, they come as an errors array of the same objects.

{
  "error": {
    "message": "Invalid Attestio record ID."
  }
}

5Hashed PII

To check whether an email, a name, or any other field matches what the record captured, you send a hash of the value — never the value itself. For security, raw PII must never cross the wire. The hash is a plain SHA-256 of the normalised value (no salt) — the same hash Attestio’s tracker computes for a masked field at capture — and the server compares it with what it captured. It follows two steps: hash the value on your own machine, then call the API with that hash.

Step 1 — Hash your email

Run this in any terminal. It prints the hash of the email; the email itself is never sent anywhere. Replace the email with the one you want to check.

printf %s "you@example.com" | tr -d ' ' | tr '[:upper:]' '[:lower:]' | shasum -a 256 | awk '{print $1}'

Prefer base64? The same hash, written shorter (44 characters) — either form is accepted:

printf %s "you@example.com" | tr -d ' ' | tr '[:upper:]' '[:lower:]' | openssl dgst -sha256 -binary | base64

Step 2 — Call the Inspect API

Paste the hash from Step 1 into email_hash, set your record ID, and send the request. Your API key is used only as the bearer token that authenticates the call — it is not part of the hash, so any key on the account gives the same result. Non-developers can simply paste a key into the Authorization header.

curl -X POST https://api.attestio.com/v1/inspect \
  -H "Authorization: Bearer atk_live_7f3aQm2Xk9…" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "A7guruOFQQKvUK-vHAGx4w",
    "email_hash": "PASTE_YOUR_HASH"
  }'

Step 3 — Read the response

The call always returns the complete response (field by field in §4), with true or false per PII field you sent. The stored value is never returned. For example:

{
  "record": {
    "id": "A7guruOFQQKvUK-vHAGx4w",
    "issued_timestamp": "2026-10-20T22:05:35.210Z",
    "expiration_timestamp": "2026-10-27T22:05:35.210Z"
  },
  "account": { "id": "obLD1OX2obLD1OX2", "name": "Affiliate A" },
  "form": { "id": "nXj8yUJWTzoqLcir", "name": "Long Form" },
  "pii_match": { "email": true },
  "session": {
    "begin_timestamp": "2026-10-20T22:02:12.123Z",
    "end_timestamp": "2026-10-20T22:05:34.456Z",
    "duration": 202.333,
    "age": 65,
    "page": {
      "url": "https://quotes.example.com/long-form/",
      "referrer": "https://www.google.com/",
      "frame": "top-level"
    },
    "geo": {
      "city": "Atlanta",
      "region": "GA",
      "country": "US"
    },
    "network": {
      "ip": "203.0.113.24",
      "ip_network": "unrecognized",
      "vpn_detected": false
    },
    "device": {
      "type": "desktop",
      "browser": "Chrome 155",
      "os": "macOS",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
      "viewport_width": 1512,
      "viewport_height": 827,
      "headless_browser": false
    },
    "consent": {
      "text": "By clicking Submit, I agree to be contacted…",
      "detected": true,
      "font_size_px": 12,
      "contrast_ratio": 7.21,
      "placement": "in_viewport",
      "above_submit": true
    },
    "interaction": {
      "events_recorded": 412,
      "mouse_events": 14,
      "mouse_clicks": 10,
      "keypresses": 22,
      "cursor_distance_px": 7517
    },
    "behavior": {
      "verdict": "normal",
      "input_method": { "prefilled": 0, "manual": 60, "autofill": 40, "paste": 0 },
      "typing_speed_wpm": 38,
      "fields_completed": 6,
      "fields_total": 6,
      "backtracking": false
    }
  }
}

Here your account does not store the record, so expiration_timestamp is 7 days after it was issued and there is no stored_timestamp. While your account stores it, expiration_timestamp is when your store ends instead, and stored_timestamp says when that store began:

"record": {
  "id": "A7guruOFQQKvUK-vHAGx4w",
  "issued_timestamp": "2026-10-20T22:05:35.210Z",
  "expiration_timestamp": "2031-10-21T22:10:00.000Z",
  "stored_timestamp": "2026-10-20T22:10:00.000Z"
}

The recipe

Every hash is computed the same way. The Attestio Testing Tool and any client must match it exactly:

hash = SHA256( normalize(field, value) )   # send as hex (64 chars, any case) or base64 (43/44 chars), no salt

How to use it. For each field you want matched:

• 1. Normalise the value with the field’s rule from the table below.
• 2. SHA-256 the normalised value and write the digest as hex (64 characters, any letter case) or base64 (43 or 44 characters, standard or URL-safe) — whichever your tools produce. Do not add a salt or your API key — the key authenticates in the Authorization header only. (Attestio stores masked fields as this same hash, protected server-side with a secret pepper, which is why the hash you send must be the plain one.)
• 3. Send it as "<field>_hash": "<hash>" — e.g. "email_hash" — one entry per field.

Accepted hash formats

The same hash can be written several ways; all of these are accepted and give the same result. This is SHA-256("jane@example.com") — send whichever your tools produce:

We tell them apart by length (64 = hex, 43/44 = base64), so you never say which one you used. Anything else — including the plain value — is rejected with 400.

Normalisation per field

Apply the field’s rule to the value before hashing, so trivially-different spellings still match. Both the caller and the server use these exact rules.

1Overview & the store model

A record reaches you one of two ways: a publisher issues it to you, or someone shares it with you. Before you act on it, you inspect it — confirm it is genuine, that the consent was shown, and that its details match your own data on the lead. Once you are satisfied it is real, you store it.

Storing is the deliberate act of taking possession. Its guiding principle is inspect to trust, store to keep. A single POST confirms the record and writes an entry showing that your account stored this record, at this moment, kept for as long as you choose — or your account’s default period (5 years unless your account changed it). That entry is the record’s chain of custody.

2Base URL & versioning

All requests use HTTPS and are versioned in the path. Breaking changes ship under a new major version; additive fields do not.

The Store API shares the Inspect API’s host and key — it is served on the same api. subdomain, separate from the app and the tracker.

3Authentication

Every request authenticates with an API key, sent as a bearer token — the same key you use for Inspect. A key is created once, shown once, and pasted into the buyer’s CRM or integration tool. It never expires and can be revoked at any time — revocation takes effect on the next request. Attestio stores only a hash of the key, and records who created it and when it was last used.

Create your key in the dashboard under Settings → API keys. A key acts as the account that created it: every store is logged against that account, so always use a key from your own account.

Any account holding a record’s ID may store it — the ID is what proves you were given the record. An unknown ID returns 404, so IDs cannot be probed. Storing is non-exclusive — any number of accounts may store the same record, and every store is logged separately.

Authorization: Bearer atk_live_7f3aQm2Xk9…

A signed session token (the JWT Attestio issues at login) is also accepted in the same header, so a record can be stored from an authenticated session without creating a key.

A missing or invalid token returns 401. A key limited to the Inspect API (an older single-purpose key) returns 403. An unknown record returns 404, so tokens cannot be used to probe for which records exist. A malformed body returns 400. Every error is one error object with a message (see §4).

4The Store endpoint

Storing takes the record to store and, optionally, how long to keep it: expiration_in_days or expiration_timestamp — never both. Send neither and your account’s default store period applies (5 years for a new account; change it in Settings → API keys). Any new value replaces the old one, longer or shorter. There are no sections to select — reading the record’s data (metadata, consent, the captured fields, PII matching) is the Inspect API’s job, and you do that before you store. Store does one thing: note that you have taken possession.

Request body

Call it with cURL

Set your record ID and send the request. Your API key is the bearer token that authenticates the call. Non-developers can simply paste a key into the Authorization header.

curl -X POST https://api.attestio.com/v1/store \
  -H "Authorization: Bearer atk_live_7f3aQm2Xk9…" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "fyqJkSSJRNub0RxVxe8Wdw",
    "expiration_in_days": 365
  }'

Or until a date — or send neither to use your account’s default period:

{
  "record_id": "fyqJkSSJRNub0RxVxe8Wdw",
  "expiration_timestamp": "10-10-2030"
}

What it returns

The call returns the record object — the same one the Inspect API returns — now with stored_timestamp. Its presence is your confirmation that the store went through. It does not re-send the record’s data; that is read on inspect. Every timestamp is a *_timestamp field in UTC, ISO 8601 with milliseconds.

{
  "record": {
    "id": "fyqJkSSJRNub0RxVxe8Wdw",
    "issued_timestamp": "2026-08-26T20:43:25.123Z",
    "expiration_timestamp": "2031-10-07T14:12:09.481Z",
    "stored_timestamp": "2026-10-06T14:12:09.481Z"
  }
}

When the call ends your store ("expiration_in_days": 0 or a past date in expiration_timestamp), the record shows the store that just ended: expiration_timestamp is the moment it ended. Inspect then treats the record as not stored. If you had no store to end, the record comes back without stored_timestamp.

{
  "record": {
    "id": "fyqJkSSJRNub0RxVxe8Wdw",
    "issued_timestamp": "2026-08-26T20:43:25.123Z",
    "expiration_timestamp": "2026-11-02T09:30:00.000Z",
    "stored_timestamp": "2026-10-06T14:12:09.481Z"
  }
}

Errors

Every error is one error object with a message saying what went wrong; the HTTP status tells the kind of failure. No record is returned with an error. A request fails for one reason, so one error is returned; if a case ever needs several, they come as an errors array of the same objects.

{
  "error": {
    "message": "Invalid Attestio record ID."
  }
}

5The store receipt & chain of custody

Every successful store writes one row to the record’s chain of custody: which account stored which record, and when. That row is the point of the endpoint — it is what the account, and if it ever comes to it a court, reads as “who took possession of this evidence.” The record in the response reflects that row: stored_timestamp is when it was written and expiration_timestamp is until when it keeps the record for you.

Storing is idempotent: if your account has already stored this record, a repeat call returns the same stored_timestamp rather than writing a second row. Sending a new expiration_in_days or expiration_timestamp replaces your expiry — longer or shorter. Once your store has ended, storing again starts a new store: stored_timestamp is that new time. Every store and every end is logged, so the full history stays in the chain of custody.

1Overview & the event model

Inspect and Store are calls your system makes. Integrate works the other way round: you tell Attestio once where to send events, and Attestio pushes each one to your system as it happens. No polling, no batch exports.

Its guiding principle is the proof travels with the lead. When a record is stored, your CRM receives the record ID, the store receipt and the consent evidence, ready to attach to the lead it already has.

2Base URL & authentication

All requests use HTTPS and are versioned in the path, on the same host as Inspect and Store.

Every request authenticates with an API key from Settings → API keys, sent as a bearer token. A missing or invalid key returns 401.

Authorization: Bearer atk_live_7f3aQm2Xk9…

3Create an integration

Request body

{
  "integration_id": "Hc2Lp4QwZ8mT1xVb6RkN3g",
  "event": "record.stored",
  "target_url": "https://crm.example.com/hooks/attestio",
  "status": "active",
  "signing_secret": "whsec_…"
}

4Events & delivery payload

Each delivery is a POST to your target_url, with a JSON body like this:

{
  "event": "record.stored",
  "delivery_id": "Qm9Xa2Kp1Lw4Tz8RbN0cVg",
  "record_id": "fyqJkSSJRNub0RxVxe8Wdw",
  "store": { "store_id": "7PF4ibByTPi-SLJHhPRHaA", "stored_timestamp": "2026-10-13T14:12:09.481Z" },
  "consent": { "text": "By clicking Submit, I agree to be contacted…" },
  "form": { "id": "nXj8yUJWTzoqLcir", "name": "Default form" }
}

5Checking delivery signatures

Every delivery carries an X-Attestio-Signature header: an HMAC-SHA256 of the raw request body, keyed with your signing_secret, plus a timestamp. Compute the same HMAC on your side and accept the delivery only if they match and the timestamp is recent.

X-Attestio-Signature: t=1760364729,v1=5b2e9c…

• Respond quickly. Return any 2xx within 10 seconds; do slow work afterwards.
• Retries. If your system doesn’t answer with 2xx, Attestio retries with growing gaps for up to 24 hours.
• Idempotent. A retry repeats the same delivery_id. Store it and ignore duplicates.

6Testing an integration

Sends one sample delivery for the integration’s event to its target_url, marked "test": true, and returns the response your system gave. In the dashboard, the Integrate card’s Send test call does the same.

1Why tag your fields

Tagging tells Attestio exactly which field is which, so advertisers can confirm each lead through the Inspect API. The two attributes do two different jobs:

Use both on one field to name it and hide it. Inspect can still confirm a hidden field by comparing fingerprints.

Never captured. Passwords, file uploads and buttons are left out of the form data, and so are hidden technical fields such as CSRF tokens and TrustedForm or Jornaya certificate IDs. Empty fields are skipped.

2How the tracker works

What the Attestio snippet does with your form, step by step.

1. Every field is captured, tagged or not. Each field is saved under its own name (or id), which is what the certificate shows. Passwords, file uploads, buttons, hidden technical fields and empty fields are left out.

2. It reads the tags live from the page, in this order.

• data-attestio-field="email" (or phone, first-name, …) tells Attestio what the field is.
• data-attestio-mask hides the field. It is kept out of the session replay and the stored form data.
• The older attestio-* classes still work as a fallback, also on a form builder’s wrapper around a single field.
• data-attestio-unmask keeps a field visible and beats every masking rule.

3. No tag: Attestio guesses. It reads the field’s name, id, type and autocomplete. Names like email, phone, first_name, address and state are recognised. A name like field_7 stays unmapped but is still captured.

4. Some fields are hidden automatically. Date of birth, SSN and card fields are hidden by their name or autocomplete, even without a tag, and so is any type turned on under Sensitive fields in the dashboard.

5. A hidden field keeps a fingerprint when its type is known. The type comes from the tag, from Sensitive fields, or from the guess in step 3. The fingerprint (SHA-256) is made in the visitor’s browser before the value is dropped, so the value itself never leaves the page. A hidden field whose type is unknown is hidden with no fingerprint.

6. The tags are sent with the submit. Only the tag names travel, never values. Attestio uses them as the field’s official meaning, so Inspect knows which field is the email, phone or name, whatever the field is called.

7. The record ID is added to the form. A hidden attestio_record_id field carries it to your server, and window.Attestio.getRecordID() returns it. A multi-step form keeps one record ID, and the tags, fingerprints and form data of every step are combined into that one record.

3Tag the contact fields

Add data-attestio-field to the field element itself — the input, select or textarea. Values are lowercase. Your existing classes and attributes stay as they are.

<form action="/submit" method="post">
  <input type="text"  name="fname"  data-attestio-field="first-name">
  <input type="text"  name="lname"  data-attestio-field="last-name">
  <input type="email" name="em"     data-attestio-field="email">
  <input type="tel"   name="ph"     data-attestio-field="phone">

  <input type="text"  name="street" data-attestio-field="address-line1">
  <input type="text"  name="apt"    data-attestio-field="address-line2">
  <input type="text"  name="city"   data-attestio-field="city">
  <select name="st"                data-attestio-field="state">…</select>
  <input type="text"  name="zip"    data-attestio-field="postal-code">

  <button type="submit">Get my quote</button>
</form>

4Hide sensitive fields

Add data-attestio-mask to any field that should never be seen: a Social Security number, card or bank details, date of birth, income. The value is hidden in the visitor’s browser and never reaches the session replay or the form data.

<!-- Hidden. Shows as •••• in the replay and is left out of the form data -->
<input type="text" name="ssn_last4" data-attestio-mask>
<input type="text" name="acct_no"   data-attestio-mask>
<input type="date" name="birthday"  data-attestio-mask>

Name it and hide it. Put both attributes on one field to hide a contact detail and still let advertisers confirm it. Attestio keeps only a fingerprint, under that field’s name.

<!-- Hidden; its fingerprint is kept under "email" for Inspect -->
<input type="email" name="em" data-attestio-field="email" data-attestio-mask>

Matching a masked SSN, date of birth, card or income. Set the field’s type under Forms and Domains → Sensitive fields in the dashboard. Attestio then fingerprints it under that type (ssn, dob, card, income) for the Inspect API. SSN, date of birth and card are switched on by default, so those are fingerprinted without any change; you only need this for income, or if one of the defaults was switched off.

Masked automatically. These fields are hidden even without the attribute:

• autocomplete="bday" and any autocomplete="cc-…" (card) field
• fields whose name or id contains ssn, social, dob, birth, cardnumber or creditcard

Opting out. If one of those is not sensitive on your form, add data-attestio-unmask to it. It beats every other masking rule.

<!-- "social_handle" matches the built-in rule but is not sensitive here -->
<input type="text" name="social_handle" data-attestio-unmask>

5Special cases

Phone split into three boxes. Put the same tag on every box. Attestio joins them, in page order, into one phone number.

<input type="tel" name="phone_area"   maxlength="3" data-attestio-field="phone">
<input type="tel" name="phone_prefix" maxlength="3" data-attestio-field="phone">
<input type="tel" name="phone_line"   maxlength="4" data-attestio-field="phone">

First and last name. Tag each with its own value. When they are masked, the two are joined into one name fingerprint, so an advertiser matches the full name.

<input name="fname" data-attestio-field="first-name" data-attestio-mask>
<input name="lname" data-attestio-field="last-name"  data-attestio-mask>

Consent checkbox and TCPA text. Tag the checkbox the person ticks, and the element that holds the disclaimer, so the record keeps the exact wording they saw.

<label>
  <input type="checkbox" name="agree" data-attestio-field="consent">
  I agree to be contacted.
</label>

<p data-attestio-field="tcpa">
  By clicking "Get my quote", I consent to receive calls and texts from …
</p>

Multi-step forms. Tag the fields on every step. Attestio combines the tags from all steps into one record, so the final record knows every field.

6Your record ID

Every visit Attestio records gets a record ID, a 22-character code such as kq2b7w3m9paXc4TzR1vY0Q. Keep it with the lead in your own system and pass it on to your buyers: it is the ID they use with the Inspect and Store APIs.

In a hidden field, automatically. Attestio adds a hidden field named attestio_record_id to your form. When the form is submitted, the record ID reaches your server or CRM with the rest of the lead. You don’t add this field yourself.

<!-- Added by Attestio; you don't write this -->
<input type="hidden" name="attestio_record_id" value="kq2b7w3m9paXc4TzR1vY0Q">

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const lead = Object.fromEntries(new FormData(form));
  lead.attestio_record_id = window.Attestio?.getRecordID();
  await fetch('/api/leads', { method: 'POST', body: JSON.stringify(lead) });
});