Persons API Reference

Persons

For instructions on how to authenticate to use this endpoint, see API overview.

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Endpoints

`GET`	`/api/projects/:project_id/persons/`
`GET`	`/api/projects/:project_id/persons/:id/`
`PATCH`	`/api/projects/:project_id/persons/:id/`
`DELETE`	`/api/projects/:project_id/persons/:id/`
`GET`	`/api/projects/:project_id/persons/:id/activity/`
`POST`	`/api/projects/:project_id/persons/:id/delete_property/`
`GET`	`/api/projects/:project_id/persons/:id/properties_timeline/`
`POST`	`/api/projects/:project_id/persons/:id/split/`
`POST`	`/api/projects/:project_id/persons/:id/update_property/`
`GET`	`/api/projects/:project_id/persons/activity/`
`POST`	`/api/projects/:project_id/persons/bulk_delete/`
`GET`	`/api/projects/:project_id/persons/cohorts/`
`GET`	`/api/projects/:project_id/persons/funnel/`
`POST`	`/api/projects/:project_id/persons/funnel/`
`GET`	`/api/projects/:project_id/persons/funnel/correlation/`
`POST`	`/api/projects/:project_id/persons/funnel/correlation/`
`GET`	`/api/projects/:project_id/persons/lifecycle/`
`GET`	`/api/projects/:project_id/persons/path/`
`POST`	`/api/projects/:project_id/persons/path/`

List all persons

You can also use the query endpoint to retrieve persons. It enables you to use SQL to query the persons table.

Required API key scopes

person:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

distinct_id
string
Filter list by distinct id.
email
string
Filter persons by email (exact match)
format
string
One of: "csv""json"
limit
integer
Number of results to return per page.
offset
integer
The initial index from which to return the results.
properties
array
Filter Persons by person properties.
search
string
Search persons, either by email (full text search) or distinct_id (exact match).

Response

Request

GET /api/projects/:project_id/persons

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/

Response

Status 200

RESPONSE

{
  "next": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "previous": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "count": 400,
  "results": [
    {
      "id": 0,
      "name": "string",
      "distinct_ids": [
        "string"
      ],
      "properties": null,
      "created_at": "2019-08-24T14:15:22Z",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
    }
  ]
}

Retrieve persons

Required API key scopes

person:read

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/

Response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Update persons

It is better to use the capture API to update person properties.

This endpoint functionally captures a $set event with a $set property key along with the property values you want to update.

Required API key scopes

person:write

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Response

Request

PATCH /api/projects/:project_id/persons/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/\
	-d name="string"

Response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Delete persons

This is the main way to delete data in PostHog.

To learn more, see our data deletion docs.

Use this endpoint to delete individual persons. For bulk deletion, use the bulk_delete endpoint instead.

Required API key scopes

person:write

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

delete_events
boolean
If true, a task to delete all events associated with this person will be created and queued. The task does not run immediately and instead is batched together and at 5AM UTC every Sunday
format
string
One of: "csv""json"

Request

DELETE /api/projects/:project_id/persons/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/

Response

Status 204 No response body

Retrieve persons activity retrieve

Required API key scopes

activity_log:read

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/:id/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/activity/

Response

Status 200 No response body

Create persons delete property

It is better to use the capture API to change person properties.

This endpoint functionally captures a $delete_person_property event with an $unset property key along with the property value you want to delete.

Required API key scopes

person:write

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

$unset
string
Specify the property key to delete
format
string
One of: "csv""json"

Request parameters

properties

Request

POST /api/projects/:project_id/persons/:id/delete_property

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/delete_property/\
	-d name="string"

Response

Status 200 No response body

Retrieve persons properties timeline

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/:id/properties_timeline

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/properties_timeline/

Response

Status 200 No response body

Create persons split

Required API key scopes

person:write

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Request

POST /api/projects/:project_id/persons/:id/split

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/split/\
	-d name="string"

Response

Status 200 No response body

Create persons update property

It is better to use the capture API to update person properties.

This endpoint functionally captures a $set event with a $set property key along with the property value you want to update.

Required API key scopes

person:write

Path parameters

id
integer
A unique integer value identifying this person.
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"
key
string
Specify the property key
value
Specify the property value

Request parameters

properties

Request

POST /api/projects/:project_id/persons/:id/update_property

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/:id/update_property/\
	-d name="string"

Response

Status 200 No response body

Retrieve persons activity

Required API key scopes

activity_log:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/activity/

Response

Status 200 No response body

Create persons bulk delete

This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs. You can pass in a maximum of 1000 IDs per call.

Required API key scopes

person:write

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

delete_events
boolean
If true, a task to delete all events associated with this person will be created and queued. The task does not run immediately and instead is batched together and at 5AM UTC every Sunday
distinct_ids
object
A list of distinct IDs, up to 100 of them. We'll delete all persons associated with those distinct IDs.
format
string
One of: "csv""json"
ids
object
A list of PostHog person IDs, up to 100 of them. We'll delete all the persons listed.

Request parameters

properties

Request

POST /api/projects/:project_id/persons/bulk_delete

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/bulk_delete/\
	-d name="string"

Response

Status 200 No response body

Retrieve persons cohorts

Required API key scopes

person:readcohort:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/cohorts

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/cohorts/

Response

Status 200 No response body

Retrieve persons funnel

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/funnel

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/funnel/

Response

Status 200 No response body

Create persons funnel

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Request

POST /api/projects/:project_id/persons/funnel

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/funnel/\
	-d name="string"

Response

Status 200 No response body

Retrieve persons funnel correlation

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/funnel/correlation

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/funnel/correlation/

Response

Status 200 No response body

Create persons funnel correlation

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Request

POST /api/projects/:project_id/persons/funnel/correlation

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/funnel/correlation/\
	-d name="string"

Response

Status 200 No response body

Retrieve persons lifecycle

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/lifecycle

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/lifecycle/

Response

Status 200 No response body

Retrieve persons path

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request

GET /api/projects/:project_id/persons/path

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/path/

Response

Status 200 No response body

Create persons path

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Request

POST /api/projects/:project_id/persons/path

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/persons/path/\
	-d name="string"