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": "[email protected]",
  "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

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.

Last updated