Taxonomy API

The Taxonomy API grants Enterprise users the ability to programmatically plan their event schema in the Taxonomy tab.

The Taxonomy API lets you create, get, update, and delete categories, event types, event properties, and user properties.

Authentication

This API uses basic authentication, using the API key and secret key for your project. Pass base64-encoded credentials in the request header like {api-key}:{secret-key}. api-key replaces username, and secret-key replaces the password.

Your authorization header should look something like this:

--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'

For more information, see Find your API Credentials

Endpoints

Region	Endpoint
Standard server	`https://amplitude.com/api/2/`
EU residency server	`https://analytics.eu.amplitude.com/api/2/`

Considerations

You may have to URL encode special characters in the names of event types, event properties, and user properties.
For example, encode Play Song as Play%20Song. Use the W3Schools encoding reference.
In responses, custom user properties have a gp: prefix. For example, gp:my_custom_property.
You must plan events or properties in the schema before you can delete them via this API.

Limits

For each endpoint, there is a concurrent and a rate limit. This limit restricts the number of requests you can run at the same time, while the rate limit restricts the total number of queries you can run per hour.

Limits are per project, and exceeding any of these limits returns a 429 error.

The endpoints use a cost per query model. Here are the max costs per API Key:

Concurrent Cost Limit: You can run queries that collectively add up to 4 cost at the same time.
Period Cost Limit: You can run up to 7200 cost per hour.

Cost structure of each endpoint:

GET: 1 cost
PUT: 2 cost
POST: 2 cost
DELETE: 2 cost

Event category

Event categories are a way to organize your event types into broad groups.

Example

You want to track how users register for your app, checkout, and how they interact with the onboarding experience. You can bucket your events using these event categories:

Registration
Checkout
Onboarding

Create event category

Create an event category in your project.

POST /api/2/taxonomy/category

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/category' \
2--header 'Authorization: Basic {api-key}:{secret-key}' \ #credentials must be base64 encoded
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'category_name=CATEGORY_NAME'

1POST /api/2/taxonomy/category HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5category_name=CATEGORY_NAME

Example: Create an event category

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/category' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'category_name=Attribution'

1POST /api/2/taxonomy/category HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 25
6category_name=Attribution

Body parameters

Name	Description
`category_name`	Required. Name of the category.

Response

A successful request returns a 200 OK response with a JSON body:

1{
2    "success" : true
3}

A failed request sends an error message with more information:

1{
2   "success" : false,
3   "errors" : [
4      {
5         "message" : "error info"
6      }
7   ]
8}

Get all event categories

Get all event categories in your project.

GET https://amplitude.com/api/2/taxonomy/category

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category' \
2-u '{api_key}:{secret_key}'

1GET /api/2/taxonomy/category HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Response

A successful request returns a 200 OK status with a JSON body:

 1{
 2    "success": true,
 3    "data": [
 4        {
 5            "id": 412931,
 6            "name": "Attribution"
 7        },
 8        {
 9            "id": 412941,
10            "name": "Conversion"
11        }
12    ]
13}

A failed request returns a 400 Bad Request response with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Get an event category

Get the ID of an event category in your project. Send a GET request with the category name.

GET https://amplitude.com/api/2/taxonomy/category/:category_name

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category/:category_name' \
2-u '{api_key}:{secret_key}'

1GET /api/2/taxonomy/category/:category_name HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Get a category's ID

This example get the ID for the event category named "Attribution".

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category/Attribution' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1GET /api/2/taxonomy/category/Attribution HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`category_name`	Required. The name of the category

Response

A successful request returns a 200 OK status and a JSON body with the category's data:

1{
2    "success": true,
3    "data": {
4        "id": 412941,
5        "name": "Conversion"
6    }
7}

A failed request returns a 400 Bad Request status with more information about the error.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Update the name of an event category. Send a PUT request with the category ID and a new name in the body.

PUT https://amplitude.com/api/2/taxonomy/category/:category_id

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/category/CATEGORY_ID' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'category_name=NEW_NAME'

1PUT /api/2/taxonomy/category/CATEGORY_ID HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 23
6 
7category_name=NEW_NAME

Example: Rename a category

This example renames the category with the ID 412941 to "Converted".

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/category/412941' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'category_name=Converted'

1PUT /api/2/taxonomy/category/412941 HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 23
6 
7category_name=Converted

Path parameters

Name	Description
`category_id`	Required. The ID of the category

Body parameters

Name	Description
`category_name`	Required. The new name of the category

200 ok response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

If there is a problem with your request, the request returns a 409 Conflict status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to operate on entity event_category, id \"4129\", that does not exist."
6        }
7    ]
8}

Delete an event category

Delete an event category. Send a DELETE request with the category ID.

DELETE https://amplitude.com/api/2/taxonomy/category/:category_id

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/category/:category_id' \
2-u '{api_key}:{secret_key}'

1DELETE /api/2/taxonomy/category/:category_id HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Delete a category

