Home Original page

Users API Reference - PostHog

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

Endpoints

GET
GET
PATCH
DELETE
GET
PATCH
POST
GET
POST
POST
GET
GET
POST
POST
PATCH
POST
POST

List all users

Required API key scopes

user:read

Query parameters

Response

Example request

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/

Example response

Status 200 
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "date_joined": "2019-08-24T14:15:22Z",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "pending_email": "user@example.com",
      "is_email_verified": true,
      "notification_settings": {
        "property1": null,
        "property2": null
      },
      "anonymize_data": true,
      "allow_impersonation": true,
      "toolbar_mode": "disabled",
      "has_password": true,
      "id": 0,
      "is_staff": true,
      "is_impersonated": true,
      "is_impersonated_until": "string",
      "is_impersonated_read_only": true,
      "sensitive_session_expires_at": "string",
      "team": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
        "project_id": -9223372036854776000,
        "api_token": "string",
        "name": "string",
        "completed_snippet_onboarding": true,
        "has_completed_onboarding_for": null,
        "ingested_event": true,
        "is_demo": true,
        "timezone": "Africa/Abidjan",
        "access_control": true
      },
      "organization": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "membership_level": 1,
        "plugins_access_level": 0,
        "teams": [
          {
            "property1": null,
            "property2": null
          }
        ],
        "projects": [
          {
            "property1": null,
            "property2": null
          }
        ],
        "available_product_features": [
          null
        ],
        "is_member_join_email_enabled": true,
        "metadata": {
          "property1": "string",
          "property2": "string"
        },
        "customer_id": "string",
        "enforce_2fa": true,
        "members_can_invite": true,
        "members_can_use_personal_api_keys": true,
        "allow_publicly_shared_resources": true,
        "member_count": 0,
        "is_ai_data_processing_approved": true,
        "default_experiment_stats_method": "bayesian",
        "default_anonymize_ips": true,
        "default_role_id": "string",
        "is_active": true,
        "is_not_active_reason": "string"
      },
      "organizations": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "slug": "string",
          "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
          "membership_level": 1,
          "members_can_use_personal_api_keys": true,
          "is_active": true,
          "is_not_active_reason": "string"
        }
      ],
      "set_current_organization": "string",
      "set_current_team": "string",
      "password": "string",
      "current_password": "string",
      "events_column_config": null,
      "is_2fa_enabled": true,
      "has_social_auth": true,
      "has_sso_enforcement": true,
      "has_seen_product_intro_for": null,
      "scene_personalisation": [
        {
          "scene": "string",
          "dashboard": 0
        }
      ],
      "theme_mode": "light",
      "hedgehog_config": null,
      "allow_sidebar_suggestions": true,
      "shortcut_position": "above",
      "role_at_organization": "engineering",
      "passkeys_enabled_for_2fa": true
    }
  ]
}

Retrieve users

Required API key scopes

user:read

Path parameters

Response

Example request

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/

Example response

Status 200 
{
  "date_joined": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "distinct_id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "pending_email": "user@example.com",
  "is_email_verified": true,
  "notification_settings": {
    "property1": null,
    "property2": null
  },
  "anonymize_data": true,
  "allow_impersonation": true,
  "toolbar_mode": "disabled",
  "has_password": true,
  "id": 0,
  "is_staff": true,
  "is_impersonated": true,
  "is_impersonated_until": "string",
  "is_impersonated_read_only": true,
  "sensitive_session_expires_at": "string",
  "team": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
    "project_id": -9223372036854776000,
    "api_token": "string",
    "name": "string",
    "completed_snippet_onboarding": true,
    "has_completed_onboarding_for": null,
    "ingested_event": true,
    "is_demo": true,
    "timezone": "Africa/Abidjan",
    "access_control": true
  },
  "organization": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "slug": "string",
    "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "membership_level": 1,
    "plugins_access_level": 0,
    "teams": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "projects": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "available_product_features": [
      null
    ],
    "is_member_join_email_enabled": true,
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "customer_id": "string",
    "enforce_2fa": true,
    "members_can_invite": true,
    "members_can_use_personal_api_keys": true,
    "allow_publicly_shared_resources": true,
    "member_count": 0,
    "is_ai_data_processing_approved": true,
    "default_experiment_stats_method": "bayesian",
    "default_anonymize_ips": true,
    "default_role_id": "string",
    "is_active": true,
    "is_not_active_reason": "string"
  },
  "organizations": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
      "membership_level": 1,
      "members_can_use_personal_api_keys": true,
      "is_active": true,
      "is_not_active_reason": "string"
    }
  ],
  "set_current_organization": "string",
  "set_current_team": "string",
  "password": "string",
  "current_password": "string",
  "events_column_config": null,
  "is_2fa_enabled": true,
  "has_social_auth": true,
  "has_sso_enforcement": true,
  "has_seen_product_intro_for": null,
  "scene_personalisation": [
    {
      "scene": "string",
      "dashboard": 0
    }
  ],
  "theme_mode": "light",
  "hedgehog_config": null,
  "allow_sidebar_suggestions": true,
  "shortcut_position": "above",
  "role_at_organization": "engineering",
  "passkeys_enabled_for_2fa": true
}

