# Profiles API

### 1 Overview

{% hint style="info" %}
DinMo Profiles API requires the activation of the **Customer Hub** module and the definition of **Profiles** in your workspace.
{% endhint %}

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:

```http
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

```http
GET /v1/profiles/id/{profile_id}
```

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

**Example**

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

**Success 200 Response**

```json
{
  "profile_id": "12345",
  "email": "jane.doe@example.com",
  "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

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

| Parameter   | In   | Example                              | Description                    |
| ----------- | ---- | ------------------------------------ | ------------------------------ |
| `namespace` | path | `email`, `anonymous_id`, `device_id` | Which identifier to search on. |
| `value`     | path | `jane.doe@example.com`               | 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.