## Regions The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table. Requests go to `https://amplitude.com` (default) or `https://analytics.eu.amplitude.com` (EU). The `https://analytics.amplitude.com` hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not `analytics.amplitude.com`. | Data residency | Base URL | | -------------- | ------------------------------------ | | Default | `https://amplitude.com` | | EU | `https://analytics.eu.amplitude.com` | ## 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`. Refer to the [W3Schools](http://www.w3schools.com/tags/ref_urlencode.asp) 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 through this API. ## Limits Each endpoint has a concurrent limit and a rate limit. The concurrent limit restricts how many requests you can run at the same time. The rate limit restricts the total number of queries per hour. Limits are per project. Exceeding any limit returns a 429 error. The endpoints use a cost per query model. Max costs per API key: - **Concurrent Cost Limit:** Run queries that collectively add up to 4 cost at the same time. - **Period Cost Limit:** 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. {% callout type="example" heading="" %} To track how users register for your app, checkout, and interact with the onboarding experience, group your events using these event categories: - Registration - Checkout - Onboarding {% /callout %} ### Create event category Create an event category in your project. `POST /api/2/taxonomy/category` {% code-group %} ```curl cURL 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' ``` ```bash HTTP POST /api/2/taxonomy/category HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded category_name=CATEGORY_NAME ``` {% /code-group %} {% accordion title="Example: Create an event category" %} {% code-group %} ```curl cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/category' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'category_name=Attribution' ``` ```bash HTTP POST /api/2/taxonomy/category HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Type: application/x-www-form-urlencoded Content-Length: 25 category_name=Attribution ``` {% /code-group %} {% /accordion %} #### Body parameters | Name | Description | | --------------- | ------------------------------- | | `category_name` | Required. Name of the category. | #### Response A successful request returns a `200 OK` response with a JSON body: ```json { "success": true } ``` A failed request sends an error message with more information: ```json { "success": false, "errors": [ { "message": "error info" } ] } ``` ### Get all event categories Get all event categories in your project. `GET https://amplitude.com/api/2/taxonomy/category` {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/2/taxonomy/category HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} #### Response A successful request returns a `200 OK` status with a JSON body: ```json { "success": true, "data": [ { "id": 412931, "name": "Attribution" }, { "id": 412941, "name": "Conversion" } ] } ``` A failed request returns a `400 Bad Request` response with more information. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Get an event category Get the ID of an event category in your project by sending a `GET` request with the category name. `GET https://amplitude.com/api/2/taxonomy/category/:category_name` {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category/:category_name' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/2/taxonomy/category/:category_name HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Get a category's ID" %} This example get the ID for the event category named "Attribution". {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/category/Attribution' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/2/taxonomy/category/Attribution HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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: ```json { "success": true, "data": { "id": 412941, "name": "Conversion" } } ``` A failed request returns a `400 Bad Request` status with more information about the error. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Update an event category Update the name of an event category by sending a `PUT` request with the category ID and a new name in the body. `PUT https://amplitude.com/api/2/taxonomy/category/:category_id` {% code-group %} ```curl cURL 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' ``` ```bash HTTP PUT /api/2/taxonomy/category/CATEGORY_ID HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 23 category_name=NEW_NAME ``` {% /code-group %} {% accordion title="Example: Rename a category" %} This example renames the category with the ID `412941` to "Converted". {% code-group %} ```curl cURL curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/category/412941' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'category_name=Converted' ``` ```bash HTTP PUT /api/2/taxonomy/category/412941 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Type: application/x-www-form-urlencoded Content-Length: 23 category_name=Converted ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Attempted to operate on entity event_category, id \"4129\", that does not exist." } ] } ``` ### Delete an event category Delete an event category by sending a `DELETE` request with the category ID. `DELETE https://amplitude.com/api/2/taxonomy/category/:category_id` {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/category/:category_id' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP DELETE /api/2/taxonomy/category/:category_id HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Delete a category" %} This example deletes the category with the ID `412941`. {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/category/412941' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP DELETE /api/2/taxonomy/category/412941 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Attempted to operate on entity event_category, id \"412941\", that does not exist." } ] } ``` ## 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. Use the Taxonomy API to create, get, update, delete, and restore event types. ### Create an event type Create an event type by sending a `POST` request to `https://amplitude.com/api/2/taxonomy/event` with parameters in the body. {% callout type="note" heading="" %} [Initialize the schema](/docs/data/amplitude-data-settings) before you add event types through the API. {% /callout %} {% code-group %} ```bash cURL 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' ``` ```bash HTTP POST /api/2/taxonomy/event?=null HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 80 event_type=EVENT_TYPE&category=CATEGORY_NAME&description=CATEGORY_DESCRIPTION ``` {% /code-group %} {% accordion title="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". {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'event_type=Onboard Start' \ --data-urlencode 'category=Onboarding' \ --data-urlencode 'description=My new onboarding event. ' \ ``` ```bash HTTP POST /api/2/taxonomy/event HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 92 event_type=Onboard%20Start&category=Onboarding&description=My%20new%20onboarding%20event.%20 ``` {% /code-group %} {% /accordion %} #### 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. | | `is_active` | Optional. Boolean. Activity of the event type. | | `is_hidden_from_dropdowns` | Optional. Boolean. Event type is hidden from dropdowns. | | `is_hidden_from_persona_results` | Optional. Boolean. Event type is hidden from persona results. | | `is_hidden_from_pathfinder` | Optional. Boolean. Event type is hidden from pathfinder. | | `is_hidden_from_timeline` | Optional. Boolean. Event type is hidden from timeline. | | `tags` | Optional. String. List of tags, separated by a comma. | | `owner` | Optional. String. Owner of the event type. | {% callout type="note" heading="" %} `is_hidden_from_dropdowns`, `is_hidden_from_persona_results`, `is_hidden_from_pathfinder` and `is_hidden_from_timeline` properties can only be set on ingested event types. {% /callout %} #### 200 ok response A successful request returns a `200 OK` response with a JSON body: ```json { "success": true } ``` #### 409 conflict response A failed request returns a `409 Conflict` status with an error message. ```json { "success": false, "errors": [ { "message": "error info" } ] } ``` ### 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` {% callout type="note" heading="" %} Hidden events (those with a visibility other than "Visible") don't appear in the response. By default, the response excludes deleted events. To include them, add the `showDeleted` query parameter: `GET https://amplitude.com/api/2/taxonomy/event?showDeleted=true` {% /callout %} {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/2/taxonomy/event HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} #### 200 OK response A successful request returns a `200 OK` status with a JSON body: ```json { "success": true, "data": [ { "event_type": "Attribution", "category": { "name": "Attribution Events" }, "description": null, "display_name": null, "is_active": false, "is_hidden_from_dropdowns": false, "is_hidden_from_persona_results": false, "is_hidden_from_pathfinder": false, "is_hidden_from_timeline": false, "tags": [], "owner": null }, { "event_type": "Conversation", "category": { "name": "Conversion Events" }, "description": "This event is fired when a user converts.", "display_name": "User Conversion", "is_active": false, "is_hidden_from_dropdowns": false, "is_hidden_from_persona_results": false, "is_hidden_from_pathfinder": false, "is_hidden_from_timeline": false, "tags": [], "owner": null } ] } ``` ### 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` {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event:event_type' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/2/taxonomy/event/:event_type HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Get an event type by name" %} This example gets the 'Event 2' event type. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event/Event 2' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event/Event 2' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` {% /code-group %} {% /accordion %} #### 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: ```json { "success": true, "data": { "event_type": "Event 2", "category": { "name": "Conversion Events" }, "description": null, "display_name": null, "is_active": false, "is_hidden_from_dropdowns": false, "is_hidden_from_persona_results": false, "is_hidden_from_pathfinder": false, "is_hidden_from_timeline": false, "tags": [], "owner": null } } ``` #### 400 Bad Request response A failed request returns a `400 Bad Request` status with more information about the error. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Update an event type Update an event type by sending a `PUT` request with the event type name. `PUT https://amplitude.com/api/2/taxonomy/event/:event_type` {% code-group %} ```bash cURL 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' ``` ```bash HTTP PUT /api/2/taxonomy/event/EVENT_TYPE_NAME HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded Content-Length: 41 category=NEW_CATEGORY_NAME&display_name=NEW_EVENT_TYPE_DISPLAY_NAME ``` {% /code-group %} {% accordion title="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". {% code-group %} ```bash cURL curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event/OnboardBegin' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'new_event_type=OnboardStart' \ --data-urlencode 'category=Onboarding' \ --data-urlencode 'description=User signed in and completed an onboarding task from modal.' \ --data-urlencode 'display_name=Onboarding Start' ``` ```bash HTTP PUT /api/2/taxonomy/event/OnboardBegin HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Type: application/x-www-form-urlencoded Content-Length: 169 new_event_type=OnboardStart&category=Onboarding&description=User%20signed%20in%20and%20completed%20an%20onboarding%20task%20from%20modal.&display_name=Onboarding%20Start ``` {% /code-group %} {% /accordion %} #### 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. | | `is_active` | Optional. Boolean. Activity of the event type. | | `is_hidden_from_dropdowns` | Optional. Boolean. Event type is hidden from dropdowns. | | `is_hidden_from_persona_results` | Optional. Boolean. Event type is hidden from persona results. | | `is_hidden_from_pathfinder` | Optional. Boolean. Event type is hidden from pathfinder. | | `is_hidden_from_timeline` | Optional. Boolean. Event type is hidden from timeline. | | `tags` | Optional. String. List of tags, separated by a comma. | | `owner` | Optional. String. Owner of the event type. | {% callout type="note" heading="" %} `is_hidden_from_dropdowns`, `is_hidden_from_persona_results`, `is_hidden_from_pathfinder` and `is_hidden_from_timeline` properties can only be set on ingested event types. {% /callout %} #### 200 OK response A successful request returns a `200 OK` status and a JSON body. ```json { "success": true } ``` #### 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. ```json { "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 an event type by sending a `DELETE` request with the event type name as a path parameter. `DELETE https://amplitude.com/api/2/taxonomy/event/:event_type` {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE' -u '{api_key}:{secret_key}' ``` ```bash HTTP DELETE /api/2/taxonomy/event/EVENT_TYPE HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Delete an event type" %} This example deletes the event type `Event1`. {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event/Event1' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ ``` ```bash HTTP DELETE /api/2/taxonomy/event/Event1 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` #### 4XX responses If there's a problem with the request, Amplitude returns a `4XX` status, and a JSON body with more information. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Restore an event type Restore an event type by sending a `POST` request with the event type name as a path parameter. `POST https://amplitude.com/api/2/taxonomy/event/:event_type/restore` {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event/EVENT_TYPE/restore' -u '{api_key}:{secret_key}' ``` ```bash HTTP POST /api/2/taxonomy/event/EVENT_TYPE/restore HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Restore an event type" %} This example restores the event type "Event1". {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event/Event1/restore' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP POST /api/2/taxonomy/event/Event1/restore HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` #### 4XX responses If there's a problem with your request, Amplitude returns a `4XX` status, and a JSON body with more information. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ## Event property Event properties describe the attributes of an event. For example, if `Swipe` is an event that you track, the event property `Direction` could have the values `Left` or `Right`. ### Create an event property Create an event property by sending a `POST` request with the required information in the body. `POST https://amplitude.com/api/2/taxonomy/event-property` {% code-group %} ```bash cURL 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' \ ``` ```bash HTTP POST /api/2/taxonomy/event-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 94 event_type=EVENT_TYPE&event_property=EVENT_PROPERTY ``` {% /code-group %} {% accordion title="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 and isn't required. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'event_type=Onboard Start' \ --data-urlencode 'event_property=Completed Task' \ --data-urlencode 'description=User completed any onboarding task' \ --data-urlencode 'type=boolean' \ --data-urlencode 'is_required=false' ``` ```bash HTTP POST /api/2/taxonomy/event-property HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 144 event_type=Onboard%20Start&event_property=Completed%20Task&type=boolean&is_required=false&description=User%20completed%20any%20onboarding%20task ``` {% /code-group %} {% /accordion %} #### Body parameters | Name | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_property` | Required. String. Name of the event property. | | `event_type` | Optional. String. Name of the event type 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 exists but not on this event type, Amplitude creates an override for the property. If the event property doesn't exist anywhere, Amplitude doesn't create an override. | | `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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### 200 OK response A successful request returns a `200 OK` status and a JSON body. ```json { "success": true } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Attempted to add an event property, \"Completed Task\" for event \"Onboard Start\", that already exists." } ] } ``` ### Get event properties Get shared or event-specific event properties. `GET https://amplitude.com/api/2/taxonomy/event-property` {% code-group %} ```bash cURL 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' ``` ```bash HTTP GET /api/2/taxonomy/event-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded event_type=EVENT_NAME ``` {% /code-group %} {% accordion title="Example: get all of an event's properties" %} This example gets all event properties for the "Onboard Start" event. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'event_type=Onboard Start' ``` ```bash HTTP GET /api/2/taxonomy/event-property HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 26 event_type=Onboard%20Start ``` {% /code-group %} {% /accordion %} #### Body parameters | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event_type` | Required. Name of the event type 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. ```json { "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, "is_hidden": 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, "is_hidden": false, "classifications": [] } ] } ``` ### 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` {% code-group %} ```bash cURL 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' ``` ```bash HTTP GET /api/2/taxonomy/event-property/EVENT_PROPERTY_NAME HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded event_type=EVENT_NAME ``` {% /code-group %} {% accordion title="Example: Get a property from a specific event" %} This example gets the "Completed Task" property for the "Onboard Start" event. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/event-property?event_property=Completed Task' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'event_type=Onboard Start' ``` ```bash HTTP GET /api/2/taxonomy/event-property?event_property=Completed Task HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 26 event_type=Onboard%20Start ``` {% /code-group %} {% /accordion %} #### Path parameters | Name | Description | | ---------------- | ---------------------------------- | | `event_property` | Required. The event property name. | #### Body parameter | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event_type` | Optional. Name of the event type 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. ```json { "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, "is_hidden": false, "classifications": ["PII"] } } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Update event property Update an event property by sending a `PUT` request with the event property name as a path parameter. `PUT https://amplitude.com/api/2/taxonomy/event-property/:event-property` {% code-group %} ```bash cURL 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' \ ``` ```bash HTTP PUT /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 24 event_type=EVENT_NAME ``` {% /code-group %} {% accordion title="Example: Update an event property" %} This example updates the "Completed Task" property. The update changes the name to "Task Completed" and adds a description. {% code-group %} ```bash cURL curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'description=User completed an onboarding task' \ --data-urlencode 'new_event_property_value=Task Completed' \ ``` ```bash HTTP PUT /api/2/taxonomy/event-property/Completed Task HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 130 event_type=Onboard%20Start&description=User%20completed%20an%20onboarding%20task&new_event_property_value=Task%20Completed&type=any ``` {% /code-group %} {% /accordion %} #### Path parameters | Name | Description | | ---------------- | ------------------------------------- | | `event-property` | Required. Name of the event property. | #### Body parameters | Name | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_type` | Optional. Name of the event type 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 exists but not on this event type, Amplitude creates an override for the property. If the event property doesn't exist anywhere, Amplitude doesn't create an override. | | `overrideScope` | Optional. Determines how Amplitude acts on this event property. Only applicable when `event_type` is present. If `overrideScope` isn't present, Amplitude updates the property override on the event if one exists, or the shared property if no override exists. With `overrideScope: "override"`, Amplitude creates an override if none exists on the event, then updates that override, or updates the existing override if one already exists. With `overrideScope: "shared"`, Amplitude removes the property override on the event if one exists, then updates the shared property, or updates the shared property if no 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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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. Setting classifications on an overridden property returns an error. Setting `overrideScope: "override"` also returns an error for the same reason. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### 200 OK response A successful request returns a `200 OK` status and a JSON body. ```json { "success": true } ``` #### 409 conflict response Some failed requests return a `409 Conflict` and an error message with more details. ```json { "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 Delete an event property by sending a `DELETE` request with the event property as a path parameter. Optionally include the event type in the request body. `DELETE https://amplitude.com/api/2/taxonomy/event-property/:event-property` {% code-group %} ```bash cURL 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' ``` ```bash HTTP DELETE /api/2/taxonomy/event-property/EVENT_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded event_type=EVENT_NAME ``` {% /code-group %} {% accordion title="Example: Delete an event property" %} This example deletes the event property "Completed Task" from the "Onboarding Start" event. {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'event_type=Onboarding Start' ``` ```bash HTTP DELETE /api/2/taxonomy/event-property/Completed Task HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Type: application/x-www-form-urlencoded Content-Length: 29 event_type=Onboarding%20Start ``` {% /code-group %} {% /accordion %} #### Path parameters | Name | Description | | ---------------- | ---------------------------------- | | `event_property` | Required. The event property name. | #### Body parameter | Name | Description | | ------------ | ---------------------------------------------------------------- | | `event_type` | Optional. Name of the event type the event properties belong to. | #### 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. ```json { "success": true } ``` ### Restore an event property Restore an event property by sending a `POST` request with the event property as a path parameter. `POST https://amplitude.com/api/2/taxonomy/event-property/:event-property/restore` {% code-group %} ```bash cURL 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 ``` ```bash HTTP POST /api/2/taxonomy/event-property/EVENT_PROPERTY/restore HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded event_type=EVENT_TYPE ``` {% /code-group %} {% accordion title="Example: Restore an event property" %} This example restores the event property "Completed Task" for the "Onboard Start" event. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/event-property/Completed Task/restore' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'event_type=Onboard Start' ``` ```bash HTTP POST /api/2/taxonomy/event-property/Completed Task/restore HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= event_type=Onboard%20Start ``` {% /code-group %} {% /accordion %} #### Path parameters | Name | Description | | ---------------- | ---------------------------------- | | `event_property` | Required. The event property name. | #### Body parameters | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event_type` | Optional. String. The name of the event type. When included, restores the event property for the specified event type. When omitted, restores the shared event property. | #### Behavior | Event property | Behavior in Amplitude | | ---------------------------- | --------------------------- | | `deleted` | Restores the event property | | `not deleted` or `not found` | Returns an error | {% callout type="note" heading="Deleted properties and the GET endpoint" %} The [Get event properties](#get-event-properties) endpoint doesn't return deleted properties. If you try to create an event property that exists but is deleted, the [Create event property](#create-an-event-property) endpoint returns a `409 Conflict` error indicating the property already exists. To work with deleted properties: - Use the restore endpoint to restore a deleted property. - Check for `409 Conflict` errors when creating properties. The error may indicate the property exists but is deleted. {% /callout %} #### 201 OK response A successful request returns a `201 OK` status and a JSON body. ```json { "success": true } ``` ## User property User properties reflect traits about the individuals using your product. ### Create a user property Create a user property by sending a `POST` request with the user property name in the body. `POST https://amplitude.com/api/2/taxonomy/user-property/` {% code-group %} ```bash cURL 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' \ ``` ```bash HTTP POST /api/2/taxonomy/user-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} # credentials must be base64 encoded user_property=USER_PROPERTY ``` {% /code-group %} {% accordion title="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". {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'user_property=User Type' \ --data-urlencode 'description=Describes whether the user is a Free, Standard, or Premium user. ' \ --data-urlencode 'type=string' \ --data-urlencode 'enum_values=Free, Standard, Premium' ``` ```bash HTTP POST /api/2/taxonomy/user-property HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 185 user_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 ``` {% /code-group %} {% /accordion %} #### 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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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`. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### Response This request returns either a true or false response. ```json { "success": true } ``` ```json { "success": false } ``` ### Get all user properties Retrieves all user properties in your account. The request has no required parameters. `GET https://amplitude.com/api/2/taxonomy/user-property` {% callout type="note" heading="" %} Hidden user properties (those with a visibility other than "Visible") don't appear in the response. By default, this endpoint excludes deleted user properties. To include them, add the `showDeleted` query parameter: `GET https://amplitude.com/api/2/taxonomy/user-property?showDeleted=true` {% /callout %} {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property' \ -u '{api_key}:{secret_key}'' ``` ```bash HTTP GET /api/2/taxonomy/user-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} #### Response A successful request returns a `200 OK` response and a JSON body with user property details. ```json { "success": true, "data": [ { "user_property": "device_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": ["PII"], "deleted": false }, { "user_property": "event_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "amplitude_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "location_lat", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "location_lng", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "server_upload_time", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "session_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false }, { "user_property": "user_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": [], "deleted": false } ] } ``` ### Get a user property Retrieves a single user property by name. `GET https://amplitude.com/api/2/taxonomy/user-property/:user_property` {% callout type="note" heading="" %} By default, this endpoint excludes deleted user properties. To include them, add the `showDeleted` query parameter: `GET https://amplitude.com/api/2/taxonomy/user-property/:user_property?showDeleted=true` {% /callout %} {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Get a user property" %} This example gets the `device_id` user property. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/user-property/device_id' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/2/taxonomy/user-property/device_id HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} ##### 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. ```json { "success": true, "data": { "user_property": "device_id", "description": null, "type": null, "enum_values": null, "regex": null, "is_array_type": false, "is_hidden": false, "classifications": ["PII"], "deleted": false } } ``` #### 404 Bad Request response A failed request returns a `404 Bad Request` status and an error message. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Update a user property Update a user property by sending a `PUT` request with the user property name as a path parameter. `PUT https://amplitude.com/api/2/taxonomy/user-property/:user_property` {% code-group %} ```bash cURL 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' ``` ```bash HTTP PUT /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 37 new_user_property_value=VALUE&description=DESCRIPTION ``` {% /code-group %} {% accordion title="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. {% code-group %} ```bash cURL curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/user-property/gp:user_type' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'new_user_property_value=subscription_type' \ --data-urlencode 'description=The user'\''s subscription type' \ --data-urlencode 'type=string' ``` ```bash HTTP PUT /api/2/taxonomy/user-property/gp:user_type HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 100 new_user_property_value=subscription_type&description=The%20user's%20subscription%20type&type=string ``` {% /code-group %} {% /accordion %} #### 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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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`. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### Response This request returns either a true or false response. ```json { "success": true } ``` ```json { "success": false } ``` ### Delete a user property Deletes a single user property by name. `DELETE https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY` {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP DELETE /api/2/taxonomy/user-property/USER_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Delete a user property" %} This example deletes a custom user property "interests". Notice that the user property is prefixed with `gp:`. {% code-group %} ```bash cURL curl --location --request DELETE 'https://amplitude.com/api/2/taxonomy/user-property/gp:interests' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP DELETE /api/2/taxonomy/user-property/gp:interests HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` ### Restore a user property Restore a single user property by name. `POST https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore` {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property/USER_PROPERTY/restore' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP POST /api/2/taxonomy/user-property/USER_PROPERTY/restore HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Restore a user property" %} This example restores a custom user property `interests`. Notice that the user property is prefixed with `gp:`. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/user-property/gp:interests/restore' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP POST /api/2/taxonomy/user-property/gp:interests/restore HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} #### 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. ```json { "success": true } ``` ## Group property Group properties are properties at the account level. Group properties apply to all users who belong to that account. ### Create a group property Create a group property by sending a `POST` request with the required information in the body. `POST https://amplitude.com/api/2/taxonomy/group-property` {% code-group %} ```bash cURL 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' \ ``` ```bash HTTP POST /api/2/taxonomy/group-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 94 group_type=GROUP_TYPE&group_property=GROUP_PROPERTY ``` {% /code-group %} {% accordion title="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. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/2/taxonomy/group-property' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-urlencode 'group_type=Group 1' \ --data-urlencode 'group_property=Group Property 1' \ --data-urlencode 'description=First Group Property' \ --data-urlencode 'type=boolean' ``` ```bash HTTP POST /api/2/taxonomy/group-property HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 144 group_type=Group%201&group_property=Group%20Property%201&type=boolean&description=First%20Group%20Property ``` {% /code-group %} {% /accordion %} #### 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 exists but not on this group type, Amplitude creates an override for the property. If the group property doesn't exist anywhere, Amplitude doesn't create an override. If the group property exists and is Amplitude-sourced, providing any extra arguments other than `group_property` and `group_type` returns an error because Amplitude-sourced group properties aren't editable. | | `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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### 200 OK response A successful request returns a `200 OK` status and a JSON body. ```json { "success": true } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Attempted to add a group property, \"Group Property 1\", that already exists." } ] } ``` ### Get group properties Get shared or group-specific group properties. `GET https://amplitude.com/api/2/taxonomy/group-property` {% code-group %} ```bash cURL 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' ``` ```bash HTTP GET /api/2/taxonomy/group-property HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded group_type=GROUP_TYPE ``` {% /code-group %} {% accordion title="Example: get all of a group's properties" %} This example gets all group properties for the "Group 1" group type. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'group_type=Group 1' ``` ```bash HTTP GET /api/2/taxonomy/group-property HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 26 group_type=Group%201 ``` {% /code-group %} {% /accordion %} #### 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. ```json { "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, "is_hidden": 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, "is_hidden": false, "classifications": [] } ] } ``` ### Get a single group property Get a single group property by sending a `GET` request with the group property name as a path parameter. Optionally include the group type in the body. `GET https://amplitude.com/api/2/taxonomy/group-property/:group_property` {% code-group %} ```bash cURL 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' ``` ```bash HTTP GET /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded group_type=GROUP_TYPE ``` {% /code-group %} {% accordion title="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. {% code-group %} ```bash cURL curl --location --request GET 'https://amplitude.com/api/2/taxonomy/group-property/grp%3AGroup%20Property%201 \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'group_type=Group 1' ``` ```bash HTTP GET /api/2/taxonomy/group-property/grp%3AGroup%20Property%201 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 26 group_type=Group%201 ``` {% /code-group %} {% /accordion %} #### 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, Amplitude returns all group properties associated with this group type. If `group_type` isn't provided, 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 containing information about the group property. ```json { "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, "is_hidden": false, "classifications": ["PII"] } } ``` #### 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. ```json { "success": false, "errors": [ { "message": "Not found" } ] } ``` ### Update group property Update a group property by sending a `PUT` request with the group property name as a path parameter. `PUT https://amplitude.com/api/2/taxonomy/group-property/:group_property` {% code-group %} ```bash cURL 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' \ ``` ```bash HTTP PUT /api/2/taxonomy/group-property/GROUP_PROPERTY HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/x-www-form-urlencoded Content-Length: 24 group_type=GROUP_NAME ``` {% /code-group %} {% accordion title="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. {% code-group %} ```bash cURL curl --location --request PUT 'https://amplitude.com/api/2/taxonomy/group-property/grp:Group Property 1' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'description=First Group Property Updated' \ --data-urlencode 'new_group_property_value=grp:Group Property - Renamed' \ ``` ```bash HTTP PUT /api/2/taxonomy/group-property/grp:Group Property 1 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA== Content-Type: application/x-www-form-urlencoded Content-Length: 130 group_type=Group%201&description=First%20Group%20Property%20Updated&new_group_property_value=grp%3AGroup%20Property%201%20Renamed ``` {% /code-group %} {% /accordion %} #### 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 Amplitude acts on this group property. Only applicable when `group_type` is present. If `overrideScope` isn't present, Amplitude updates the property override on the group type if one exists, or the shared property if no override exists. With `overrideScope: "override"`, Amplitude creates an override if none exists on the group type, then updates that override, or updates the existing override if one already exists. With `overrideScope: "shared"`, Amplitude removes the property override on the group type if one exists, then updates the shared property, or updates the shared property if no 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. | | `is_hidden` | Optional. Boolean. Hide the property from chart dropdowns. | | `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. | {% callout type="note" heading="" %} `is_hidden` property can only be set on ingested properties. {% /callout %} #### 200 OK response A successful request returns a `200 OK` status and a JSON body. ```json { "success": true } ``` #### 409 conflict response Some failed requests return a `409 Conflict` and an error message with more details. ```json { "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." } ] } ```