Persons-2 API Reference

Persons-2

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

Endpoints

`POST`
`POST`
`POST`
`GET`
`GET`
`GET`
`POST`
`GET`
`POST`
`GET`

Create environments persons batch by distinct ids

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_distinct_ids
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/environments/:environment_id/persons/batch_by_distinct_ids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_distinct_ids/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons batch by distinct ids

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_distinct_ids
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/environments/:environment_id/persons/batch_by_distinct_ids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_distinct_ids/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons batch by uuids

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_uuids
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/environments/:environment_id/persons/batch_by_uuids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_uuids/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons batch by uuids

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_uuids
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/environments/:environment_id/persons/batch_by_uuids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_uuids/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments 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. Only events captured before the request will be deleted.

Required API key scopes

person:write

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

ids
array
distinct_ids
array
delete_events
boolean
Default: false
delete_recordings
boolean
Default: false
keep_person
boolean
Default: false

Response

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/bulk_delete/\
	-d ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/bulk_delete/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 202

RESPONSE
{
  "persons_found": 0,
  "persons_deleted": 0,
  "events_queued_for_deletion": true,
  "recordings_queued_for_deletion": true,
  "deletion_errors": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Create environments persons bulk delete

Required API key scopes

person:write

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

ids
array
distinct_ids
array
delete_events
boolean
Default: false
delete_recordings
boolean
Default: false
keep_person
boolean
Default: false

Response

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/bulk_delete/\
	-d ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/bulk_delete/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 202

RESPONSE
{
  "persons_found": 0,
  "persons_deleted": 0,
  "events_queued_for_deletion": true,
  "recordings_queued_for_deletion": true,
  "deletion_errors": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Retrieve environments persons cohorts

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.

Required API key scopes

person:readcohort:read

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"
person_id
string

Example request

GET /api/environments/:environment_id/persons/cohorts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/cohorts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/cohorts/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments persons cohorts

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.

Required API key scopes

person:readcohort:read

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"
person_id
string

Example request

GET /api/environments/:environment_id/persons/cohorts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/cohorts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/cohorts/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

List all environments persons deletion status

List the status of queued event deletions for persons. When you delete a person with delete_events=true, an async deletion is queued. Use this endpoint to check whether those deletions are still pending or have been completed.

Required API key scopes

person:read

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"
limit
integer
offset
integer
person_uuid
string
status
string
One of: "all""completed""pending"

Response

Example request

GET /api/environments/:environment_id/persons/deletion_status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/deletion_status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/deletion_status/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example 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": [
    {
      "person_uuid": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "status": "string",
      "delete_verified_at": "2019-08-24T14:15:22Z"
    }
  ]
}

List all environments persons deletion status

Required API key scopes

person:read

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"
limit
integer
offset
integer
person_uuid
string
status
string
One of: "all""completed""pending"

Response

Example request

GET /api/environments/:environment_id/persons/deletion_status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/deletion_status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/deletion_status/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example 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": [
    {
      "person_uuid": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "status": "string",
      "delete_verified_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve environments persons funnel

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/funnel/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments persons funnel

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/funnel/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons funnel

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/funnel/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons funnel

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/funnel/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments persons funnel correlation

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_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/environments/:environment_id/persons/funnel/correlation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/correlation/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments persons funnel correlation

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_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/environments/:environment_id/persons/funnel/correlation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/correlation/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons funnel correlation

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/funnel/correlation/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/correlation/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons funnel correlation

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_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/environments/:environment_id/persons/funnel/correlation/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/correlation/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments persons lifecycle

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/lifecycle
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/lifecycle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/lifecycle/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments persons lifecycle

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.

Path parameters

environment_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/lifecycle
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/lifecycle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/lifecycle/".format(
        project_id=project_id,
		environment_id="<the environment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()