This example deletes the category with the ID 412941.

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/category/412941' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1DELETE /api/2/taxonomy/category/412941 HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`category_id`	Required. The ID of the category

200 ok response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

If there is a problem with your request, the request returns a 409 Conflict status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to operate on entity event_category, id \"412941\", that does not exist."
6        }
7    ]
8}

Event type

An event is any action a user can take, like start game or add to cart, or any activity associated with a user, like in-app notifications or push notifications.

You can use the API to manipulate event types.

Create an event type

Creates an event type. Send a POST request to https://amplitude.com/api/2/taxonomy/event and include a body with your parameters.

Note

Initialize the schema before you can add event types via the API.

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'event_type=EVENT_TYPE' \
5--data-urlencode 'category=CATEGORY_NAME' \
6--data-urlencode 'description=DESCRIPTION'

1POST /api/2/taxonomy/event?=null HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 80
6 
7event_type=EVENT_TYPE&category=CATEGORY_NAME&description=CATEGORY_DESCRIPTION

Example: Create an event type

This example creates the event type "Onboarding Start" with the category "Onboarding" and a description of "My new onboarding event".

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
3--data-urlencode 'event_type=Onboard Start' \
4--data-urlencode 'category=Onboarding' \
5--data-urlencode 'description=My new onboarding event. ' \

1 
2POST /api/2/taxonomy/event HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5 
6Content-Length: 92
7 
8event_type=Onboard%20Start&category=Onboarding&description=My%20new%20onboarding%20event.%20

Body parameters

Name	Description
`event_type`	Required. String. The event name.
`category`	Optional. String. The event type's category.
`description`	Optional. String. Details about the event type.

200 ok response

A successful request returns a 200 OK response with a JSON body:

1{
2    "success" : true
3}

409 conflict response

A failed request returns a 409 Conflict status with an error message.

1{
2   "success" : false,
3   "errors" : [
4      {
5         "message" : "error info"
6      }
7   ]
8}

Get all event types

Retrieves all event types in a project. This request has no required parameters.

GET https://amplitude.com/api/2/taxonomy/event

Note

Hidden events, those that have a visibility other than "Visible", don't appear in the response.

By default, deleted events will also not be included, but the showDeleted query parameter can be optionally added to the endpoint to include them:

GET https://amplitude.com/api/2/taxonomy/event?showDeleted=true

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event' \
2-u '{api_key}:{secret_key}'

1GET /api/2/taxonomy/event HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

200 OK response

A successful request returns a 200 OK status with a JSON body:

 1{
 2    "success": true,
 3    "data": [
 4        {
 5            "event_type": "Attribution",
 6            "category": {
 7                "name": "Attribution Events"
 8            },
 9            "description": null
10        },
11        {
12            "event_type": "Conversation",
13            "category": {
14                "name": "Conversion Events"
15            },
16            "description": "This event is fired when a user converts."
17        }
18    ]
19}

Get an event type

Get a single event type, by name. Send a GET request with the event name.

GET https://amplitude.com/api/2/taxonomy/event/:event_type

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event:event_type' \
2-u '{api_key}:{secret_key}'

1GET /api/2/taxonomy/event/:event_type HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Get an event type by name

This example gets the 'Event 2' event type.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event/Event 2' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event/Event 2' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

Path parameters

Name	Description
`event_type`	Required. String. The event name.

200 OK response

A successful request returns a 200 OK status and a JSON body with the event type's data:

 1{
 2    "success": true,
 3    "data": {
 4        "event_type": "Event 2",
 5        "category": {
 6            "name": "Conversion Events"
 7        },
 8        "description": null
 9    }
10}

400 Bad Request response

A failed request returns a 400 Bad Request status with more information about the error.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Update an event type

Update an event type. Send a PUT request with the event type name.

PUT https://amplitude.com/api/2/taxonomy/event/:event_type

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE_NAME' \
2-u '{api_key}:{secret_key}'
3--data-urlencode 'category=NEW_CATEGORY_NAME' \
4--data-urlencode 'display_name=NEW_EVENT_TYPE_DISPLAY_NAME'

1PUT /api/2/taxonomy/event/EVENT_TYPE_NAME HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded
4Content-Length: 41
5 
6category=NEW_CATEGORY_NAME&display_name=NEW_EVENT_TYPE_DISPLAY_NAME

Example: Update an event type

This example updates the event type OnboardingBegin with the category Onboarding, event type name OnboardStart, the display name "Onboarding Start", and a description of "User signed in and completed an onboarding task from modal".

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event/OnboardBegin' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'new_event_type=OnboardStart' \
5--data-urlencode 'category=Onboarding' \
6--data-urlencode 'description=User signed in and completed an onboarding task from modal.' \
7--data-urlencode 'display_name=Onboarding Start'

1PUT /api/2/taxonomy/event/OnboardBegin HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 169
6 
7new_event_type=OnboardStart&category=Onboarding&description=User%20signed%20in%20and%20completed%20an%20onboarding%20task%20from%20modal.&display_name=Onboarding%20Start

Path parameters

Name	Description
`event_type`	Required. String. The event name.

