Custom Property

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

Endpoints

GET
POST
GET
PATCH
DELETE
POST
GET
POST

List all custom property sources

Required API key scopes

account:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
      "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
      "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
      "source_column": "string",
      "column_property_map": null,
      "column_descriptions": null,
      "key_column": "string",
      "is_enabled": true,
      "consecutive_failures": 0,
      "last_synced_at": "2019-08-24T14:15:22Z",
      "last_sync_error": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": 0,
      "updated_at": "2019-08-24T14:15:22Z",
      "sync_frequency_interval_seconds": 0,
      "next_sync_at": "2019-08-24T14:15:22Z",
      "latest_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "trigger": "string",
        "status": "string",
        "started_at": "2019-08-24T14:15:22Z",
        "finished_at": "2019-08-24T14:15:22Z",
        "rows_read": 0,
        "changed": 0,
        "existing": 0,
        "produced": 0,
        "skipped_missing_person": 0,
        "error": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    }
  ]
}

Create custom property sources

Required API key scopes

account:write

Request parameters

  • definition
    string
  • saved_query
    stringnull
  • external_data_schema
    stringnull
  • source_column
    stringnull
  • column_property_map
  • column_descriptions
  • key_column
    string
  • is_enabled
    boolean
    Default: true

Response


Example request

POST /api/projects/:project_id/custom_property_sources
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/projects/:project_id/custom_property_sources/\
	-d definition="string",\
	-d key_column="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  }
}

Retrieve custom property sources

Required API key scopes

account:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/custom_property_sources/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/custom_property_sources/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  }
}

Update custom property sources

Required API key scopes

account:write

Path parameters

  • id
    string

Request parameters

  • source_column
    string
  • key_column
    string
  • is_enabled
    boolean

Response


Example request

PATCH /api/projects/:project_id/custom_property_sources/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/custom_property_sources/:id/\
	-d source_column="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  }
}

Delete custom property sources

Required API key scopes

account:write

Path parameters

  • id
    string

Example request

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

Example response

Status 204 No response body

Create custom property sources

Person and group sources only: start a backfill that reads the whole warehouse table and populates person or group properties for historical rows. Coalesces if one is already running for the table.

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/custom_property_sources/:id/backfill
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/projects/:project_id/custom_property_sources/:id/backfill/

Example response

Status 202
RESPONSE
{
  "status": "triggered",
  "already_running": true
}

List all custom property sources runs

Person and group sources only: the source's sync/backfill run history, newest first. Gated on the caller's warehouse-source viewer access, since the runs expose its row counts and sync errors.

Path parameters

  • id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/custom_property_sources/:id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/custom_property_sources/:id/runs/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "trigger": "string",
      "status": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "rows_read": 0,
      "changed": 0,
      "existing": 0,
      "produced": 0,
      "skipped_missing_person": 0,
      "error": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create custom property sources

Person and group sources only: trigger the underlying warehouse schema's sync now. This re-runs a real (billable) warehouse sync; the incremental person/group-property update runs off it.

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/custom_property_sources/:id/sync
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/projects/:project_id/custom_property_sources/:id/sync/

Example response

Status 202
RESPONSE
{
  "status": "triggered",
  "already_running": true
}

Community questions