# People

Source: https://docs.mirafive.io/rest-api/people

> List the people of a MIRA FIVE project with views, segments and person filters, and read one person's profile by ref.

A person is someone the site recognised with consent: a signed-in user, or a browser in [full mode](https://docs.mirafive.io/guides/consent#full-mode). List them as the People screen does, or read one profile by its ref. Traffic collected without consent never becomes people: on such a project the list is empty and `meta.availability` says why.

## List people

```text
GET /api/v1/projects/{project_id}/people
```

People active in the period, 50 per page.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `period` | string | `30d` | `1h`, `24h`, `7d`, `30d`, `90d`, `12m` or `custom`. See [Periods](https://docs.mirafive.io/rest-api#periods). |
| `from` | string | none | First day of a custom period, `YYYY-MM-DD`. **Required** with `period=custom`. |
| `to` | string | none | Last day of a custom period, inclusive. **Required** with `period=custom`. |
| `view` | string | `everyone` | `everyone`; `customers` (bought); `known` (signed in); `high-intent` (showed intent, not bought). |
| `sort` | string | `last_seen` | `last_seen`, `first_seen`, `value` (revenue in the reporting currency) or `visits`. Always descending. |
| `window` | string | none | `all` lists everyone in the retained history instead of the period. Slower. |
| `new` | string | none | `1` keeps only people first seen in the period. |
| `segment` | string | none | A saved segment's id. Keeps only its members. |
| `filters[i][field]`, `filters[i][op]`, `filters[i][value]` | string | none | [Person filters](#person-filters), all of which must hold. At most 12. |
| `cursor` | string | none | `meta.nextCursor` of the previous page. A cursor belongs to one `sort`. |

`compare` is refused.

```bash
curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'view=customers' \
  --data-urlencode 'sort=value' \
  --data-urlencode 'filters[0][field]=first_channel' \
  --data-urlencode 'filters[0][op]=is' \
  --data-urlencode 'filters[0][value]=organic_search'
```

```json title="200 OK"
{
  "data": [
    {
      "id": "0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
      "type": "people",
      "attributes": {
        "name": "Lena Hoffmann",
        "known": true,
        "stage": "customer",
        "firstSeen": "2026-06-14T19:02:11.540+02:00",
        "lastSeen": "2026-09-26T21:47:30.118+02:00",
        "visits": 6,
        "value": [{ "currency": "EUR", "amount": 412.7 }],
        "firstTouch": {
          "channel": "organic_search",
          "source": "google.com",
          "campaign": "",
          "landing": "/products/linen-shirt"
        },
        "country": "DE",
        "device": "desktop",
        "lastPath": "/checkout/thank-you"
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a"
      }
    },
    {
      "id": "01970b2c-3d4e-7f5a-9b6c-7d8e9f0a1b2c",
      "type": "people",
      "attributes": {
        "name": "u_58213",
        "known": true,
        "stage": "customer",
        "firstSeen": "2026-08-30T08:15:42.003+02:00",
        "lastSeen": "2026-09-24T12:31:05.871+02:00",
        "visits": 3,
        "value": [{ "currency": "EUR", "amount": 129 }, { "currency": "CHF", "amount": 89 }],
        "firstTouch": {
          "channel": "organic_search",
          "source": "bing.com",
          "campaign": "",
          "landing": "/"
        },
        "country": "CH",
        "device": "mobile",
        "lastPath": "/account/orders"
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/01970b2c-3d4e-7f5a-9b6c-7d8e9f0a1b2c"
      }
    }
  ],
  "links": {
    "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people?view=customers&sort=value&filters%5B0%5D%5Bfield%5D=first_channel&filters%5B0%5D%5Bop%5D=is&filters%5B0%5D%5Bvalue%5D=organic_search",
    "next": null
  },
  "meta": {
    "period": {
      "preset": "30d",
      "from": "2026-08-29T00:00:00+02:00",
      "to": "2026-09-28T00:00:00+02:00",
      "timezone": "Europe/Berlin",
      "interval": "day",
      "comparison": null,
      "clampedToRetention": false
    },
    "allTime": false,
    "view": "customers",
    "sort": "value",
    "availability": "ready",
    "perPage": 50,
    "nextCursor": null
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The person's ref, a UUID. Pass it to [Get a person](#get-a-person). |
| `attributes.name` | string or null | Their name from identify, or their user id when they gave no name. `null` for a visitor who never signed in. |
| `attributes.known` | boolean | Signed in at least once. |
| `attributes.stage` | string | `customer` (bought), `known` (signed in), `returning` (two visits or more) or `visitor`. |
| `attributes.firstSeen`, `attributes.lastSeen` | string | Their first and latest activity in the retained history. |
| `attributes.visits` | integer | Visits in the period. |
| `attributes.value` | array | Revenue per currency, `{ currency, amount }`, reporting currency first. |
| `attributes.firstTouch` | object or null | How they first came: `channel`, `source` (UTM source, else the referring host), `campaign` and `landing` path. Empty strings where nothing was tagged. |
| `attributes.country` | string | Two-letter country code. |
| `attributes.device` | string | `desktop`, `mobile` or `tablet`. |
| `attributes.lastPath` | string | The last page they viewed. |
| `links.self` | string | The person's profile in the API. |
| `meta.allTime` | boolean | Whether `window=all` was asked for. |
| `meta.view`, `meta.sort` | string | The view and sort used. |
| `meta.availability` | string | `ready`; `consentless_only` (the project collects without consent, so it has nobody to list); `no_sources` (the project has no source yet). |
| `meta.perPage`, `meta.nextCursor` | | See [Pagination](https://docs.mirafive.io/rest-api#pagination). |

### Person filters

People take their own filters, not the [event filters](https://docs.mirafive.io/rest-api#filters) of reports. Each is `filters[i][field]`, `filters[i][op]` and `filters[i][value]`; all must hold. At most 12, and `value` is at most 500 characters.

| Field | Operators | Value |
| --- | --- | --- |
| `stage` | `is`, `is_not` | `customer`, `known`, `returning` or `visitor` |
| `purchase` | `set` (made), `not_set` (not made) | none |
| `goal` | `is` (reached), `is_not` (not reached) | a goal id, from [List goals](https://docs.mirafive.io/rest-api/goals#list-goals) |
| `action` | `is` (done), `is_not` (not done) | an action id |
| `segment` | `is`, `is_not` | a segment id |
| `funnel` | `is` | a step: `{window}:{step}:{reached or stopped}:{action id},{action id},…`, e.g. `7:2:stopped:<id>,<id>` for people who got to step 2 and no further |
| `experiment` | `is` | `{experiment id}:{a or b}`, optionally followed by `:goal` or `:purchase` for those who then reached the deciding goal or bought |
| `first_channel`, `last_channel` | `is`, `is_not` | a channel: `paid_search`, `paid_social`, `email`, `ai_assistant`, `organic_search`, `organic_social`, `campaign`, `referral`, `direct` |
| `first_campaign`, `last_campaign` | `is`, `is_not`, `contains`, `set`, `not_set` | a `utm_campaign` |
| `first_landing`, `last_landing` | `is`, `is_not`, `starts_with`, `contains` | a page path |
| `first_ad_platform`, `last_ad_platform` | `is`, `is_not` | `google_ads` or `meta_ads` |
| `country` | `is`, `is_not` | an upper-case two-letter code, e.g. `DE` |
| `device` | `is`, `is_not` | `desktop`, `mobile` or `tablet` |

The first touch is the visit that first brought a person. The last touch is their latest visit from outside (not `direct`), else their latest visit. `goal`, `action`, `purchase` and `funnel` count within the period. Trait filters (`traits.<key>`) belong to segments and are refused here.

## Get a person

```text
GET /api/v1/projects/{project_id}/people/{ref}
```

One person over their whole retained history. `ref` comes from the list or from an [event](https://docs.mirafive.io/rest-api/events). The ref of a browser that later signed in answers with the person who claimed it, and `id` carries that person's ref.

```bash
curl https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY"
```

```json title="200 OK"
{
  "data": {
    "id": "0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
    "type": "people",
    "attributes": {
      "name": "Lena Hoffmann",
      "email": "lena.hoffmann@example.com",
      "userId": "u_40177",
      "known": true,
      "stage": "customer",
      "firstSeen": "2026-06-14T19:02:11.540+02:00",
      "lastSeen": "2026-09-26T21:47:30.118+02:00",
      "visits": 14,
      "activeDays": 11,
      "events": 236,
      "pageviews": 181,
      "orders": 3,
      "revenue": [{ "currency": "EUR", "amount": 412.7 }],
      "firstTouch": {
        "channel": "organic_search",
        "source": "google.com",
        "campaign": "",
        "landing": "/products/linen-shirt"
      },
      "client": {
        "country": "DE",
        "region": "HH",
        "device": "desktop",
        "browser": "Firefox",
        "os": "macOS",
        "locale": "de-DE"
      },
      "traits": [
        { "key": "plan", "value": "club" },
        { "key": "newsletter", "value": "true" }
      ],
      "browsers": 2,
      "sharedBrowser": false
    },
    "links": {
      "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a"
    }
  }
}
```

It takes no query parameters except [sparse fieldsets](https://docs.mirafive.io/rest-api#sparse-fieldsets). A ref the project does not know gets `404` with `Nobody with this ref within what the plan keeps, or they were erased.`

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The person's current ref. |
| `attributes.name`, `attributes.email`, `attributes.userId` | string or null | What they signed in with, from identify. `null` when never given. |
| `attributes.known` | boolean | Whether they have a user id. |
| `attributes.stage` | string | `customer`, `known`, `returning` or `visitor`. |
| `attributes.firstSeen`, `attributes.lastSeen` | string | First and latest activity. |
| `attributes.visits`, `attributes.activeDays`, `attributes.events`, `attributes.pageviews`, `attributes.orders` | integer | Counts over the retained history. |
| `attributes.revenue` | array | Revenue per currency, `{ currency, amount }`. |
| `attributes.firstTouch` | object or null | `channel`, `source`, `campaign`, `landing` of the visit that first brought them. |
| `attributes.client` | object | `country`, `region` (ISO subdivision code), `device`, `browser`, `os` and `locale`. |
| `attributes.traits` | array | `{ key, value }` of their latest identify traits. |
| `attributes.browsers` | integer | How many browsers are joined to this person. |
| `attributes.sharedBrowser` | boolean | Someone else signed in on one of their browsers. |
| `links.self` | string | This profile's URL in the API. |