Persons

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

To create or update persons, use a PostHog library of your choice and use an identify call. This API endpoint is only for reading and deleting.

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/
    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/
    GET/api/projects/:project_id/persons/retention/
    GET/api/projects/:project_id/persons/stickiness/
    GET/api/projects/:project_id/persons/trends/
    GET/api/projects/:project_id/persons/values/

    List all persons

    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/projects/:project_id/persons
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/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": {
            "property1": null,
            "property2": null
          },
          "created_at": "2019-08-24T14:15:22Z",
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
        }
      ]
    }

    Retrieve persons

    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/

    Response

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

    Update persons

    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
      object

    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/\
    	-d name="string"

    Response

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

    Delete persons

    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 (controlled by environment variable CLEAR_CLICKHOUSE_REMOVED_DATA_SCHEDULE_CRON)

    • 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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/

    Response

    Status 204 No response body

    Retrieve persons activity retrieve

    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/activity
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/activity/

    Response

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

    Create persons delete property

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/delete_property/\
    	-d name="string"

    Response

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

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/properties_timeline/

    Response

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

    Create persons split

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/split/\
    	-d name="string"

    Response

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

    Create persons update property

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/update_property/\
    	-d name="string"

    Response

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

    Retrieve persons activity

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/activity/

    Response

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

    Retrieve persons cohorts

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/cohorts/

    Response

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

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/

    Response

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

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/\
    	-d name="string"

    Response

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

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/

    Response

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

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/\
    	-d name="string"

    Response

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

    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


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/lifecycle/

    Response

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

    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"

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/path/

    Response

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

    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
      object

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/path/\
    	-d name="string"

    Response

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

    Retrieve persons retention

    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


    Request

    GET /api/projects/:project_id/persons/retention
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/retention/

    Response

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

    Retrieve persons stickiness

    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


    Request

    GET /api/projects/:project_id/persons/stickiness
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/stickiness/

    Response

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

    Retrieve persons values

    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


    Request

    GET /api/projects/:project_id/persons/values
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/values/

    Response

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

    Questions?

    Was this page useful?