Body parameters

Name	Description
`new_event_type`	Optional. String. The event type's new name.
`category`	Optional. Current category name of the event type.
`description`	Optional. String. Details to add to the event type.
`display_name`	Optional. String. Display name of an event type. You can update the display name for an event type after it's ingested into Amplitude.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

If there is a problem with your request, the request returns a 409 Conflict status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to change the event display name for event \"Event\", but the event is not in schema."
6        }
7    ]
8}

Delete an event type

Delete an event type.

DELETE https://amplitude.com/api/2/taxonomy/event/:event_type

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE'
2-u '{api_key}:{secret_key}'

1DELETE /api/2/taxonomy/event/EVENT_TYPE HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Delete an event type

This example deletes the event type Event1.

1 
2curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event/Event1' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \

1 
2DELETE /api/2/taxonomy/event/Event1 HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`event_type`	Required. The name of the event type.

Behavior

Event type	Behavior in Amplitude
`live`	Marks the event as deleted
`unexpected`	Adds the event to the tracking plan, then marks it as `deleted`
`planned`	Removes the event from the tracking plan
`transformed`	Returns an error because `transformed` event types aren't deletable
`deleted` or `not found`	Returns an error

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

4XX responses

If there's a problem with the request, Amplitude returns a 4XX status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Restore an event type

Restore an event type.

POST https://amplitude.com/api/2/taxonomy/event/:event_type/restore

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE/restore'
2-u '{api_key}:{secret_key}'

1POST /api/2/taxonomy/event/EVENT_TYPE/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Restore an event type

This example restores the event type "Event1".

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event/Event1/restore' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1POST /api/2/taxonomy/event/Event1/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`event_type`	Required. The name of the event type.

Behavior

Event type	Behavior in Amplitude
`deleted`	Restores the event
`not deleted` or `not found`	Returns an error

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

4XX responses

If there's a problem with your request, Amplitude returns a 4XX status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Event property

Event properties describe the attributes of an event. For example, if 'Swipe' is an event that you are tracking, then the event property ‘Direction’ could have the values ‘Left’ or ‘Right’.

Create an event property

Create an event property. Send a POST request to the endpoint with the required information in the body.

POST https://amplitude.com/api/2/taxonomy/event-property

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'event_type=EVENT_TYPE' \
5--data-urlencode 'event_property=EVENT_PROPERTY' \

1POST /api/2/taxonomy/event-property HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 94
6 
7event_type=EVENT_TYPE&event_property=EVENT_PROPERTY

Example: Create an event property

This example creates the event property "Completed Task" with the description "User completed any onboarding task" for the event "Onboarding Start". The event property is a boolean type, isn't required.

1 
2curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--data-urlencode 'event_type=Onboard Start' \
5--data-urlencode 'event_property=Completed Task' \
6--data-urlencode 'description=User completed any onboarding task' \
7--data-urlencode 'type=boolean' \
8--data-urlencode 'is_required=false'

1 
2POST /api/2/taxonomy/event-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5 
6Content-Length: 144
7 
8event_type=Onboard%20Start&event_property=Completed%20Task&type=boolean&is_required=false&description=User%20completed%20any%20onboarding%20task

Body parameters

