Skip to main content

Consent Management

Learn how to properly manage user consents in the Stateless platform.

The Stateless API supports two main types of consent:

Consent for the specific purpose of the form submission (e.g., signing a petition, registering for an event).

Fields:

  • consent_to_primary_purpose: boolean
  • consent_to_primary_purpose_deadline_date: ISO 8601 date string
  • consent_to_primary_purpose_deadline_interval: time interval (e.g., "1y", "30d")

Consent for general marketing and outreach communications.

Email Contact:

  • consent_to_general_contact_email: boolean

Phone Contact:

  • consent_to_general_contact_phone: boolean

Deadline (applies to both):

  • consent_to_general_contact_deadline_date: ISO 8601 date string
  • consent_to_general_contact_deadline_interval: time interval

Every form submission must include at least one granted consent:

{
  "form_id": "newsletter-signup",
  "email": "user@example.com",
  "consent_to_general_contact_email": true
}

If your form submission includes fields beyond basic contact information, you must obtain primary purpose consent:

{
  "form_id": "event-registration",
  "email": "user@example.com",
  "dietary_preferences": "vegetarian",  // Custom field requires primary consent
  "consent_to_primary_purpose": true,
  "consent_to_primary_purpose_deadline_date": "2026-12-31T23:59:59Z"
}

Contact Method Validation​

If you request consent for a contact method, you must provide that contact information:

{
  "form_id": "newsletter",
  "email": "user@example.com",  // Email required when email consent is granted
  "consent_to_general_contact_email": true
}

Consent deadlines specify how long the user's consent is valid. After the deadline, the consent expires.

Deadline Formats​

1. Absolute Date (ISO 8601)​

{
  "consent_to_primary_purpose_deadline_date": "2026-12-31T23:59:59Z"
}

2. Relative Interval​

{
  "consent_to_primary_purpose_deadline_interval": "1y"
}

Supported intervals:

  • Days: "30d", "90d", "180d"
  • Months: "3M", "6M" (30 days per month)
  • Years: "1y", "2y", "5y"

Uses the ms library format.

3. Both Formats​

When both are provided, the earlier deadline is used:

{
  "consent_to_primary_purpose_deadline_date": "2027-12-31T23:59:59Z",
  "consent_to_primary_purpose_deadline_interval": "6M"
}

If the current date plus 6 months is earlier than December 31, 2027, the 6-month deadline is used.

Why Deadlines Matter​

  1. GDPR Compliance: Demonstrates time-limited data processing
  2. Data Minimization: Automatically expires old consents
  3. User Trust: Shows respect for user preferences
  4. Legal Protection: Provides audit trail of consent duration

Newsletter Signup​

{
  "form_id": "newsletter-signup",
  "email": "user@example.com",
  "first_name": "Jane",
  "consent_to_general_contact_email": true,
  "consent_to_general_contact_deadline_interval": "1y"
}

Event Registration with Follow-up​

{
  "form_id": "conference-2026",
  "email": "attendee@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "consent_to_primary_purpose": true,
  "consent_to_primary_purpose_deadline_date": "2026-06-30T23:59:59Z",
  "consent_to_general_contact_email": true,
  "consent_to_general_contact_deadline_interval": "1y",
  "ticket_type": "early_bird"
}

Petition with Optional Communications​

{
  "form_id": "climate-petition",
  "email": "activist@example.com",
  "first_name": "Alex",
  "consent_to_primary_purpose": true,
  "consent_to_primary_purpose_deadline_interval": "2y",
  "consent_to_general_contact_email": true,
  "consent_to_general_contact_phone": true,
  "consent_to_general_contact_deadline_interval": "1y",
  "phone": "+15551234567",
  "street": "123 Main St",
  "city": "Portland",
  "state": "OR",
  "zip": "97201"
}

Survey Response (No Marketing)​

{
  "form_id": "customer-survey",
  "email": "customer@example.com",
  "consent_to_primary_purpose": true,
  "consent_to_primary_purpose_deadline_interval": "90d",
  "satisfaction_rating": 5,
  "feedback": "Great service!"
}
{
  "error": "ValidationError",
  "code": "consent_missing",
  "message": "At least one consent must be granted"
}

Solution: Include at least one consent field set to true.

{
  "error": "ValidationError",
  "code": "consent_to_primary_purpose_missing",
  "message": "Primary purpose consent required when custom fields are present"
}

Solution: Add primary purpose consent when including custom fields.

Email Required​

{
  "error": "ValidationError",
  "code": "consent_to_general_contact_email_missing",
  "message": "Email address required when email consent is granted"
}

Solution: Provide an email address when requesting email consent.

Invalid Deadline​

{
  "error": "ValidationError",
  "code": "consent_to_primary_purpose_deadline_invalid",
  "message": "Invalid deadline format"
}

Solution: Use valid ISO 8601 date or ms library interval format.

Best Practices​

1. Be Transparent​

Clearly explain what each consent type means to the user:

<label>
  <input type="checkbox" name="consent_to_primary_purpose" />
  I agree to have my signature added to the climate petition
</label>

<label>
  <input type="checkbox" name="consent_to_general_contact_email" />
  I want to receive updates about future climate campaigns (optional)
</label>

2. Set Appropriate Deadlines​

Match deadlines to the purpose:

  • Event registration: Until event date + reasonable buffer
  • Newsletter: 1 year (renewable)
  • Petition: 2 years (campaign duration)
  • Survey: 90 days (analysis period)

Don't bundle consents together. Give users granular control:

{
  "consent_to_primary_purpose": true,          // Required for form
  "consent_to_general_contact_email": false    // Optional marketing
}

Track when and how consent was obtained:

{
  "form_id": "newsletter-signup",
  "email": "user@example.com",
  "consent_to_general_contact_email": true,
  "consent_to_general_contact_deadline_interval": "1y",
  "consent_source": "website_footer_form",
  "consent_ip_address": "203.0.113.42",
  "consent_timestamp": "2026-02-04T15:30:00Z"
}

5. Honor Unsubscribes Immediately​

Integrate with the Brevo Unsubscribe API to process opt-outs in real-time.

6. Provide Easy Opt-Out​

Always include unsubscribe links in communications and honor them promptly.

GDPR Compliance​

The Stateless consent management system helps you comply with GDPR requirements:

  1. Freely Given: Users can grant or decline each consent independently
  2. Specific: Different consent types for different purposes
  3. Informed: Clear consent fields map to specific use cases
  4. Unambiguous: Boolean true/false values (no pre-checked boxes)
  5. Time-Limited: Consent deadlines ensure regular re-confirmation
  6. Revocable: Unsubscribe and GDPR anonymization APIs support withdrawal

Test various consent combinations:

# Only primary consent
curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "test",
    "email": "test@example.com",
    "consent_to_primary_purpose": true,
    "consent_to_primary_purpose_deadline_interval": "1y"
  }'

# Only email consent
curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "test",
    "email": "test@example.com",
    "consent_to_general_contact_email": true
  }'

# Both consents
curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "test",
    "email": "test@example.com",
    "consent_to_primary_purpose": true,
    "consent_to_primary_purpose_deadline_date": "2027-12-31T23:59:59Z",
    "consent_to_general_contact_email": true,
    "consent_to_general_contact_deadline_interval": "1y"
  }'