Profile Blacklist

The Profile Blacklist feature lets you define validation rules that block specific emails, mobile numbers, or names from being created, updated, or imported via the API. When a profile operation is attempted with a blacklisted value, the API returns a 422 error with a descriptive message.

Concepts

Validation Rule

A Validation Rule defines what field to check, how to match against it, and when to apply the check.

Validation Rule Value

A Value is a single entry that the rule matches against. Each rule can have many values. Values default to is_active: false and must be explicitly activated.

Rule Types

Normalisation

Values are normalised before matching to avoid trivial bypasses:

• Email — lowercased and trimmed. [email protected] matches [email protected]
• Mobile — normalised to E.164 format using the phone number library
• Name — lowercased, leading/trailing whitespace trimmed, internal whitespace collapsed to a single space

Applies To

Note: For update and import updates, a field is only checked if its value is actually changing. Sending the existing email in an update payload will not trigger the blacklist.

API Endpoints

Validation Rules

Values

Examples

Block an entire email domain

Create the rule:

POST /profiles/validation-rules
{
  "name": "Block disposable email domains",
  "type": "email",
  "rule_type": "domain",
  "applies_to": "all",
  "error_message": "This email domain is not permitted.",
  "is_active": true
}

Add a domain value and activate it:

POST /profiles/validation-rules/1/values
{
  "value": "mailinator.com",
  "is_active": true
}

Any profile creation or update using an @mailinator.com address will now receive:

{
  "message": "This email domain is not permitted.",
  "errors": {
    "email": ["This email domain is not permitted."]
  }
}

Block specific email addresses

POST /profiles/validation-rules
{
  "name": "Known fraud emails",
  "type": "email",
  "rule_type": "exact",
  "applies_to": "all",
  "is_active": true
}

POST /profiles/validation-rules/2/values
{
  "value": "[email protected]",
  "is_active": true
}

Block mobile number prefixes

POST /profiles/validation-rules
{
  "name": "Block premium rate numbers",
  "type": "mobile",
  "rule_type": "prefix",
  "applies_to": "all",
  "is_active": true
}

POST /profiles/validation-rules/3/values
{
  "value": "+1900",
  "is_active": true
}

Any mobile number starting with +1900 will be blocked.

Block names using regex

POST /profiles/validation-rules
{
  "name": "Block test names",
  "type": "name",
  "rule_type": "regex",
  "applies_to": "create",
  "pattern": "/^test\\s/i",
  "is_active": true
}

No values are needed for regex rules — the pattern field on the rule is used directly.

Inline values on rule creation

You can create a rule and its values in a single request:

POST /profiles/validation-rules
{
  "name": "Block spam domains",
  "type": "email",
  "rule_type": "domain",
  "applies_to": "all",
  "is_active": true,
  "values": [
    { "value": "spam.com", "is_active": true },
    { "value": "trash.com", "is_active": true }
  ]
}

When updating a rule, passing values replaces all existing values. Omitting values leaves them untouched. Passing values: [] removes all values.

Deactivate a single value

PATCH /profiles/validation-rules/1/values/5
{
  "is_active": false
}

Error Response

When a profile operation is blocked, the API returns 422 Unprocessable Entity:

{
  "message": "Cannot create profile with blacklisted contact details",
  "errors": {
    "email": ["Cannot create profile with blacklisted contact details"]
  }
}

The error key matches the offending field (email, mobile_phone, or first_name). The message is either the rule's custom error_message or one of the built-in defaults below.