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

    Query Parameters

    • distinct_id
      string
    • email
      string
    • format
      string
      One of: "csv""json"
    • limit
      integer
    • offset
      integer
    • properties
      Click to open
      array
    • search
      string

    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

    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",
    "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
    • project_id
      string

    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

    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
    • project_id
      string

    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

    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
    • project_id
      string

    Query Parameters

    • delete_events
      boolean
    • 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

    No response

    Retrieve persons activity retrieve

    Path Parameters

    • id
      integer
    • project_id
      string

    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

    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
    • project_id
      string

    Query Parameters

    • $unset
      string
    • 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

    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
    • project_id
      string

    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

    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
    • project_id
      string

    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

    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
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"
    • key
      string
    • 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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Path Parameters

    • project_id
      string

    Query Parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/properties
    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/properties/

    Response

    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

    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

    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

    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

    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

    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

    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?