Update users

Required API key scopes

user:write

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Response

Example request

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/\
	-d date_joined="string"

Example response

Status 200 
{
  "date_joined": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "distinct_id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "pending_email": "user@example.com",
  "is_email_verified": true,
  "notification_settings": {
    "property1": null,
    "property2": null
  },
  "anonymize_data": true,
  "allow_impersonation": true,
  "toolbar_mode": "disabled",
  "has_password": true,
  "id": 0,
  "is_staff": true,
  "is_impersonated": true,
  "is_impersonated_until": "string",
  "is_impersonated_read_only": true,
  "sensitive_session_expires_at": "string",
  "team": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
    "project_id": -9223372036854776000,
    "api_token": "string",
    "name": "string",
    "completed_snippet_onboarding": true,
    "has_completed_onboarding_for": null,
    "ingested_event": true,
    "is_demo": true,
    "timezone": "Africa/Abidjan",
    "access_control": true
  },
  "organization": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "slug": "string",
    "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "membership_level": 1,
    "plugins_access_level": 0,
    "teams": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "projects": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "available_product_features": [
      null
    ],
    "is_member_join_email_enabled": true,
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "customer_id": "string",
    "enforce_2fa": true,
    "members_can_invite": true,
    "members_can_use_personal_api_keys": true,
    "allow_publicly_shared_resources": true,
    "member_count": 0,
    "is_ai_data_processing_approved": true,
    "default_experiment_stats_method": "bayesian",
    "default_anonymize_ips": true,
    "default_role_id": "string",
    "is_active": true,
    "is_not_active_reason": "string"
  },
  "organizations": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "logo_media_id": "a5d9f2f1-d934-4d2e-bebe-4b3cdcd08a33",
      "membership_level": 1,
      "members_can_use_personal_api_keys": true,
      "is_active": true,
      "is_not_active_reason": "string"
    }
  ],
  "set_current_organization": "string",
  "set_current_team": "string",
  "password": "string",
  "current_password": "string",
  "events_column_config": null,
  "is_2fa_enabled": true,
  "has_social_auth": true,
  "has_sso_enforcement": true,
  "has_seen_product_intro_for": null,
  "scene_personalisation": [
    {
      "scene": "string",
      "dashboard": 0
    }
  ],
  "theme_mode": "light",
  "hedgehog_config": null,
  "allow_sidebar_suggestions": true,
  "shortcut_position": "above",
  "role_at_organization": "engineering",
  "passkeys_enabled_for_2fa": true
}

Delete users

Path parameters

Example request

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/

Example response

Status 204 No response body

Retrieve users hedgehog config

Required API key scopes

user:read

Path parameters

Example request

GET /api/users/:uuid/hedgehog_config

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/

Example response

Status 200 No response body

Update users hedgehog config

Required API key scopes

user:write

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

PATCH /api/users/:uuid/hedgehog_config

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/\
	-d date_joined="string"

Example response

Status 200 No response body

Create users scene personalisation

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/:uuid/scene_personalisation

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/users/:uuid/scene_personalisation/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Retrieve users start 2fa setup

Path parameters

Example request

GET /api/users/:uuid/start_2fa_setup

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/start_2fa_setup/

Example response

Status 200 No response body

Create users two factor backup codes

Generate new backup codes, invalidating any existing ones

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/:uuid/two_factor_backup_codes

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/users/:uuid/two_factor_backup_codes/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Create users two factor disable

Disable 2FA and remove all related devices

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/:uuid/two_factor_disable

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/users/:uuid/two_factor_disable/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Retrieve users two factor start setup

Path parameters

Example request

GET /api/users/:uuid/two_factor_start_setup

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/two_factor_start_setup/

Example response

Status 200 No response body

Retrieve users two factor status

Get current 2FA status including backup codes if enabled

Path parameters

Example request

GET /api/users/:uuid/two_factor_status

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/two_factor_status/

Example response

Status 200 No response body

Create users two factor validate

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/:uuid/two_factor_validate

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/users/:uuid/two_factor_validate/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Create users validate 2fa

Path parameters

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/:uuid/validate_2fa

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/users/:uuid/validate_2fa/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Update users cancel email change request

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

PATCH /api/users/cancel_email_change_request

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/cancel_email_change_request/\
	-d date_joined="string"

Example response

Status 200 No response body

Create users request email verification

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/request_email_verification

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/users/request_email_verification/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body

Create users verify email

Request parameters

  • has_seen_product_intro_for

  • allow_sidebar_suggestions

Example request

POST /api/users/verify_email

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/users/verify_email/\
	-d email="string",\
	-d password="string"

Example response

Status 200 No response body