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.
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
Region | Endpoint |
---|---|
Standard server | https://amplitude.com/api/2/ |
EU residency server | https://analytics.eu.amplitude.com/api/2/ |
Play Song
as Play%20Song
. Use the W3Schools encoding reference.gp:
prefix. For example, gp:my_custom_property
.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:
Cost structure of each endpoint:
Event categories are a way to organize your event types into broad groups.
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:
Create an event category in your project.
POST /api/2/taxonomy/category
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/category' \--header 'Authorization: Basic {api-key}:{secret-key}' \ #credentials must be base64 encoded--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'category_name=CATEGORY_NAME'
POST /api/2/taxonomy/category HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedcategory_name=CATEGORY_NAME
Example: Create an event category
Name |
Description |
---|---|
category_name |
Required. Name of the category. |
A successful request returns a 200 OK
response with a JSON body:
{ "success" : true}
A failed request sends an error message with more information:
{ "success" : false, "errors" : [ { "message" : "error info" } ]}
Get all event categories in your project.
GET https://amplitude.com/api/2/taxonomy/category
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category' \-u '{api_key}:{secret_key}'
GET /api/2/taxonomy/category HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
A successful request returns a 200 OK
status with a JSON body:
{ "success": true, "data": [ { "id": 412931, "name": "Attribution" }, { "id": 412941, "name": "Conversion" } ]}
A failed request returns a 400 Bad Request
response with more information.
{ "success": false, "errors": [ { "message": "Not found" } ]}
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
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category/:category_name' \-u '{api_key}:{secret_key}'
GET /api/2/taxonomy/category/:category_name HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Get a category's ID
Name |
Description |
---|---|
category_name |
Required. The name of the category |
A successful request returns a 200 OK
status and a JSON body with the category's data:
{ "success": true, "data": { "id": 412941, "name": "Conversion" }}
A failed request returns a 400 Bad Request
status with more information about the error.
{ "success": false, "errors": [ { "message": "Not found" } ]}
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
curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/category/CATEGORY_ID' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'category_name=NEW_NAME'
PUT /api/2/taxonomy/category/CATEGORY_ID HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 23category_name=NEW_NAME
Example: Rename a category
412941
to "Converted".
Name |
Description |
---|---|
category_id |
Required. The ID of the category |
Name |
Description |
---|---|
category_name |
Required. The new name of the category |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there is a problem with your request, the request returns a 409 Conflict
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Attempted to operate on entity event_category, id \"4129\", that does not exist." } ]}
Delete an event category. Send a DELETE
request with the category ID.
DELETE https://amplitude.com/api/2/taxonomy/category/:category_id
curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/category/:category_id' \-u '{api_key}:{secret_key}'
DELETE /api/2/taxonomy/category/:category_id HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Delete a category
412941
.
Name |
Description |
---|---|
category_id |
Required. The ID of the category |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there is a problem with your request, the request returns a 409 Conflict
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Attempted to operate on entity event_category, id \"412941\", that does not exist." } ]}
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.
Creates an event type. Send a POST
request to https://amplitude.com/api/2/taxonomy/event
and include a body with your parameters.
Initialize the schema before you can add event types via the API.
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_TYPE' \--data-urlencode 'category=CATEGORY_NAME' \--data-urlencode 'description=DESCRIPTION'
POST /api/2/taxonomy/event?=null HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} # credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 80event_type=EVENT_TYPE&category=CATEGORY_NAME&description=CATEGORY_DESCRIPTION
Example: Create an event type
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. |
A successful request returns a 200 OK
response with a JSON body:
{ "success" : true}
A failed request returns a 409 Conflict
status with an error message.
{ "success" : false, "errors" : [ { "message" : "error info" } ]}
Retrieves all event types in a project. This request has no required parameters.
GET https://amplitude.com/api/2/taxonomy/event
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
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event' \-u '{api_key}:{secret_key}'
GET /api/2/taxonomy/event HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
A successful request returns a 200 OK
status with a JSON body:
{ "success": true, "data": [ { "event_type": "Attribution", "category": { "name": "Attribution Events" }, "description": null }, { "event_type": "Conversation", "category": { "name": "Conversion Events" }, "description": "This event is fired when a user converts." } ]}
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
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event:event_type' \-u '{api_key}:{secret_key}'
GET /api/2/taxonomy/event/:event_type HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Get an event type by name
Name |
Description |
---|---|
event_type |
Required. String. The event name. |
A successful request returns a 200 OK
status and a JSON body with the event type's data:
{ "success": true, "data": { "event_type": "Event 2", "category": { "name": "Conversion Events" }, "description": null }}
A failed request returns a 400 Bad Request
status with more information about the error.
{ "success": false, "errors": [ { "message": "Not found" } ]}
Update an event type. Send a PUT
request with the event type name.
PUT https://amplitude.com/api/2/taxonomy/event/:event_type
curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE_NAME' \-u '{api_key}:{secret_key}'--data-urlencode 'category=NEW_CATEGORY_NAME' \--data-urlencode 'display_name=NEW_EVENT_TYPE_DISPLAY_NAME'
PUT /api/2/taxonomy/event/EVENT_TYPE_NAME HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} # credentials must be base64 encodedContent-Length: 41category=NEW_CATEGORY_NAME&display_name=NEW_EVENT_TYPE_DISPLAY_NAME
Example: Update an 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".
Name |
Description |
---|---|
event_type |
Required. String. The event name. |
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there is a problem with your request, the request returns a 409 Conflict
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Attempted to change the event display name for event \"Event\", but the event is not in schema." } ]}
Delete an event type.
DELETE https://amplitude.com/api/2/taxonomy/event/:event_type
curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE'-u '{api_key}:{secret_key}'
DELETE /api/2/taxonomy/event/EVENT_TYPE HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Delete an event type
Event1
.
Name |
Description |
---|---|
event_type |
Required. The name of the event type. |
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 |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there's a problem with the request, Amplitude returns a 4XX
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Not found" } ]}
Restore an event type.
POST https://amplitude.com/api/2/taxonomy/event/:event_type/restore
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE/restore'-u '{api_key}:{secret_key}'
POST /api/2/taxonomy/event/EVENT_TYPE/restore HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Restore an event type
Name |
Description |
---|---|
event_type |
Required. The name of the event type. |
Event type | Behavior in Amplitude |
---|---|
deleted |
Restores the event |
not deleted or not found |
Returns an error |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there's a problem with your request, Amplitude returns a 4XX
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Not found" } ]}
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. Send a POST
request to the endpoint with the required information in the body.
POST https://amplitude.com/api/2/taxonomy/event-property
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_TYPE' \--data-urlencode 'event_property=EVENT_PROPERTY' \
POST /api/2/taxonomy/event-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 94event_type=EVENT_TYPE&event_property=EVENT_PROPERTY
Example: Create an event property
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there is a problem with your request, the request returns a 409 Conflict
status, and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Attempted to add an event property, \"Completed Task\" for event \"Onboard Start\", that already exists." } ]}
Get shared or event-specific event properties.
GET https://amplitude.com/api/2/taxonomy/event-property
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_NAME'
GET /api/2/taxonomy/event-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedevent_type=EVENT_NAME
Example: get all of an event's properties
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. |
A successful request returns a 200 OK
status and a JSON body with a list of event properties and their data.
{ "success": true, "data": [ { "event_property": "Completed Task", "event_type": "Onboard Start", "description": "User completed a task during onboarding.", "type": "boolean", "regex": null, "enum_values": null, "is_array_type": false, "is_required": false, "classifications": ["PII"] }, { "event_property": "Completed Tutorial", "event_type": "Onboard Start", "description": "", "type": "any", "regex": null, "enum_values": null, "is_array_type": false, "is_required": false, "classifications": [] } ]}
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
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property?event_property=EVENT_PROPERTY' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_NAME'
GET /api/2/taxonomy/event-property/EVENT_PROPERTY_NAME HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedevent_type=EVENT_NAME
Example: Get a property from a specific event
Name |
Description |
---|---|
event_property |
Required. The event property name. |
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. |
A successful request returns a 200 OK
status and a JSON body containing information about the event property.
{ "success": true, "data": { "event_property": "Shared", "event_type": "Onboard Finish", "description": "Whether user shared content.", "type": "boolean", "regex": null, "enum_values": null, "is_array_type": false, "is_required": false, "classifications": ["PII"] }}
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.
{ "success": false, "errors": [ { "message": "Not found" } ]}
Update an event property.
PUT https://amplitude.com/api/2/taxonomy/event-property/:event-property
curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_NAME' \
PUT /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 24event_type=EVENT_NAME
Example: Update an event property
Name |
Description |
---|---|
event-property |
Required. Name of the event property. |
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
Some failed requests return a 409 Conflict
and an error message with more details.
{ "success": false, "errors": [ { "message": "Attempted to change the event property description for property \"Completed Task\" for event \"\", but the property is not in schema." } ]}
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
curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY' \--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'event_type=EVENT_NAME'
DELETE /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} # credentials must be base64 encodedevent_type=EVENT_NAME
Example: Delete an event property
Name |
Description |
---|---|
event_property |
Required. The event property name. |
Name |
Description |
---|---|
event_type |
Optional. Name of the event type to which the event properties belong. |
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
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
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property/EVENT_PROPERTY/restore' \--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded
POST /api/2/taxonomy/event-property/EVENT_PROPERTY/restore HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded
Example: Delete an event property
Name |
Description |
---|---|
event_property |
Required. The event property name. |
Event property | Behavior in Amplitude |
---|---|
deleted |
Restores the event property |
not deleted or not found |
Returns an error |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
User properties reflect traits about the individuals using your product.
Create a user property.
POST https://amplitude.com/api/2/taxonomy/user-property/
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property' \--header 'Authorization: Basic {api-key}:{secret-key}' # credentials must be base64 encoded \--data-urlencode 'user_property=USER_PROPERTY' \
POST /api/2/taxonomy/user-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} # credentials must be base64 encodeduser_property=USER_PROPERTY
Example: Create a user property
string
and allows the values "Free", "Standard", and "Premium".
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 . |
This request returns either a true or false response.
{ "success" : true}
{ "success" : false}
Retrieves all user properties in your account. This call doesn't have any required parameters.
GET https://amplitude.com/api/2/taxonomy/user-property
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property' \-u '{api_key}:{secret_key}''
GET /api/2/taxonomy/user-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
A successful request returns a 200 OK
response and a JSON body with user property details.
{ "success": true, "data": [ { "user_property": "device_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": ["PII"] }, //[tl! collapse:start] { "user_property": "event_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "amplitude_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "location_lat", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "location_lng", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "server_upload_time", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "session_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, { "user_property": "user_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] } //[tl! collapse:end] ]}
Retrieves a single user property, by name.
GET https://amplitude.com/api/2/taxonomy/user-property/:user_property
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \-u '{api_key}:{secret_key}'
GET /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Get a user property
device_id
user property.
Name |
Description |
---|---|
user_property |
Required. The user property name. Prefix custom user properties with gp: . |
A successful request returns a 200 OK
response and a JSON body with user property details.
{ "success": true, "data": { "user_property": "device_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "classifications": ["PII"] }}
A failed request returns a 404 Bad Request
status and an error message.
{ "success": false, "errors": [ { "message": "Not found" } ]}
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.
PUT https://amplitude.com/api/2/taxonomy/user-property/:user_property
curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \-u '{api_key}:{secret_key}'--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'new_user_property_value=VALUE' \--data-urlencode 'description=DESCRIPTION'
PUT /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 37new_user_property_value=VALUE&description=DESCRIPTION
Example: Update a user property
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.
Name |
Description |
---|---|
user_property |
Required. The user property name. Prefix custom user properties with gp: . |
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 . |
This request returns either a true or false response.
{ "success" : true}
{ "success" : false}
Deletes a single user property, by name.
DELETE https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY
curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \-u '{api_key}:{secret_key}'
DELETE /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Delete a user property
gp:
.
Name |
Description |
---|---|
user_property |
Required. The user property name. Prefix custom user properties with gp: . |
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 |
A successful request returns a 200 OK
response and a JSON message.
{ "success": true}
Restore a single user property, by name.
POST https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore' \-u '{api_key}:{secret_key}'
POST /api/2/taxonomy/user-property/USER_PROPERTY/restore HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Example: Restore a user property
interests
. Notice that the user property is prefixed with gp:
.
Name |
Description |
---|---|
user_property |
Required. The user property name. Prefix custom user properties with gp: . |
User property | Behavior in Amplitude |
---|---|
deleted |
Restores the user property |
not deleted or not found |
Returns an error |
A successful request returns a 200 OK
response and a JSON message.
{ "success": true}
Group properties are properties at the account level. They apply to all users who belong to that account.
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
curl --location --request POST 'https://amplitude.com/api/2/taxonomy/group-property' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'group_type=GROUP_TYPE' \--data-urlencode 'group_property=GROUP_PROPERTY' \
POST /api/2/taxonomy/group-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 94group_type=GROUP_TYPE&group_property=GROUP_PROPERTY
Example: Create a group property
Group Property 1
with the description "First group property" for the group Group 1
. The group property is a boolean type.
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
If there's a problem with your request, the request returns a 409 Conflict
status and a JSON body with more information.
{ "success": false, "errors": [ { "message": "Attempted to add a group property, \"Group Property 1\", that already exists." } ]}
Get shared or group-specific group properties.
GET https://amplitude.com/api/2/taxonomy/group-property
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'group_type=GROUP_TYPE'
GET /api/2/taxonomy/group-property HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedgroup_type=GROUP_TYPE
Example: get all of a group's properties
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. |
A successful request returns a 200 OK
status and a JSON body with a list of group properties and their data.
{ "success": true, "data": [ { "group_type": "Group 1", "group_property": "grp:Group Property 1", "description": "First Group Property", "type": "string", "enum_values": null, "regex": null, "is_array_type": false, "classifications": ["PII"] }, { "group_type": "Group 1", "group_property": "grp:Group Property 2", "description": "Second Group Property", "type": "string", "enum_values": null, "regex": null, "is_array_type": false, "classifications": [] }, ]}
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
curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property/GROUP_PROPERTY' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'group_type=GROUP_TYPE'
GET /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedgroup_type=GROUP_TYPE
Example: Get a property from a specific group type
Group Property 1
for the Group 1
group type.
Name |
Description |
---|---|
group_property |
Required. The group property name. Prefix custom group properties with grp: . |
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. |
A successful request returns a 200 OK
status and a JSON body containing information about the group property.
{ "success": true, "data": { "group_type": "Group 1", "group_property": "grp:Group Property 1", "description": "First Group Property", "type": "string", "enum_values": null, "regex": null, "is_array_type": false, "classifications": ["PII"] },}
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.
{ "success": false, "errors": [ { "message": "Not found" } ]}
Update a group property.
PUT https://amplitude.com/api/2/taxonomy/group-property/:group_property
curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/group-property/GROUP_PROPERTY' \-u '{api_key}:{secret_key}' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'group_type=GROUP_TYPE' \
PUT /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1Host: amplitude.comAuthorization: Basic {api-key}:{secret-key} #credentials must be base64 encodedContent-Type: application/x-www-form-urlencodedContent-Length: 24group_type=GROUP_NAME
Example: Update a group property
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. |
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. |
A successful request returns a 200 OK
status and a JSON body.
{ "success": true}
Some failed requests return a 409 Conflict
and an error message with more details.
{ "success": false, "errors": [ { "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." } ]}
Thanks for your feedback!
October 15th, 2024
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.