Account Protection API Overview
5 min
\<font color="#b6c7cb">\</font> topic type concept purpose explain how the api evaluates risk associated with account activity prior to, during, and outside of a purchase transaction audience api integrators and client developers implementing pre‑transaction fraud prevention applies to clients using the api for account level and identity driven events does not apply to industry‑specific apis, dispute apis, or regulatory‑only apis such as data privacy the api evaluates risk associated with user activity on your website or application , with a focus on account takeover (ato) and new account opening (nao) fraud it is designed to assess risk before a transaction occurs , or in cases where no payment is involved at all operates at the event level each request represents a specific user action—such as a login attempt, password reset, account update, or withdrawal—that should be evaluated for risk at the moment it occurs the api does not take action on accounts directly instead, it returns risk signals and scores that you use to determine how your systems should respond how works account protection architecture data flow at a high level, the flow is a user triggers an event in your application (for example, login or account update) your system submits the event to the api evaluates the event using behavioral signals, historical context, and machine‑learning models the api returns a risk score and supporting details your system decides how to proceed while each request represents a single event, evaluation does not occur in isolation measures consistency, change, and correlation across events over time to identify abnormal behavior that may indicate fraud supported event types the api currently supports the following event types each event type has its own expected context and field requirements, which are documented in the linked event‑specific overview pages accountcreate docid opuuvx5wyxgmqlkwnp 7 accountupdate docid\ bb5ptmhwvnee1vybobcsg login docid\ j1oufkngem49c9r0iuwoa logout docid 5h9ufd7hp1tfiu6du6ddv passwordforgot docid\ j31c2d4egcmelxyup tuo passwordupdate docid\ gtzfcu mrjys 7swyuyjw usernameforgot docid\ aofhg63wbpeqmkebk8cur verification docid\ re89e0j7wlsno40d hccr payment docid\ soon wrdextqcptxz7y9z refund docid\ ghhhzonthcuz3oqlw c2k withdrawal docid\ jeygsgpwnzxlkj6ezhtfk transfer docid\ hfoytz7xk36sv ltkkfe3 inventoryhold docid m1u mertwngwy1xumbdm listingcreate docid\ rkpgqj7qakb8lqfbw4y30 listingupdate docid\ t0cg3jzefoohgenuvv6ko giftcardbalance docid\ hiyhls1ov4pcvtwmcjayj chargeback docid\ uuxisnkfiradxrtdln0kx taking action the api provides decision support , not enforcement using the returned risk score and event details, you determine how your systems respond common response patterns include preventative actions require multi‑factor authentication reset a password block or reject a high‑risk action supportive actions allow one‑click checkout reduce friction for trusted users enable expedited flows for low‑risk activity the appropriate response depends on your business logic, risk tolerance, and regulatory obligations request origin and integration model requests must be submitted from a back‑end system client‑side javascript api submission is not supported this requirement exists because some required data elements are available only from server‑side systems error handling and retry behavior must be controlled centrally requests are accepted only from whitelisted ip addresses certain fields require cryptographic hashing prior to transmission details on authentication, hashing, field classification, and validation behavior are documented in global constraints docid\ hxd7wt2raxtw6nh2h3yn0 field availability and imperative data some account protection fields are labeled imperative , meaning they provide high‑value signals when available imperative fields should be sent whenever your system can legitimately provide them however, there are valid scenarios where an imperative field may be unavailable for a given event in those cases do not suppress the request do not fabricate placeholder values send the event with the available data for example, automated attacks may prevent generation of a device identifier, but the event should still be evaluated using the remaining context refer to global constraints docid\ hxd7wt2raxtw6nh2h3yn0 for full definitions and expectations field hashing prior to sending certain sensitive fields, you must hash the clear text value using our hash algorithm the fields that require hashing are cardnumber giftcardnumber hashedpassword previoushashedpassword updatedhashedpassword refer to hashing requirements docid\ yughwvl8eon7vcgswpcd3 and accertify hash algorithm docid\ rkik1lb6euuwsz3sxpce for more information webhooks and downstream actions includes a set of standard webhooks that allow to notify your systems when follow‑up action is recommended webhooks act as a reverse api, enabling to push messages—such as account‑level actions or payment flags—back to your environment these notifications are commonly used to force password resets trigger verification flows flag or cancel suspicious payments apply account‑level restrictions webhook payloads may reference a single object or multiple related objects, depending on the action taken event references overviews account create docid opuuvx5wyxgmqlkwnp 7 account update docid\ bb5ptmhwvnee1vybobcsg chargeback docid\ uuxisnkfiradxrtdln0kx gift card balance docid\ hiyhls1ov4pcvtwmcjayj inventory hold docid m1u mertwngwy1xumbdm listing create docid\ rkpgqj7qakb8lqfbw4y30 listing update docid\ t0cg3jzefoohgenuvv6ko login docid\ j1oufkngem49c9r0iuwoa logout docid 5h9ufd7hp1tfiu6du6ddv password forgot docid\ j31c2d4egcmelxyup tuo password update docid\ gtzfcu mrjys 7swyuyjw payment docid\ soon wrdextqcptxz7y9z refund docid\ ghhhzonthcuz3oqlw c2k transfer docid\ hfoytz7xk36sv ltkkfe3 username forgot docid\ aofhg63wbpeqmkebk8cur verification docid\ re89e0j7wlsno40d hccr withdrawal docid\ jeygsgpwnzxlkj6ezhtfk field references account create fields https //atlas accertify com/public apis/bcdx account create fields account update fields https //atlas accertify com/public apis/account update fields chargeback fields https //atlas accertify com/public apis/chargeback fields gift card balance fields https //atlas accertify com/public apis/gift card balance fields inventory hold fields https //atlas accertify com/public apis/inventory hold fields listing create fields https //atlas accertify com/public apis/create listing fields listing update fields https //atlas accertify com/public apis/update listing fields login fields https //atlas accertify com/public apis/login fields logout fields https //atlas accertify com/public apis/logout fields password forgot fields https //atlas accertify com/public apis/password forgot fields password update fields https //atlas accertify com/public apis/password update fields payment fields https //atlas accertify com/public apis/payment fields refund fields https //atlas accertify com/public apis/refund fields transfer fields https //atlas accertify com/public apis/transfer fields username forgot https //atlas accertify com/public apis/username forgot fields verification fields https //atlas accertify com/public apis/verification fields withdrawal fields https //atlas accertify com/public apis/withdrawal fields