Report an Account Update

info

This endpoint is available on request. Contact support@pinch.ai to enable it on your account.

Call /v1/evaluate/account whenever a customer makes a sensitive change to their account. These changes are the most common indicator that an account has been taken over — a legitimate attacker logs in (perhaps even passing your normal auth) and then immediately changes the email, password, or payment instrument to lock out the real owner before draining loyalty points or running fraudulent orders.

Request

POST /v1/evaluate/account HTTP/1.1
Host: api.pinch.ai
Authorization: {api-key}
Content-Type: application/json

Body

Field	Type	Required	Description
`providerCustomerId`	string	yes	Your `customerId`.
`changeType`	string	yes	What changed. See enum below.
`previousValue`	string	no	Hashed or redacted previous value, when available.
`newValue`	string	no	Hashed or redacted new value.
`siteDomain`	string	yes	Domain where the change happened.
`deviceFingerprints`	array	recommended	`[{ "deviceIdentifier": "{visitorId}" }]`.
`timestamp`	string	yes	Epoch milliseconds as a string.

`changeType` enum

Value	Description
`PASSWORD_CHANGE`	Customer changed their password.
`EMAIL_CHANGE`	Primary email on the account changed.
`PHONE_CHANGE`	Primary phone or 2FA phone changed.
`PAYMENT_METHOD_ADD`	New payment instrument added (card, ACH, etc.).
`PAYMENT_METHOD_REMOVE`	Existing payment instrument removed.
`PAYOUT_ADD`	New payout destination added (relevant for marketplaces, gift card resale).
`PAYOUT_CHANGE`	Existing payout destination modified.
`MFA_DISABLE`	Two-factor authentication turned off.
`MFA_METHOD_CHANGE`	2FA method or device changed.
`ADDRESS_ADD`	New shipping address added.
`LOYALTY_REDEMPTION`	Loyalty points redeemed (treat as sensitive on accounts with large balances).

Do not send the literal old and new values for credentials. For email/phone changes, sending the new value can be helpful; for passwords, send a hash or just "redacted".

Example request

curl
Node
Python

curl https://api.pinch.ai/v1/evaluate/account \
  -H "Authorization: $PINCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerCustomerId": "user_12345abcde",
    "changeType": "EMAIL_CHANGE",
    "previousValue": "johndoe@example.com",
    "newValue": "newjohndoe2026@example.com",
    "siteDomain": "demostore.com",
    "deviceFingerprints": [{ "deviceIdentifier": "abc123visitorId" }],
    "timestamp": "'"$(date +%s)000"'"
  }'

await fetch("https://api.pinch.ai/v1/evaluate/account", {
  method: "POST",
  headers: {
    Authorization: process.env.PINCH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    providerCustomerId: customerId,
    changeType: "PASSWORD_CHANGE",
    previousValue: "redacted",
    newValue: "redacted",
    siteDomain: "demostore.com",
    deviceFingerprints: [{ deviceIdentifier: visitorId }],
    timestamp: String(Date.now()),
  }),
});

import os, requests, time

requests.post(
    "https://api.pinch.ai/v1/evaluate/account",
    headers={
        "Authorization": os.environ["PINCH_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "providerCustomerId": customer_id,
        "changeType": "PAYOUT_ADD",
        "newValue": "acct_****1234",
        "siteDomain": "demostore.com",
        "deviceFingerprints": [{"deviceIdentifier": visitor_id}],
        "timestamp": str(int(time.time() * 1000)),
    },
)

Response

{
  "providerAccountEventId": "evt_8f3a2c",
  "pinchAccountEventId": "pacc_1d2e3f",
  "Decisions": [
    {
      "decisions": [
        {
          "decisionType": "APPROVE/DECLINE/REVIEW",
          "decision": "REVIEW",
          "subDecision": "Suspect ATO",
          "decisionReason": "Email change from a device that has never been associated with this account",
          "abuseScore": 72
        }
      ]
    }
  ]
}

Decision semantics

Decision	Recommended action
`APPROVE`	Apply the change normally.
`DECLINE`	Roll back the change and notify the legitimate account owner via their previous email/phone. Lock the account pending verification.
`REVIEW`	Apply the change but require step-up verification — send a confirmation email to the previous address with a "you can undo this" link valid for 24 hours. Also: alert your fraud team.

For payout additions and MFA disables, consider treating any non-APPROVE as a hard block until manually cleared. These are the highest-stakes changes.

Common patterns detected

Classic ATO follow-through — successful login from a new device, then EMAIL_CHANGE and PASSWORD_CHANGE within minutes
Refund-to-new-payment attacks — PAYMENT_METHOD_ADD from a new device, followed by a high-value refund request to that new instrument
Marketplace payout drain — PAYOUT_ADD from a new device on a seller account with pending balance
MFA strip — MFA_DISABLE is rare in normal usage; treat as suspicious unless paired with a fresh successful MFA challenge

Errors

HTTP	Code	Meaning
400	`invalid_request`	Required field missing
403	`endpoint_not_enabled`	Account update endpoint not enabled on your account — contact support
422	`unprocessable_entity`	`changeType` not in enum

Request​

Body​

changeType enum​

Example request​

Response​

Decision semantics​

Common patterns detected​

Errors​

See also​