Environments-9

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.

List all environments persons

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
    Click to open
    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/environments/:project_id/persons
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/: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"
    }
  ]
}

List all environments persons

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
    Click to open
    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/environments/:project_id/persons
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/: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 environments 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/environments/: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/environments/: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"
}

Retrieve environments 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/environments/: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/environments/: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 environments persons

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/environments/: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/environments/: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"
}

Update environments persons

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/environments/: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/environments/: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 environments persons

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/environments/: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/environments/:project_id/persons/:id/

Response

Status 204 No response body

Delete environments persons

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/environments/: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/environments/:project_id/persons/:id/

Response

Status 204 No response body

Retrieve environments 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/environments/: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/environments/:project_id/persons/:id/activity/

Response

Status 200 No response body

Retrieve environments 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/environments/: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/environments/:project_id/persons/:id/activity/

Response

Status 200 No response body

Create environments persons delete property

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/environments/: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/environments/:project_id/persons/:id/delete_property/\
	-d name="string"

Response

Status 200 No response body

Create environments persons delete property

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/environments/: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/environments/:project_id/persons/:id/delete_property/\
	-d name="string"

Response

Status 200 No response body

Retrieve environments 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/environments/: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/environments/:project_id/persons/:id/properties_timeline/

Response

Status 200 No response body

Retrieve environments 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/environments/: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/environments/:project_id/persons/:id/properties_timeline/

Response

Status 200 No response body

Create environments 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/environments/: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/environments/:project_id/persons/:id/split/\
	-d name="string"

Response

Status 200 No response body

Create environments 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/environments/: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/environments/:project_id/persons/:id/split/\
	-d name="string"

Response

Status 200 No response body

Create environments persons update property

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/environments/: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/environments/:project_id/persons/:id/update_property/\
	-d name="string"

Response

Status 200 No response body

Create environments persons update property

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/environments/: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/environments/:project_id/persons/:id/update_property/\
	-d name="string"

Response

Status 200 No response body
Next page →

Questions?

Was this page useful?