The Taxonomy API grants Scholarship, Growth, and 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
1curl --location --request POST 'https://amplitude.com/api/2/taxonomy/category' \2--header 'Authorization: Basic {api-key}:{secret-key}' \ #credentials must be base64 encoded3--header 'Content-Type: application/x-www-form-urlencoded' \4--data-urlencode 'category_name=CATEGORY_NAME'
1POST /api/2/taxonomy/category HTTP/1.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded4Content-Type: application/x-www-form-urlencoded5category_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:
1{2 "success" : true3}
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 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
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 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example get the ID for the event category named "Attribution".
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:
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded4Content-Type: application/x-www-form-urlencoded5Content-Length: 236 7category_name=NEW_NAME
This example renames the category with the ID
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.
1{2 "success": true3}
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. 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example deletes the category with the ID
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.
1{2 "success": true3}
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}
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.
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded4Content-Type: application/x-www-form-urlencoded5Content-Length: 806 7event_type=EVENT_TYPE&category=CATEGORY_NAME&description=CATEGORY_DESCRIPTION
This example creates the event type "Onboarding Start" with the category "Onboarding" and a description of "My new onboarding event".
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:
1{2 "success" : true3}
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}
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
1curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event' \2-u '{api_key}:{secret_key}'
1GET /api/2/taxonomy/event HTTP/1.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
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": null10 },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 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example gets the "Event 2" event type. This is a custom event, so it has a
Example: Get an event type by name
ce:
prefix.
Name |
Description |
---|---|
event_type |
Required. String. The event name. Prefix custom event types with ce: . |
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": "ce:Event 2", 5 "category": { 6 "name": "Conversion Events" 7 }, 8 "description": null 9 }10}
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. 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded4Content-Length: 415 6category=NEW_CATEGORY_NAME&display_name=NEW_EVENT_TYPE_DISPLAY_NAME
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". Because the event type is custom, it has the
Example: Update an event type
ce:
prefix.
Name |
Description |
---|---|
event_type |
Required. String. The event name. Prefix custom event types with ce: . |
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.
1{2 "success": true3}
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 \"ce:Event\", but the event is not in schema."6 }7 ]8}
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example deletes the event type "Event1". Because the event type is custom, it has the
Example: Delete an event type
ce:
prefix.
Name |
Description |
---|---|
event_type |
Required. The name of the event type. Prefix custom event types with ce: . |
A successful request returns a 200 OK
status and a JSON body.
1{2 "success": true3}
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 remove an event, \"ce:Event1\", that is not a planned event."6 }7 ]8}
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
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded4Content-Type: application/x-www-form-urlencoded5Content-Length: 946 7event_type=EVENT_TYPE&event_property=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, is not required.
Example: Create an event property
Name |
Description |
---|---|
event_type |
Required. String. Name of the event type to which the event properties belong to. |
event_property |
Required. String. Name of the event property. |
description |
Optional. String. The event property's description. |
type |
Optional. String. Available with Govern Add-on. The event property's data type. Acceptable values are string , number , boolean , enum , and any |
regex |
Optional. String. Available with Govern Add-on. 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. Available with Govern Add-on. List of allowed values. |
is_array_type |
Optional. Boolean. Available with Govern Add-on. |
is_required |
Optional. Boolean. Available with Govern Add-on. Marks the property as required. When true , Amplitude flags events that are missing this property on the Taxonomy page in the web app. |
A successful request returns a 200 OK
status and a JSON body.
1{2 "success": true3}
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 an event's 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.13Host: amplitude.com4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded5 6event_type=EVENT_NAME
This example gets all event properties for the "Onboard Start" event.
Example: get all of an event's properties
Name |
Description |
---|---|
event_type |
Required. Name of the event type to which the event properties belong to. |
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": false13 },14 {15 "event_property": "Completed Tutorial",16 "event_type": "Onboard Start",17 "description": "",18 "type": "any",19 "regex": null,20 "enum_values": null,21 "is_array_type": false,22 "is_required": false23 }24 ]25}
Get a single event property. Send a GET
request with the event property name as a path parameter, and 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded4 5event_type=EVENT_NAME
This example gets a the "Completed Task" property for the "Onboard Start" event.
Example: Get a property from a specific event
Name |
Description |
---|---|
event_property |
Required. The event property name. |
Name |
Description |
---|---|
event_type |
Required. Name of the event type to which the event properties belong to. |
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": false12 }13}
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 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.13Host: amplitude.com4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded5Content-Type: application/x-www-form-urlencoded6Content-Length: 247 8event_type=EVENT_NAME
This example updates a the "Completed Task" property. It changes the name to "Task Completed" and adds a description.
Example: Update an event property
Name |
Description |
---|---|
event-property |
Required. Name of the event property. |
Name |
Description |
---|---|
event_type |
Required. Name of the event type to which the event properties belong to. |
description |
Optional. String. The event property's description. |
new_event_property_value |
Optional. String. Available with Govern Add-on. The new name of the event property. |
type |
Optional. String. Available with Govern Add-on. The event property's data type. Acceptable values are string , number , boolean , enum , and any |
regex |
Optional. String. Available with Govern Add-on. 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. Available with Govern Add-on. List of allowed values. |
is_array_type |
Optional. Boolean. Available with Govern Add-on. |
is_required |
Optional. Boolean. Available with Govern Add-on. Marks the property as required. |
A successful request returns a 200 OK
status and a JSON body.
1{2 "success": true3}
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. Send a DELETE
request with the event property as a path parameter and 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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded4 5event_type=EVENT_NAME
This example deletes the event property "Completed Task" from the "Onboarding Start" event.
Example: Delete an event property
Name |
Description |
---|---|
event_property |
Required. The event property name. |
Name |
Description |
---|---|
event_type |
Required. Name of the event type to which the event properties belong to. |
A successful request returns a 200 OK
status and a JSON body.
1{2 "success": true3}
User properties reflect traits about the individuals using your product.
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded4 5user_property=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
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. |
This request returns either a true or false response.
1{2 "success" : true3}
1{2 "success" : false3}
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.12Host: amplitude.com3Authorization: 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.
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": false11 },
12 {13 "user_property": "event_id",14 "description": null,15 "type": null,16 "enum_values": null,17 "regex": null,18 "is_array_type": false19 },20 {21 "user_property": "amplitude_id",22 "description": null,23 "type": null,24 "enum_values": null,25 "regex": null,26 "is_array_type": false27 },28 {29 "user_property": "location_lat",30 "description": null,31 "type": null,32 "enum_values": null,33 "regex": null,34 "is_array_type": false35 },36 {37 "user_property": "location_lng",38 "description": null,39 "type": null,40 "enum_values": null,41 "regex": null,42 "is_array_type": false43 },44 {45 "user_property": "server_upload_time",46 "description": null,47 "type": null,48 "enum_values": null,49 "regex": null,50 "is_array_type": false51 },52 {53 "user_property": "session_id",54 "description": null,55 "type": null,56 "enum_values": null,57 "regex": null,58 "is_array_type": false59 },60 {61 "user_property": "user_id",62 "description": null,63 "type": null,64 "enum_values": null,65 "regex": null,66 "is_array_type": false67 } 68 ]69}
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example gets the
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.
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": false10 }11}
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 or the Govern add-on enabled. 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
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.12Host: amplitude.com3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded4Content-Type: application/x-www-form-urlencoded5Content-Length: 376 7new_user_property_value=VALUE&description=DESCRIPTION
This example updates a user property called "user_type" to be named "subscription_type", adds a description of "The user's subscription type", and changes the property's data type to
Example: Update a user property
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} . |
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. |
This request returns either a true or false response.
1{2 "success" : true3}
1{2 "success" : false3}
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}'
1 2DELETE /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.13Host: amplitude.com4Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
This example deletes a custom user property "interests". Notice that the user property is prefixed with
Example: Delete a user property
gp:
.
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 message.
1{2 "success": true3}
A failed request returns a 409 Bad Request
status and an error message.
1{2 "success": false,3 "errors": [4 {5 "message": "Attempted to remove a user property, \"sdf\", that is not a planned user property."6 }7 ]8}
Thanks for your feedback!
May 21st, 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.