User Acquisition Integration

Overview

This document outlines the requirements for Membership Organizations (MOs) to integrate with our Customer Data Platform (CDP) and personalized recommendation system. Our system polls your user profile data 4 times daily to maintain up-to-date user profiles for personalized content recommendations.

---

Polling Schedule

Our system polls your API 4 times per day at:

• 00:00 UTC (Midnight)
• 06:00 UTC (6 AM)
• 12:00 UTC (Noon)
• 18:00 UTC (6 PM)

---

API Requirements

1. API Endpoint Configuration

To enable integration, the membership organization admin must complete the following information in the Settings section of the Membership Organization Portal:

Configuration	Description
Base API URL	Your API's base URL (e.g., https://api.yourmembershiporg.com)
API Key	Authentication key for secure access to your user data
Membership Organization ID	Your unique identifier in our system

2. Required API Endpoints

Your API must implement the following endpoint:

GET /users

• Description: Returns user profile data for all users or users updated since a specific date.

Query Parameters:

Name	Type	Required	Description
limit	integer	Yes	Maximum number of users to return per request (we use 100)
offset	integer	No	Number of users to skip for pagination
from_date	string	No	ISO 8601 datetime for incremental updates (e.g., 2024-01-15T12:00:00Z)

Request Headers:

X-Api-Key: your-api-key
Content-Type: application/json

Response Format:

{
  "users": [
    {
      // User profile data according to schema below
    }
  ],
  "pagination": {
    "total_count": 1500,
    "limit": 100,
    "offset": 0
  }
}

3. Authentication

We support API Key authentication via the X-Api-Key header. Ensure your API key:

• Has read access to user profile endpoints
• Does not expire (or provide advance notice of renewal)
• Is kept secure and not shared publicly

4. Rate Limiting & Performance

Please ensure your API can handle:

• Concurrent requests: Up to 5 requests per second
• Bulk data retrieval: Pagination support for large user bases
• Incremental updates: Support for from_date parameter to retrieve only updated records

---

Data Schema Requirements

Your API must return user data conforming to the following JSON schema:

User Profile Schema

Required Fields

{
  "user_id": "string",           // Unique identifier (alphanumeric, max 128 chars)
  "email": "string",             // Valid email format
  "created_at": "string",        // ISO 8601 datetime
  "updated_at": "string",        // ISO 8601 datetime
  "communication_preferences": {
    "email_opt_in": boolean,
    "sms_opt_in": boolean,
    "push_opt_in": boolean
  }
}

Optional Fields

{
  "phone": "string",             // E.164 format (e.g., +1234567890)
  "birth_date": "string",        // ISO date format (YYYY-MM-DD)
  "device_ids": ["string"],      // Array of device identifiers
  "demographics": {
    "age_range": "string",       // Enum: "18-20", "21-24", "25-29", etc.
    "education_and_occupation": "string", // See full enum list below
    "gender": "string",          // Enum: "Female", "Male", "Other Gender", "Unknown Gender"
    "language": "string",        // Country name (see full enum list below)
    "marital_status": "string",  // Enum: "Co-Habiting", "Married", "Single"
    "income": "string",          // Enum: "$10,000-$14,999", "$15,000-$19,999", etc.
    "location": {
      "country": "string",       // ISO 3166-1 alpha-2 (e.g., "US", "CA")
      "region": "string",        // State/province code (max 3 chars)
      "city": "string",          // City name
      "postal_code": "string",   // ZIP/postal code
      "timezone": "string"       // IANA timezone (e.g., "America/New_York")
    },
    "mo_location": {
      "country": "string",       // Your organization's country
      "region": "string",        // Your organization's state/region
      "city": "string"           // Your organization's city
    }
  },
  "content_preferences": {
    "interests": ["string"],     // Array of interest categories
    "favorite_content_types": ["string"], // Content type preferences
    "preferred_content_length": "string", // "short", "medium", "long"
    "content_frequency": "string" // "daily", "weekly", "monthly"
  }
}

---

Field Enums and Validation

Age Range Options

• 18-20, 21-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75+

Education and Occupation Options

• Primary Education, Secondary Education, College Education, Professional School, Postgraduate Education, Undergraduate Education, Work from Home, Director/Managerial, Homemaker / Domestic Work, Office Worker, Part-Time Worker, Professional, Public Sector, Retired, Self Employed, Shop Worker, Skilled/Manual Work, Student, Unemployed, Employment Sector / Industry, Employed, Part-Time, Full-Time, Self-Employed, Unemployed / Job Seeker

Income Brackets

• $10,000-$14,999, $15,000-$19,999, $20000 - $39999, $40000 - $49999, $50000 - $74999, $75000 - $99999, $100000 - $149999, $150,000-$174,999, $175,000-$199,999, $200,000-$249,999, $250,000+

Interest Categories

• Automotive, Books and Literature, Business and Finance, Careers, Education, Academic Interests, Family and Relationships, Fine Art, Food & Drink, Healthy Living, Hobbies & Interests, Home & Garden, Movies, Music and Audio, News and Politics, Personal Finance, Pets, Pop Culture, Real Estate, Religion & Spirituality, Science, Shopping, Sports, Style & Fashion, Technology & Computing, Television, Travel, Video Gaming

---

Example Complete User Profile

{
  "user_id": "user123",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "birth_date": "1985-06-15",
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "device_ids": ["device1", "device2"],
  "demographics": {
    "age_range": "35-39",
    "education_and_occupation": "Professional",
    "gender": "Male",
    "language": "United States",
    "marital_status": "Married",
    "income": "$75000 - $99999",
    "location": {
      "country": "US",
      "region": "CA",
      "city": "San Francisco",
      "postal_code": "94105",
      "timezone": "America/Los_Angeles"
    },
    "mo_location": {
      "country": "US",
      "region": "NY",
      "city": "New York"
    }
  },
  "communication_preferences": {
    "email_opt_in": true,
    "sms_opt_in": false,
    "push_opt_in": true
  },
  "content_preferences": {
    "interests": ["Technology & Computing", "Business and Finance", "News and Politics"],
    "favorite_content_types": ["article", "video"],
    "preferred_content_length": "medium",
    "content_frequency": "daily"
  }
}