Skip to main content

Customer 360 & Profiles API Specification

This specification documents the REST API endpoints, request parameters, JSON response models, and masking algorithms powering the Profiles Directory and Customer 360 Profile views in DriveMetaData.

1. Profiles Directory API (GET /api/v2/customers/profiles)​

Retrieves paginated, filterable customer profile records for the directory grid at /profiles.

Request Parameters​

GET /api/v2/customers/profiles?limit=25&offset=0&search=arjun&status=Ready&consent=Ready&sortBy=identityQuality&sortDirection=desc HTTP/1.1
Host: api.dmd.io
Authorization: Bearer <JWT_TOKEN>
Client-ID: 34507
Workspace-ID: 34509
Query ParameterTypeRequiredDescription
limitintegerNoNumber of records to return (default: 25, max: 100).
offsetintegerNoPagination offset index (default: 0).
searchstringNoSubstring match across customer name, email, phone, or DMD UID.
statusstringNoFilter by profile status: Ready, Needs enrichment, or Policy review.
consentstringNoFilter by consent tier: Ready, Limited, or Review.
channelstringNoFilter by active reachability channel: email, mobile, or device.
sortBystringNoSort column: identityQuality, lastSeen, engagementScore, or events.
sortDirectionstringNoSort direction: asc or desc (default: desc).

Response Schema (data[0])​

{
  "summary": {
    "totalProfiles": 245678,
    "reachableEmail": 123456,
    "reachableMobile": 98765,
    "anonymous": 23457
  },
  "pagination": {
    "limit": 25,
    "offset": 0,
    "totalRecords": 1
  },
  "profiles": [
    {
      "id": "usr-101",
      "name": "Arjun Sharma",
      "email": "[email protected]",
      "avatar": "AS",
      "avatarTone": "success",
      "channel": "Email, mobile, +1",
      "channelIcon": "email",
      "identityQuality": 94,
      "engagement": "High",
      "engagementScore": 85,
      "events": 24,
      "consent": "Ready",
      "status": "Ready",
      "priority": "P1",
      "owner": "Lifecycle",
      "nextAction": "Add now",
      "recommendedAudience": "High intent shoppers",
      "source": "Meta Ads",
      "matchReason": "Missing purchase recency rule",
      "lastSeen": "2026-05-08T14:45:00Z"
    }
  ]
}

2. Customer 360 Profile API (GET /api/v2/customers/{id}/profile)​

Retrieves the consolidated customer profile dossier for /customer-360-profile/[customerId].

Request Specification​

GET /api/v2/customers/usr-101/profile HTTP/1.1
Host: api.dmd.io
Authorization: Bearer <JWT_TOKEN>
Client-ID: 34507
Workspace-ID: 34509
X-Audience-PII-Access: true

Complete Response Schema (data[0])​

{
  "customer": {
    "customerId": "CUST-98421",
    "dmdUid": "usr-101",
    "name": "Arjun Sharma",
    "initials": "AS",
    "email": "[email protected]",
    "phone": "+91 98765 43210",
    "firstSeen": "12 Jan 2025",
    "lastSeen": "08 May 2026, 2:45 PM"
  },
  "statuses": [
    { "label": "Verified Buyer", "tone": "success" },
    { "label": "High LTV Tier", "tone": "primary" }
  ],
  "metrics": [
    { "label": "Lifetime Value", "value": "₹42,500", "tone": "success" },
    { "label": "Total Orders", "value": "8", "tone": "primary" },
    { "label": "Avg. Order Value", "value": "₹5,312", "tone": "neutral" },
    { "label": "Engagement Score", "value": "85 / 100", "tone": "info" }
  ],
  "revenueQuality": [
    {
      "label": "Purchase Frequency",
      "value": "Every 28 days",
      "tone": "success",
      "detail": "Top 5% of customer cohort"
    },
    {
      "label": "Gross Margin Contribution",
      "value": "64.2%",
      "tone": "primary",
      "detail": "Low return rate (<2%)"
    }
  ],
  "dataFreshness": [
    { "label": "Shopify Commerce Sync", "value": "Synced 5 mins ago", "icon": "globe" },
    { "label": "Mobile SDK Event Stream", "value": "Real-time active", "icon": "phone" },
    { "label": "Identity Graph Confidence", "value": "94% Deterministic", "icon": "hash" }
  ],
  "journey": [
    {
      "id": "evt-1001",
      "type": "ORDER",
      "date": "08 May 2026, 2:30 PM",
      "title": "Completed Order #ORD-7712",
      "description": "Purchased 2 items worth ₹7,499 via UPI checkout.",
      "tone": "success"
    },
    {
      "id": "evt-1002",
      "type": "CAMPAIGN",
      "date": "08 May 2026, 1:15 PM",
      "title": "Clicked WhatsApp Abandoned Cart Link",
      "description": "Inbound touchpoint from campaign 'Summer_Sale_Recovery'.",
      "tone": "primary"
    }
  ],
  "attribution": {
    "firstTouch": {
      "label": "First Touch Attribution",
      "source": "Google Ads",
      "campaign": "Search_Brand_Core",
      "medium": "cpc",
      "content": "Headline_Variant_A",
      "term": "buy shoes online",
      "publisherId": "google_search",
      "tone": "primary"
    },
    "lastTouch": {
      "label": "Last Touch Attribution",
      "source": "WhatsApp",
      "campaign": "Cart_Recovery_30D",
      "medium": "messaging",
      "content": "Promo_10_Percent",
      "publisherId": "dmd_omnichannel",
      "tone": "success"
    }
  },
  "touchpoints": [
    {
      "id": "tp-01",
      "type": "Paid Search Ad",
      "timestamp": "12 Jan 2025, 10:14 AM",
      "source": "Google Ads",
      "medium": "cpc",
      "campaign": "Search_Brand_Core",
      "interactionType": "Click",
      "device": "Mobile (Android)",
      "matchType": "Exact",
      "credits": {
        "firstTouch": true,
        "lastTouch": false,
        "linear": 0.33,
        "positionBased": 0.40
      },
      "qualitySignals": [
        { "label": "Deterministic", "tone": "success" },
        { "label": "Ad Click Verified", "tone": "primary" }
      ]
    }
  ]
}

3. Dynamic Tab Workbench Data API (POST /api/v2/customers/{id}/dynamic-tabs/{slug}/query)​

Queries granular sub-entity data (Transactions, Sessions, Custom Events) displayed in the dynamic tab workbenches.

Request Payload​

{
  "tabSlug": "transactions",
  "dateRange": ["2026-01-01", "2026-05-31"],
  "filters": [
    {
      "column": "status",
      "operator": "equals",
      "value": "completed"
    },
    {
      "column": "totalAmount",
      "operator": "greaterThan",
      "value": "1000"
    }
  ],
  "limit": 50,
  "offset": 0
}

4. PII Redaction & Masking Algorithms​

When raw PII clearance (X-Audience-PII-Access: true) is absent, the system executes client- and server-side masking functions:

Email Masking​

Preserves the first two characters of the mailbox name, masks the remaining local characters with bullets, and preserves the domain:

Input:  [email protected]
Output: ar••••@gmail.com

Phone Masking​

Masks all digits except for the last 4 characters:

Input:  +91 98765 43210
Output: ••••••3210

Customer Identifier Masking​

Preserves the first 4 characters and final 4 characters, inserting four center bullets:

Input:  usr-10184920
Output: usr-••••4920