Profiles API

Deliver real‑time customer context to any digital touchpoint—directly from your warehouse‑native Composable CDP.

1 Overview

DinMo Profiles API requires the activation of the Customer Hub module and the definition of Profiles in your workspace.

DinMo Profiles API is a fully‑managed, low‑latency service that exposes the freshest customer profiles—together with their audience memberships and attribute values—over simple HTTPS endpoints.

Think of it as a composable personalisation layer powered by your warehouse, accessible via simple HTTP calls., purpose‑built for onsite personalisation, experimentation, and decisioning.

Once enabled:

• 🔌 Zero infrastructure to manage—DinMo hosts and scales the fleet.

• ⚡ p99 latency < 30 ms in‑region; sustained throughput 500 RPS, bursts 1 000 RPS.

• 🛡️ All traffic is TLS‑encrypted and requires API‑key authentication.

• 🧩 Data stays composable: you define profile data from your datawarehouse; DinMo automatically refreshes the cache whenever that data changes.

Typical use cases • Dynamic web banners, content blocks, or search results • Feature‑flag evaluation & experimentation • Enriching server‑side events (e.g. product recommendations)

---

2 Key Concepts

We ship with a built-in profiles collection—no need to define custom tables. Each profile is based on a user model and includes:

Term	Description
Identifiers	A field that uniquely locates a profile (e.g. profile_id, email, anonymous_id).
Attributes	Custom key/value pair (string, number, boolean, JSON) attached to a profile.
Audience membership flags	Boolean flag indicating membership in a segment computed in DinMo.
Metrics snapshots	per-profile aggregates from event data

---

3 Architecture (High level)

1. Warehouse → DinMo Refresh Pipeline – You declare a SQL model that returns one row per profile, plus columns for attributes and audience flags.

2. Materialized Cache – DinMo streams the model into a globally distributed, in‑memory database. Refresh cadence can be as low as every 5 minutes.

3. Edge API Layer – HTTPS endpoints served from the region closest to your application.

┌────────────┐   SQL Model  ┌───────────────┐      HTTPS      ┌──────────────┐
│ BigQuery / │  ─────────▶  │ DinMo Cache   │  ◀────────────  │  Front‑end / │
│ Snowflake  │              │ (managed)     │                 │  Back‑end    │
└────────────┘              └───────────────┘                 └──────────────┘

---

4 Getting Started

4.1 Enable the API

• Contact your account manager to activate the Customer Hub module (Enterprise only).

• Pick the serving region: us-east-1, us-west-2, eu-west-1.

• Generate an API Key from Settings → API Keys (shown once).

4.2 Define Your Profiles

• Create a parent model of type Users in DinMo.

• Profiles will automatically be created from this model.

• Include identifiers, attributes, and any fields used in metrics or segmentation.

Once profiles are defined and refreshed, the Profiles API becomes available.

---

5 Authentication

All requests require an API key presented as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

Keys grant read‑only access to all profiles in your workspace. We strongly recommend calling the API from a trusted back‑end or edge function—not directly from browsers or mobile apps.

---

6 Endpoint Reference

Base URL template:

https://personnlization.<region>.dinmo.com

6.1 Get Profile by Primary ID

GET /v1/profiles/id/{profile_id}

Parameter	In	Type	Description
profile_id	path	string	Primary identifier defined in the dataset (e.g. 12345).

Example

curl -H "Authorization: Bearer sk_live_..." \
     "https://personalization.eu-west-1.dinmo.com/v1/profiles/id/12345"

Success 200 Response

{
  "profile_id": "12345",
  "email": "[e-mail]",
  "first_name": "Jane",
  "lifetime_value": 1492.18,
  "_audiences": {
    "high_spenders": true,
    "churn_risk": false
  },
  "_updated_at": "2025-06-10T12:34:56Z"
}

6.2 Get Profile by Secondary Identifier

GET /v1/profiles/identifier/{namespace}/{value}

Parameter	In	Example	Description
namespace	path	email, anonymous_id, device_id	Which identifier to search on.
value	path	[e-mail]	The identifier value.

6.3 Selective Field Retrieval (optional)

Add the query string fields= to limit the payload:

GET /v1/profiles/id/12345?fields=attributes,audiences

Valid tokens: identifiers, attributes, audiences.

---

7 Rate Limits & Quotas

Item	Default	Notes
Requests per second	500 RPS sustained, burst 1 000 RPS (≤ 2 min)	429 on exceed with Retry‑After.
Payload size	≤ 1 MB (recommend ≤ 256 KB)	Larger payloads rejected 413.
Concurrent connections	Unlimited (auto‑scales)

Contact support to raise limits.

---

8 Error Codes

Status	Meaning	Typical Cause
200	OK	Success.
400	Bad Request	Malformed URL or unsupported identifier namespace.
401	Unauthorized	Missing / invalid API key.
404	Not Found	No profile matches the provided identifier.
429	Too Many Requests	Rate limit exceeded.
5xx	Server Error	Temporary DinMo outage—retry with exponential backoff.

---

9 Data Freshness & Deletions

• Automatic updates – Each time your profile dataset refreshes, DinMo writes the changes to the cache within seconds.

• Automatic evictions – If a profile disappears from the source query, it is removed from the cache during the same refresh cycle; subsequent API calls return 404 Not Found.

• SLA – With a 5‑minute refresh cadence, worst‑case staleness is < 5 minutes.