Name	Description
`event_property`	Required. String. Name of the event property.
`event_type`	Optional. String. Name of the event type to which the event property belongs to. If the event property already exists on this event type, Amplitude returns a `409 Conflict` error. If the event property already exists but not on this event type, Amplitiude creates an override for this property. If the event property doesn't exist anywhere, Amplitude doesn't create an override for this property.
`description`	Optional. String. The event property's description.
`type`	Optional. String. The event property's data type. Acceptable values are `string`, `number`, `boolean`, `enum`, and `any`
`regex`	Optional. String. Regular expression, custom regex used for pattern matching or more complex values. For example, property zip code must have pattern `[0-9]{5}` Applies only to the `string` type.
`enum_values`	Optional. String. List of allowed values, separated by comma. For example: `red, yellow, blue`. Only applicable to the `enum` type.
`is_array_type`	Optional. Boolean. Use the `type` parameter to set the type of array elements.
`is_required`	Optional. Boolean. Marks the property as required. When `true`, Amplitude flags events that are missing this property on the Taxonomy page in the web app.
`classifications`	Optional. String. List of classifications applicable to this event property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`. You can only apply classifications on shared properties. Trying to set classifications on an overridden property results in an error.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

If there is a problem with your request, the request returns a 409 Conflict status, and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to add an event property, \"Completed Task\" for event \"Onboard Start\", that already exists."
6        }
7    ]
8}

Get event properties

Get shared or event-specific event properties.

GET https://amplitude.com/api/2/taxonomy/event-property

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property' \
3-u '{api_key}:{secret_key}' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'event_type=EVENT_NAME'

1 
2GET /api/2/taxonomy/event-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
5 
6event_type=EVENT_NAME

Example: get all of an event's properties

This example gets all event properties for the "Onboard Start" event.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'event_type=Onboard Start'

1 
2GET /api/2/taxonomy/event-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 26
7 
8event_type=Onboard%20Start

Body parameters

Name	Description
`event_type`	Optional. Name of the event type to which the event properties belong to. If `event_type` is present, Amplitude returns all event properties associated with this event type. If `event_type` isn't present, Amplitude returns all shared event properties in your tracking plan.

200 OK response

A successful request returns a 200 OK status and a JSON body with a list of event properties and their data.

 1{
 2    "success": true,
 3    "data": [
 4        {
 5            "event_property": "Completed Task",
 6            "event_type": "Onboard Start",
 7            "description": "User completed a task during onboarding.",
 8            "type": "boolean",
 9            "regex": null,
10            "enum_values": null,
11            "is_array_type": false,
12            "is_required": false,
13            "classifications": ["PII"]
14        },
15        {
16            "event_property": "Completed Tutorial",
17            "event_type": "Onboard Start",
18            "description": "",
19            "type": "any",
20            "regex": null,
21            "enum_values": null,
22            "is_array_type": false,
23            "is_required": false,
24            "classifications": []
25        }
26    ]
27}

Get a single event property

Get a single event property. Send a GET request with the event property name as a path parameter and, optionally, the event name in the body.

GET https://amplitude.com/api/2/taxonomy/event-property

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property?event_property=EVENT_PROPERTY' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'event_type=EVENT_NAME'

1GET /api/2/taxonomy/event-property/EVENT_PROPERTY_NAME HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4 
5event_type=EVENT_NAME

Example: Get a property from a specific event

This example gets a the "Completed Task" property for the "Onboard Start" event.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property?event_property=Completed Task' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'event_type=Onboard Start'

1 
2GET /api/2/taxonomy/event-property?event_property=Completed Task HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 26
7 
8event_type=Onboard%20Start

Path parameters

Name	Description
`event_property`	Required. The event property name.

Body parameter

Name	Description
`event_type`	Optional. Name of the event type to which the event properties belong to. If `event_type` is present, Amplitude returns all event properties associated with this event type. If `event_type` isn't present, Amplitude returns all shared properties in your tracking plan.

200 OK response

A successful request returns a 200 OK status and a JSON body containing information about the event property.

 1{
 2    "success": true,
 3    "data": {
 4        "event_property": "Shared",
 5        "event_type": "Onboard Finish",
 6        "description": "Whether user shared content.",
 7        "type": "boolean",
 8        "regex": null,
 9        "enum_values": null,
10        "is_array_type": false,
11        "is_required": false,
12        "classifications": ["PII"]
13    }
14}

400 Bad Request response

If Amplitude can't find the event property, or you configure the request incorrectly, it returns a 400 Bad Request response and an error message.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Update event property

Update an event property.

PUT https://amplitude.com/api/2/taxonomy/event-property/:event-property

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'event_type=EVENT_NAME' \

1 
2PUT /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1
3Host: amplitude.com
4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 24
7 
8event_type=EVENT_NAME

Example: Update an event property

This example updates a the "Completed Task" property. It changes the name to "Task Completed" and adds a description.

1 
2curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'description=User completed an onboarding task' \
6--data-urlencode 'new_event_property_value=Task Completed' \

1 
2PUT /api/2/taxonomy/event-property/Completed Task HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 130
7 
8event_type=Onboard%20Start&description=User%20completed%20an%20onboarding%20task&new_event_property_value=Task%20Completed&type=any

Path parameters

Name	Description
`event-property`	Required. Name of the event property.

Body parameters

Name	Description
`event_type`	Optional. Name of the event type to which the event properties belong to. If the event property already exists on this event type, Amplitude returns a `409 Conflict` error. If the event property already exists but not on this event type, Amplitude creates an override for this property. If the event property doesn't exist anywhere, Amplitude doesn't create an override for this property.
`overrideScope`	Optional. Determines how we should act on this event property. Only applicable if event_type is present. If `overrideScope` is not present, Amplitude updates property override on the event if it exists on the event, or the shared property if no override exists on the event. With `overrideScope: "override"`, Amplitude creates an override if none exists on the event, then updates that overridden property, or it updates the existing override if one already exists. With `overrideScope: "shared"`, Amplitude removes the property override on the event if one exists on the event, then updates the shared property, or updates the shared property if no property override exists.
`description`	Optional. String. The event property's description.
`new_event_property_value`	Optional. String. The new name of the event property.
`type`	Optional. String. The event property's data type. Acceptable values are `string`, `number`, `boolean`, `enum`, and `any`
`regex`	Optional. String. Regular expression, custom regex used for pattern matching or more complex values. For example, property zip code must have pattern `[0-9]{5}`
`enum_values`	Optional. String. List of allowed values.
`is_array_type`	Optional. Boolean. Specifies whether the property value is an array.
`is_required`	Optional. Boolean. Marks the property as required.
`classifications`	Optional. String. Only available if Data Access Controls is enabled at the account level. List of classifications applicable to this event property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`. You can only apply classifications on shared properties, and trying to set classifications on an overridden property results in an error. With `overrideScope: "override"`, Amplitude returns an error for the same reason mentioned in the previous point.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

