# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dinmo.io/customer-hub/profiles-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.