Signals and reasons

Understand why a decision was returned and when individual signals matter.

The action tells your signup flow what to do. Reasons and signals show what SignupScore found.

Primary reason

primary_reason is the main reason behind the action. It is OK when no reason applies.

This shortened response says the address was blocked because its domain is a known disposable provider:

Decision example

{
  "action": "block",
  "primary_reason": "DISPOSABLE",
  "reasons": ["DISPOSABLE"],
  "signals": {
    "disposable": true
  }
}

Use primary_reason for a short explanation. Check reasons when more than one fact may matter.

Code	Meaning
`DISPOSABLE`	The domain is a known disposable email provider.
`SUBDOMAIN_OF_DISPOSABLE`	The domain sits below a known disposable provider.
`NO_MX`	No mail exchange records were found when MX checking was enabled.
`SUSPICIOUS`	The address strongly resembles generated junk or a test address.
`ROLE_BASED`	The part before `@` looks like `info`, `admin`, `support`, or another shared role.
`PUBLIC_PROVIDER`	The address uses a public email provider such as Gmail or Yahoo.
`PRIVACY_RELAY`	The domain belongs to a known privacy or alias relay.
`ALIAS_SUBADDRESS`	The part before `@` uses a tag such as `name+trial`.
`DOMAIN_TYPO_SUGGESTED`	The domain resembles a known provider and a correction is available.
`DOMAIN_NEWLY_REGISTERED`	A known registration age is below the account's configured threshold.

The API returns these codes as strings. Use the code in your logic instead of copying the description text.

Signals are simple facts. They help when your product needs an exception beyond the main action.

Signal	Example	What it tells you
`disposable`	`name@tempmail.com`	The domain is a known temporary email provider.
`public_provider`	`name@gmail.com`	The address uses a public provider. This is not bad by itself.
`role_based`	`support@company.com`	The address looks shared by a team or function.
`suspicious`	A strong junk-like pattern	The address needs more confidence before valuable access.
`privacy_relay`	A known relay domain	The service forwards mail to another inbox.
`alias_subaddress`	`name+trial@example.com`	The address uses a tag or subaddress.
`has_mx`	`true`	Mail server records were found for the domain.
`suggested_domain`	`gmail.com`	The entered domain may contain a typo.