Some failed requests return a 409 Conflict and an error message with more details.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to change the event property description for property \"Completed Task\" for event \"\", but the property is not in schema."
6        }
7    ]
8}

Delete an event property

Delete an event property. Send a DELETE request with the event property as a path parameter and, optionally, the event type in the request body.

DELETE https://amplitude.com/api/2/taxonomy/event-property/:event-property

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY' \
2--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'event_type=EVENT_NAME'

1DELETE /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded
4 
5event_type=EVENT_NAME

Example: Delete an event property

This example deletes the event property "Completed Task" from the "Onboarding Start" event.

1 
2curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'event_type=Onboarding Start'

1 
2DELETE /api/2/taxonomy/event-property/Completed Task HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 29
7 
8event_type=Onboarding%20Start

Path parameters

Name	Description
`event_property`	Required. The event property name.

Body parameter

Name	Description
`event_type`	Optional. Name of the event type to which the event properties belong.

Behavior

If the event type is available:

Event property	Behavior in Amplitude
`exists`	Removes it from the event type
`does not exist`	Returns an error

If the event type isn't available, Amplitude operates on the global event property.

Event property	Behavior in Amplitude
`live`	Marks the event property as `deleted`
`unexpected`	Adds the event property to the tracking plan, and marks it as `deleted`
`planned`	Removes the event property from the tracking plan
`transformed`	Returns an error because transformed event properties aren't deletable
`deleted` or `not found`	Returns an error.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

Restore an event property

Restore an event property. Send a POST request with the event property as a path parameter.

POST https://amplitude.com/api/2/taxonomy/event-property/:event-property/restore

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY/restore' \
2--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded

1POST /api/2/taxonomy/event-property/EVENT_PROPERTY/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded

Example: Delete an event property

This example restores the event property "Completed Task".

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task/restore' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1POST /api/2/taxonomy/event-property/Completed Task/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`event_property`	Required. The event property name.

Behavior

Event property	Behavior in Amplitude
`deleted`	Restores the event property
`not deleted` or `not found`	Returns an error

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

User property

User properties reflect traits about the individuals using your product.

Create a user property

Create a user property.

POST https://amplitude.com/api/2/taxonomy/user-property/

1 
2curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property' \
3--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded \
4--data-urlencode 'user_property=USER_PROPERTY' \

1POST /api/2/taxonomy/user-property HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded
4 
5user_property=USER_PROPERTY

Example: Create a user property

This example creates a user property called "User Type", with a description of "Describes whether the user is a Free, Standard, or Premium user.", a type of string and allows the values "Free", "Standard", and "Premium".

1 
2curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--data-urlencode 'user_property=User Type' \
5--data-urlencode 'description=Describes whether the user is a Free, Standard, or Premium user. ' \
6--data-urlencode 'type=string' \
7--data-urlencode 'enum_values=Free, Standard, Premium'

1 
2POST /api/2/taxonomy/user-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5Content-Length: 185
6 
7user_property=User%20Type&description=Describes%20whether%20the%20user%20is%20a%20Free%2C%20Standard%2C%20or%20Premium%20user.%20&type=string&enum_values=Free%2C%20Standard%2C%20Premium

Body parameter

