Persons API · Docs | My Journey Analytics

A person is everyone who has sent events to your project, identified by one or more distinct IDs. The persons API reads persons, changes their properties and deletes them.

To create persons or set properties as things happen, send events with $set through the capture API or a library instead.

Reading needs a personal API key with person:read; changes and deletions need person:write.

List and find persons

GET /api/projects/<project ID>/persons/

Parameter	Description
`distinct_id`	The person with this distinct ID
`email`	Persons whose `email` property is exactly this
`search`	Persons whose email, name, person ID or distinct ID contains this text
`limit`, `offset`	Paging, see pagination

bash

curl "https://app.myjourneyanalytics.com/api/projects/12345/persons/?distinct_id=user_123" \
  -H "Authorization: Bearer <personal API key>"

const res = await fetch(
  "https://app.myjourneyanalytics.com/api/projects/12345/persons/?email=jane%40example.com",
  { headers: { Authorization: `Bearer ${process.env.MJ_PERSONAL_API_KEY}` } },
);
const { results } = await res.json();

Each result includes the person's uuid, distinct_ids, properties and created_at.

For lists of persons filtered by behaviour or many properties, a query against the persons table is usually faster.

Get one person

GET /api/projects/<project ID>/persons/<person UUID>/

Use the person's uuid from a list result, not a distinct ID. To look a person up by distinct ID, use the list endpoint with ?distinct_id=.

Update a property

POST /api/projects/<project ID>/persons/<person UUID>/update_property/

bash

curl -X POST https://app.myjourneyanalytics.com/api/projects/12345/persons/<person UUID>/update_property/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "key": "plan", "value": "enterprise" }'

Remove properties

POST /api/projects/<project ID>/persons/<person UUID>/delete_property/

bash

curl -X POST https://app.myjourneyanalytics.com/api/projects/12345/persons/<person UUID>/delete_property/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "$unset": ["phone", "company_size"] }'

$unset takes one property key or a list of them.

Delete persons

POST /api/projects/<project ID>/persons/bulk_delete/

Pass up to 1,000 person UUIDs as ids, or up to 1,000 distinct IDs as distinct_ids (not both):

bash

curl -X POST https://app.myjourneyanalytics.com/api/projects/12345/persons/bulk_delete/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "distinct_ids": ["user_123", "user_456"],
    "delete_events": true,
    "delete_recordings": true
  }'

Field	Description
`ids`	Person UUIDs to delete
`distinct_ids`	Distinct IDs whose persons should be deleted
`delete_events`	`true` to also delete the persons' events
`delete_recordings`	`true` to also delete the persons' session recordings
`keep_person`	`true` to keep the person records and delete only their events and recordings

The response is 202 Accepted with a summary, including persons_found. Deleting events and recordings is queued and happens on a schedule, not straight away, and only covers data captured before the request.

Persons in a cohort

To list the persons in a cohort, see Cohorts API.

Can't find what you need? Contact support