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_events/
    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/
    POST/api/projects/:project_id/persons/reset_person_distinct_id/

    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
      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

    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

    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"

    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
      Default: false

      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"

    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"

    Response

    Status 200 No response body

    Create persons delete events

    Queue deletion of all events associated with this person. The task runs during non-peak hours.

    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"

    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"

    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"

    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"

    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

    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"

    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
      Default: false

      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 1000 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 1000 of them. We'll delete all the persons listed.

    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"

    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"

    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"

    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"

    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"

    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"

    Response

    Status 200 No response body

    Create persons reset person distinct id

    Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.

    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

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

    Response

    Status 200 No response body
    Next page →

    Community questions

    Questions about this page? or post a community question.