Name	Description
`user_property`	Required. String. Name of the user property type.
`description`	Optional. String. Details to add to the user property type.
`type`	Optional. String. The user property's data type. Acceptable values are `string`, `number`, `boolean`, `enum`, and `any`.
`regex`	Optional. String. Regular expression or custom regex used for pattern matching and more complex values. For example, 'zip code' property must have pattern `[0-9]{5}`.
`enum_values`	Optional. String. List of allowed values, separated by comma. For example: `red, yellow, blue`.
`is_array_type`	Optional. Boolean. Specifies whether the property value is an array.
`classifications`	Optional. String. Only available if Data Access Controls is enabled at the account level. List of classifications applicable to this user property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`.

Response

This request returns either a true or false response.

1{
2    "success" : true
3}

1{
2    "success" : false
3}

Get all user properties

Retrieves all user properties in your account. This call doesn't have any required parameters.

GET https://amplitude.com/api/2/taxonomy/user-property

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property' \
2-u '{api_key}:{secret_key}''

1GET /api/2/taxonomy/user-property HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Response

A successful request returns a 200 OK response and a JSON body with user property details.

 1{
 2    "success": true,
 3    "data": [
 4        {
 5            "user_property": "device_id",
 6            "description": null,
 7            "type": null,
 8            "enum_values": null,
 9            "regex": null,
10            "is_array_type": false,
11            "classifications": ["PII"]
12        }, ...
13        {
14            "user_property": "event_id",
15            "description": null,
16            "type": null,
17            "enum_values": null,
18            "regex": null,
19            "is_array_type": false,
20            "classifications": []
21        },
22        {
23            "user_property": "amplitude_id",
24            "description": null,
25            "type": null,
26            "enum_values": null,
27            "regex": null,
28            "is_array_type": false,
29            "classifications": []
30        },
31        {
32            "user_property": "location_lat",
33            "description": null,
34            "type": null,
35            "enum_values": null,
36            "regex": null,
37            "is_array_type": false,
38            "classifications": []
39        },
40        {
41            "user_property": "location_lng",
42            "description": null,
43            "type": null,
44            "enum_values": null,
45            "regex": null,
46            "is_array_type": false,
47            "classifications": []
48        },
49        {
50            "user_property": "server_upload_time",
51            "description": null,
52            "type": null,
53            "enum_values": null,
54            "regex": null,
55            "is_array_type": false,
56            "classifications": []
57        },
58        {
59            "user_property": "session_id",
60            "description": null,
61            "type": null,
62            "enum_values": null,
63            "regex": null,
64            "is_array_type": false,
65            "classifications": []
66        },
67        {
68            "user_property": "user_id",
69            "description": null,
70            "type": null,
71            "enum_values": null,
72            "regex": null,
73            "is_array_type": false,
74            "classifications": []
75        } 
76    ]
77}

Get a user property

Retrieves a single user property, by name.

GET https://amplitude.com/api/2/taxonomy/user-property/:user_property

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \
2-u '{api_key}:{secret_key}'

1GET /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Get a user property

This example gets the device_id user property.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property/device_id' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1 
2GET /api/2/taxonomy/user-property/device_id HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`user_property`	Required. The user property name. Prefix custom user properties with `gp:`.

200 OK response

A successful request returns a 200 OK response and a JSON body with user property details.

 1{
 2    "success": true,
 3    "data": {
 4        "user_property": "device_id",
 5        "description": null,
 6        "type": null,
 7        "enum_values": null,
 8        "regex": null,
 9        "is_array_type": false,
10        "classifications": ["PII"]
11    }
12}

404 Bad Request response

A failed request returns a 404 Bad Request status and an error message.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

The Taxonomy API requires an Enterprise plan account. If your subscription doesn't qualify, the call results in a 404 Bad Request response.

Update a user property

Update a user property.

PUT https://amplitude.com/api/2/taxonomy/user-property/:user_property

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \
2-u '{api_key}:{secret_key}'
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'new_user_property_value=VALUE' \
5--data-urlencode 'description=DESCRIPTION'

1PUT /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 37
6 
7new_user_property_value=VALUE&description=DESCRIPTION

Example: Update a user property

This example updates the user_type user property to be named subscription_type, adds a description of "The user's subscription type", and changes the property's data type to string. The user property is prefixed with gp: in the path because it's a custom user property.

1 
2curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/user-property/gp:user_type' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--data-urlencode 'new_user_property_value=subscription_type' \
5--data-urlencode 'description=The user'\''s subscription type' \
6--data-urlencode 'type=string'

1 
2PUT /api/2/taxonomy/user-property/gp:user_type HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5Content-Length: 100
6 
7new_user_property_value=subscription_type&description=The%20user's%20subscription%20type&type=string

Path parameters

Name	Description
`user_property`	Required. The user property name. Prefix custom user properties with `gp:`.

Body parameters

Name	Description
`new_user_property_value`	Optional. String. New name of the user property type.
`description`	Optional. String. Details to add to the user property type.
`type`	Optional. String. The user property's data type. Acceptable values are `string`, `number`, `boolean`, `enum`, and `any`.
`regex`	Optional. String. Regular expression or custom regex used for pattern matching and more complex values. For example, 'zip code' property must have pattern `[0-9]{5}`. Only applicable to the `string` type.
`enum_values`	Optional. String. List of allowed values, separated by comma. For example: `red, yellow, blue`. Only applicable to the `enum` type.
`is_array_type`	Optional. Boolean. Specifies whether the property value is an array. Use the `type` parameter to set the type of array elements.
`classifications`	Optional. String. Only available if Data Access Controls is enabled at the account level. List of classifications applicable to this user property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`.

Response

This request returns either a true or false response.

1{
2    "success" : true
3}

1{
2    "success" : false
3}

Delete a user property

Deletes a single user property, by name.

DELETE https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \
2-u '{api_key}:{secret_key}'

1DELETE /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Delete a user property

This example deletes a custom user property "interests". Notice that the user property is prefixed with gp:.

1curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/user-property/gp:interests' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1DELETE /api/2/taxonomy/user-property/gp:interests HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`user_property`	Required. The user property name. Prefix custom user properties with `gp:`.

Behavior

User property	Behavior in Amplitude
`live`	Marks the user property as `deleted`
`unexpected`	Adds the user property to the tracking plan, and marks it as `deleted`
`planned`	Removes the user property from the tracking plan
`transformed`	Returns an error. Transformed user properties aren't deletable
`Amplitude User Property`	Returns an error. Amplitude user properties aren't deletable
`deleted` or `not found`	Returns an error

200 OK response

A successful request returns a 200 OK response and a JSON message.

1{
2    "success": true
3}

Restore a user property

Restore a single user property, by name.

POST https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore' \
2-u '{api_key}:{secret_key}'

1POST /api/2/taxonomy/user-property/USER_PROPERTY/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Restore a user property

This example restores a custom user property interests. Notice that the user property is prefixed with gp:.

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property/gp:interests/restore' \
2--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA='

1POST /api/2/taxonomy/user-property/gp:interests/restore HTTP/1.1
2Host: amplitude.com
3Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=

Path parameters

Name	Description
`user_property`	Required. The user property name. Prefix custom user properties with `gp:`.

Behavior

User property	Behavior in Amplitude
`deleted`	Restores the user property
`not deleted` or `not found`	Returns an error

200 OK response

A successful request returns a 200 OK response and a JSON message.

1{
2    "success": true
3}

Group property

Group properties are properties at the account level. They apply to all users who belong to that account.

Create a group property

Create a group property. Send a POST request to the endpoint with the required information in the body.

POST https://amplitude.com/api/2/taxonomy/group-property

1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/group-property' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'group_type=GROUP_TYPE' \
5--data-urlencode 'group_property=GROUP_PROPERTY' \

1POST /api/2/taxonomy/group-property HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4Content-Type: application/x-www-form-urlencoded
5Content-Length: 94
6 
7group_type=GROUP_TYPE&group_property=GROUP_PROPERTY

Example: Create a group property

This example creates the group property Group Property 1 with the description "First group property" for the group Group 1. The group property is a boolean type.

1 
2curl --location --request POST 'https://amplitude.com/api/2/taxonomy/group-property' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--data-urlencode 'group_type=Group 1' \
5--data-urlencode 'group_property=Group Property 1' \
6--data-urlencode 'description=First Group Property' \
7--data-urlencode 'type=boolean'

1 
2POST /api/2/taxonomy/group-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=
5 
6Content-Length: 144
7 
8group_type=Group%201&group_property=Group%20Property%201&type=boolean&description=First%20Group%20Property

Body parameters

Name	Description
`group_property`	Required. String. Name of the group property. Prefix custom group properties with `grp:`.
`group_type`	Optional. String. Name of the group type the group property belongs to. If the group type doesn't exist, Amplitude returns a `404 Not Found` error. If the group property already exists on this group type, Amplitude returns a `409 Conflict` error. If the group property already exists but not on this group type, Amplitude creates an override for this property. If the group property doesn't exist anywhere, Amplitude doesn't create an override for this property. If the group property exists and is an Amplitude-sourced group property, providing any extra arguments other than `group_property` and `group_type` results in an error because you can't edit Amplitude-sourced group properties.
`description`	Optional. String. The group property's description.
`type`	Optional. String. Data type of the group property. It must be one of `any` (default), `string` (default if array type is true), `number`, `boolean`, `enum`
`regex`	Optional. String. Regular expression, custom regex used for pattern matching or more complex values. For example, property zip code must have pattern `[0-9]{5}` Applies only to the `string` type.
`enum_values`	Optional. String. List of allowed values, separated by comma. For example: `red, yellow, blue`. Only applicable to the `enum` type.
`is_array_type`	Optional. Boolean. Property is an array type. Use the `type` parameter to set the type of array elements.
`classifications`	Optional. String. Only available if Data Access Controls is enabled at the account level. List of classifications applicable to this group property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`. You can only apply classifications on shared properties, and trying to set classifications on an overridden property results in an error.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

If there's a problem with your request, the request returns a 409 Conflict status and a JSON body with more information.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to add a group property, \"Group Property 1\", that already exists."
6        }
7    ]
8}

Get group properties

Get shared or group-specific group properties.

GET https://amplitude.com/api/2/taxonomy/group-property

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property' \
3-u '{api_key}:{secret_key}' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'group_type=GROUP_TYPE'

1 
2GET /api/2/taxonomy/group-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
5 
6group_type=GROUP_TYPE

Example: get all of a group's properties

This example gets all group properties for the "Group 1" group type.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'group_type=Group 1'

1 
2GET /api/2/taxonomy/group-property HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 26
7 
8group_type=Group%201

Body parameters

Name	Description
`group_type`	Optional. Name of the group type. If `group_type` is present, Amplitude returns all group properties associated with this group type. If `group_type` isn't present, Amplitude returns all shared group properties in your tracking plan.

200 OK response

A successful request returns a 200 OK status and a JSON body with a list of group properties and their data.

 1{
 2    "success": true,
 3    "data": [
 4        {
 5            "group_type": "Group 1",
 6            "group_property": "grp:Group Property 1",
 7            "description": "First Group Property",
 8            "type": "string",
 9            "enum_values": null,
10            "regex": null,
11            "is_array_type": false,
12            "classifications": ["PII"]
13        },
14        {
15            "group_type": "Group 1",
16            "group_property": "grp:Group Property 2",
17            "description": "Second Group Property",
18            "type": "string",
19            "enum_values": null,
20            "regex": null,
21            "is_array_type": false,
22            "classifications": []
23        },
24    ]
25}

Get a single group property

Get a single group property. Send a GET request with the group property name as a path parameter and, optionally, the group type in the body.

GET https://amplitude.com/api/2/taxonomy/group-property/:group_property

1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property/GROUP_PROPERTY' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'group_type=GROUP_TYPE'

1GET /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
4 
5group_type=GROUP_TYPE

Example: Get a property from a specific group type

This example gets a group property named Group Property 1 for the Group 1 group type.

1 
2curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property/grp%3AGroup%20Property%201 \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'group_type=Group 1'

1 
2GET /api/2/taxonomy/group-property/grp%3AGroup%20Property%201 HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 26
7 
8group_type=Group%201

Path parameters

Name	Description
`group_property`	Required. The group property name. Prefix custom group properties with `grp:`.

Query or Body parameter

Name	Description
`group_type`	Optional. Name of the group type. If `group_type` is provided, we return all group properties associated with this group type. If `group_type` is not provided, we return all shared group properties in your tracking plan.

200 OK response

A successful request returns a 200 OK status and a JSON body containing information about the group property.

 1{
 2    "success": true,
 3    "data": {
 4            "group_type": "Group 1",
 5            "group_property": "grp:Group Property 1",
 6            "description": "First Group Property",
 7            "type": "string",
 8            "enum_values": null,
 9            "regex": null,
10            "is_array_type": false,
11            "classifications": ["PII"]
12    },
13}

400 Bad Request response

If Amplitude can't find the group property, or you configure the request incorrectly, it returns a 400 Bad Request response and an error message.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Not found"
6        }
7    ]
8}

Update group property

Update a group property.

PUT https://amplitude.com/api/2/taxonomy/group-property/:group_property

1curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/group-property/GROUP_PROPERTY' \
2-u '{api_key}:{secret_key}' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'group_type=GROUP_TYPE' \

1 
2PUT /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1
3Host: amplitude.com
4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 24
7 
8group_type=GROUP_NAME

Example: Update a group property

This example updates the "Group Property 1" property. It changes the name to "Group Property 1 - Renamed" and adds a description.

1 
2curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/group-property/grp:Group Property 1' \
3--header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \
4--header 'Content-Type: application/x-www-form-urlencoded' \
5--data-urlencode 'description=First Group Property Updated' \
6--data-urlencode 'new_group_property_value=grp:Group Property - Renamed' \

1 
2PUT /api/2/taxonomy/group-property/grp:Group Property 1 HTTP/1.1
3Host: amplitude.com
4Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==
5Content-Type: application/x-www-form-urlencoded
6Content-Length: 130
7 
8group_type=Group%201&description=First%20Group%20Property%20Updated&new_group_property_value=grp%3AGroup%20Property%201%20Renamed

Path parameters

Name	Description
`group_property`	Required. Name of the group property. Prefix custom group properties with `grp:`. Amplitude-sourced group properties (names without the `grp:` prefix) aren't editable.

Body parameters

Name	Description
`group_type`	Optional. Name of the group type the group property belongs to. If the group type doesn't exist, Amplitude returns a `404 Not Found` error.
`overrideScope`	Optional. Determines how we should act on this group property. Only applicable if `group_type` is present. If `overrideScope` is not present, Amplitude updates property override on the group type if it exists on the group type, or the shared property if no override exists on the group type. With `overrideScope: "override"`, Amplitude creates an override if none exists on the group type, then updates that overridden property, or updates the existing override if one already exists. With `overrideScope: "shared"`, Amplitude removes the property override on the group type if one exists on the group type, then updates the shared property, or it updates the shared property if no property override exists.
`description`	Optional. String. Description of the group property.
`new_group_property_value`	Optional. String. The new name of the group property.
`type`	Optional. String. Data type of the group property. It must be one of `any` (default), `string` (default if array type is true), `number`, `boolean`, `enum`
`regex`	Optional. String. Regular expression, custom regex used for pattern matching or more complex values. For example, property zip code must have pattern `[0-9]{5}` Applies only to the `string` type.
`enum_values`	Optional. String. List of allowed values, separated by comma. For example: `red, yellow, blue`. Only applicable to the `enum` type.
`is_array_type`	Optional. Boolean. Property is an array type. Use the `type` parameter to set the type of array elements.
`classifications`	Optional. String. Only available if Data Access Controls is enabled at the account level. List of classifications applicable to this group property. Valid classifications are `PII`, `SENSITIVE` and `REVENUE`. You can only apply classifications on shared properties. Trying to set classifications on an overridden property results in an error.

200 OK response

A successful request returns a 200 OK status and a JSON body.

1{
2    "success": true
3}

409 conflict response

Some failed requests return a 409 Conflict and an error message with more details.

1{
2    "success": false,
3    "errors": [
4        {
5            "message": "Attempted to update classifications for an overridden group property, \"grp:Group Property 1\" on group type \"Group 1\". Call the Update API without the \"group_type\" parameter to update classifications of the shared property."
6        }
7    ]
8}