Amplitude

## Required Event Argument Keys

You must include the following keys within the event argument:

| Required Key | Description | Example |
| --- | --- | --- |
| `event_type` | String. Prefix with brackets "\[YOUR COMPANY\]". | "\[YOUR COMPANY\] Install" |
| `platform` | String. Either "ios" or "android". | "ios" |
| `idfa` or `idfv` | *Required for iOS. String.* The Identifier for Advertiser or the Identifier for Vendor. | AEBE52E7-03EE-455A-B3C4-E57283966239 |
| `adid` | *Required for Android. String.* The Google AdID, or Amazon Advertising ID for Amazon devices. | AEBE52E7-03EE-455A-B3C4-E57283966239 |

*Note: For iOS devices, you can send either the IDFA or the IDFV but you must send at least one.*

## Optional Event Argument Keys

These optional keys are available.

| Additional Key | Type | Description | Example |
| --- | --- | --- | --- |
| `android_id` | string | (Android) The Android ID | AEBE52E7-03EE-455A-B3C4-E57283966239 |
| `user_properties` | dictionary | A dictionary of attribution properties prefixed with brackets "\[YOUR COMPANY\]". | {"\[YOUR COMPANY\] media source": "Facebook"} |
| `time` | long | Timestamp of the event in milliseconds since epoch. | 1396381378123, will be set to the upload time by default |

iOS Attribution

# Batch Event Upload

Use this request to bulk upload events to Amplitude.

If you have used our HTTP API before, note that there are two minor but important differences in your POST request to `/batch`.

*   Content-type must be `application/json`.
*   The key for the `events` payload is `events` plural, not `event` singular.
    

## Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| `api_key` | string | true | none | Amplitude project API key |
| `events` | \[[Event](https://developers.amplitude.com/docs/batch-event-upload-api#schemaevent)\] | true | none | Array of [Events](https://developers.amplitude.com/docs/batch-event-upload-api#definition-Event) to upload |
| `options` | \[[options](https://developers.amplitude.com/docs/batch-event-upload-api#schemaRequestOptions)\] | false | none | Object |

## Responses

| Status | Meaning | Description |
| --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful batch upload. |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid upload request. Read the error message to fix the request. |
| 413 | [Payload Too Large](https://tools.ietf.org/html/rfc7231#section-6.5.11) | Payload size is too big (request size exceeds 20MB). Split your events array payload in half and try again. |
| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too many requests for a user or device. Amplitude throttles requests for users and devices that exceed 1000 events per second. |

### Code 429 Explained

When a request is rejected with a 429 status, it means that a device or user in that request was throttled. Details about which can be found in the error response data. Logging the response lets you investigate which users or devices were the cause of throttling.

Because device_id and user_id are the attributes that determine throttling, partitioning work on one of these attributes will help isolate throttling to a specific partition of work. This way partitions which are not being throttled can still make progress while the throttled partitions are blocked by throttling.

#### EPDS and EPUS

Amplitude measures the rate of events for each deviceid and each userid for a project, and refer to those rates as *events per device second* (**EPDS**) and *events per user second* (**EPUS**) respectively. These values are both averaged over a period of 30 seconds.

For example, to reach an EPDS limit of 1000 requires that a device sends 30,000 events in a 30-second period for the device to be throttled and receive HTTP status 429.

In general, your app shouldn't measure EPDS or EPUS itself. Send requests to Amplitude as fast as possible. When you receive a 429, wait for a short period (for example, 15 seconds) before trying to send that request again.

#### Daily Limit

In addition to the per-second limit, there is daily limit to prevent against spam and abuse. This limit is rarely exceeded. Events starts counting toward the daily limit after Amplitude determines that a user/device is spamming the system. After the threshold is reached, a daily limit of 500,000 events uploaded per rolling 24 hours is enforced. The 24 hour rolling period applies in one-hour intervals. The daily limit applies for each deviceid and each user_id for a project.

The daily limit is independent of the EPDS/EPUS. Once a user or device has hit the 500,000 event daily limit for a particular project, any batches uploaded containing the user or device is rejected. In those cases, the request returns a 429 response with a body indicating “exceeded_daily_quota_users” or “exceeded_daily_quota_devices” with list of deviceIds and userIds. Retry the batch when there are less than 500,000 events uploaded for a user or device in the previous 24 hour period.

Batch Event Upload

Get all discoverable cohorts for an app. The `id` returned for each cohort is used to get a single cohort.

Each COHORT_OBJECT has this schema:

``` json
{
    "lastComputed": timestamp,
    "owners": string[],
    "description": string,
    "definition": { COHORT_DEFINITION },
    "published": boolean,
    "archived": boolean,
    "name": string,
    "appId": string,
    "lastMod": timestamp,
    "type": string,
    "id": string,
    "size": integer
}

```

Get all Cohorts

Get a discoverable cohort using its `cohort_id`.

This is phase one in the download a cohort operation. The `request_id` returned in the response is used to poll export status.

Get a single Cohort

Poll the request status. This is the second phase in a cohort download operation.

Get Cohort Status

For small cohorts, the response body contains cohort data.

For large cohorts, the data must be downloaded. If the cohort is large, the response redirects with a 302 response code to a pre-signed Amazon S3 download URL. The download URL is valid for one minute, and should be accessed immediately.

The API request link ([https://amplitude.com/api/5/cohorts/request/:requestId/file](https://amplitude.com/api/5/cohorts/request/:requestId/file)) is valid for seven days. During the seven days, you can make the same request repeatedly to get a new S3 download link. Each S3 link is valid only for one minute.

Most clients used to send API requests automatically download the data from the S3 link. If your API client doesn't automatically download the cohort from the S3 link, you have one minute access it manually.

Cohort Download

Generate a new cohort or update an existing cohort by uploading a set of User IDs or Amplitude IDs.

## Body Parameters

| Parameter | Description |
| --- | --- |
| `name` | Required. String. A name for the cohort. |
| `app_id` | Required. Integer. An identifier for the Amplitude project containing the cohort. |
| `id_type` | Required. String. The type of ID being sent in the ids field. Valid options are `BY_AMP_ID` or `BY_USER_ID`. |
| `ids` | Required. String\[\]. One or more user or Amplitude IDs to include in the cohort. The type of the IDs should be specified in the id_type field. |
| `owner` | Required. String. The login email of the cohort's owner in Amplitude. |
| `published` | Required. Boolean. Whether the cohort is discoverable or hidden. |
| `existing_cohort_id` | Optional. String. The id of an existing cohort. This will replace the contents for the specified cohort with the ids being uploaded by this request. e.g. '1a2bc3d' is your cohort's id, and it can be found in your cohort's URL. https//analytics.amplitude.com/demo/cohort/1a2bc3d |

Upload IDs

Perform incremental update (add / remove) to existing cohort membership.

# Request Body

| Parameter | Description |
| --- | --- |
| `cohort_id` | Required. String. The ID of an existing cohort. This will update the membership for the specified cohort with the IDs being uploaded in this request. |
| `count_group` | Optional. String. The count group of the given IDs. This must be the same as the cohort’s existing count group. `Count_group` defaults to User. |
| `memberships` | Required. List of [membership json](https://developers.amplitude.com/docs/behavioral-cohorts-api#membershipjson) An array of JSON objects identifying IDs to add or remove. |
| `skip_invalid_ids` | Optional. Boolean. Setting this parameter to `false` ends the request without updating cohort membership if the request contains invalid IDs. Setting `skip_invalid_ids` to `true` skips invalid IDs while applying the remaining valid ids. Default is `true`. |

# Request Membership JSON

| Parameter | Description |
| --- | --- |
| `ids` | Required. String\[\]. List of IDs to add or remove. |
| `id_type` | Required. String. The type of ID being sent in the `ids` field. Valid options are: *\- BY_ID* *\- BY_NAME* For User count_group, BY_ID is amplitude ID and BY_NAME is user ID. For any other count_group, BY_ID is group ID and BY_NAME is group name. |
| `operation` | Required. String. The operation to apply on `ids` field. Valid options are: `ADD` and `REMOVE` |

## Success Response Fields

| Parameter | Description |
| --- | --- |
| `cohort_id` | String. The ID of an existing cohort that the membership information was updated for. |
| `memberships_result` | List of [memberships_result json](https://developers.amplitude.com/docs/behavioral-cohorts-api#membershipresultjson). An array of JSON objects identifying result of membership update (add or remove) operation. |

### Response `memberships_result` JSON

| Parameter | Description |
| --- | --- |
| `skipped_ids` | List of strings. List of IDs that were skipped (fail, invalid, etc.) in this membership operation entry. |
| `id_type` | String. The type of ID that was sent for the `ids` field in this membership operation entry. |
| `operation` | String. The operation that was applied on `ids` field in this membership operation entry |

## Error Response Body

### Response body (for non 200 response):

| Parameter | Type | Description |
| --- | --- | --- |
| `error` | [error json](https://developers.amplitude.com/docs/behavioral-cohorts-api#errorjson) | The detail information of the error |

### Response error json:

| Parameter | Description |
| --- | --- |
| `message` | String. Describes the error. |
| `code` | Integer. Internal error code. |
| `metadata` | JSON object. For bad request error (400) with invalid id while `skip_invalid_ids=false`, this field contains the `cohort_id` and `memberships_result` (list of membership JSON). The `memberships_result’`s `skipped_ids` can help identify which IDs were invalid in which operation. For other errors, this field is not present. |

Update Membership

Create a request for user data.

## Body Parameters

| **Name** | **Description** |
| --- | --- |
| `userId` | Required if `amplitudeID` is not set. The User Id of the user to request data for. |
| `amplitudeId` | Required if `userID` is not set. Integer. The Amplitude ID of the user to request data for. |
| `startDate` | Required. Date. The start date for the data request. |
| `endDate` | Required. Date. The end date for the data request. |

## Response

When successful, the call returns a `requestID`, which is used to poll the job status.

Create Data Request

Retrieves a request's status.

## Response Body

| Name | Description |
| --- | --- |
| `requestId` | Integer. The ID of the request. |
| `userId` | String. The User Id of the user to request data for. |
| `amplitudeId` | Integer. The Amplitude ID of the user to request data for. |
| `startDate` | Date. The start date for the data request. |
| `endDate` | The end date for the data request. |
| `status` | **staging**: not started **submitted**: in progress **done**: job completed successfully and urls populated **failed**: job failed, may need to retry |
| `failReason` | String. If the job failed, contains Information about the failure. |
| `urls` | Array of strings. A list of dowload URLs for the data. |
| `expires` | Data. The date that the output download links expire. |

Get Request Status

Download a returned output file.

The download link is valid for two days. Most clients used to send API requests automatically download the data from the S3 link. If your API client doesn't automatically download the file from the link, access it manually using your org API key as the username and your org secret key as the password.

Get Output File

# Get Annotation

Gets the annotation specified by ID.

Get Chart Annotation

# Create Annotation

Creates an annotation with the specified parameters.

Create Chart Annotation

This is the basic request format for the Funnel Analysis API, including all available parameters.

Funnel Analysis

This is the basic request format with all parameters.

Retention analysis

This is the basic GET request format and all parameters.

User activity

User composition

Get users

Get the number of sessions for each pre-defined length ("bucket") period during a specified date range.

## timeHistogramConfigBin Format

`timeHistogramConfigBinTimeUnit` is any of `['hours', 'minutes', 'seconds']`.

In order to take advantage of custom binning, `timeHistogramConfigBinMin`, `timeHistogramConfigBinMax`, and `timeHistogramConfigBinTimeUnit` must be specified. When `timeHistogramConfigBinSize` is not specified, Amplitude will try to determine the optimum bin sizing. For example, if we have `timeHistogramConfigBinMin=0`, `timeHistogramConfigBinMax=10`, and `timeHistogramConfigBinTimeUnit=minutes`, there is no guarantee regarding the final amount of bins or bin bounds. If `timeHistogramConfigBinSize=1` is specified, 10 bins would be guaranteed, with each bin size equaling a minute.

When combined `timeHistogramConfigBin` parameters are invalid/missing, Amplitude will default to use default bins that are chosen because they approximate certain behaviors such as bounce rate. These bins are (in milliseconds): `[0, 3000), [3000, 10,000), [10,000, 30,000), [30,000, 60,000), [60,000, 180,000), [180,000, 600,000), [600,000, 1,800,000), [1,800,000, 3,600,000), [3,600,000, 86,400,000)`.

Session lengths are bounded at a maximum of 1 day (86,400,000 ms).

### Returns

| Attribute | Description |
| --- | --- |
| series | An array with one element which is itself an array that contains the counts (number of sessions) for each of the buckets. |
| xValues | An array of the (string) session length intervals (buckets) of the format `[bucketStartInSeconds]s-[bucketEndInSeconds]s`. |

Session length distribution

Get the average number of sessions per user on each day in the specified date range.  

## Returns

| Attribute | Description |
| --- | --- |
| series | An array with one element which is itself an array that contains the (float) average number of sessions per user for each day. |
| seriesMeta | An array of labels with one for each segment. |
| segmentIndex | This represents the index of the segment, referring to its position in the right module of the chart control panel |
| xValues | An array of (string) dates formatted like "YYYY-MM-DD" with one for each in the specified date range |

Average sessions per user

Get the average session length (in seconds) for each day in the specified date range.


## Returns

| Attribute | Description |
| --- | --- |
| series | An array with one element which is itself an array that contains the average session length for each day. |
| seriesMeta | An array of labels with one for each segment. |
| segmentIndex | This represents the index of the segment, referring to its position in the right module of the chart control panel. |
| xValues | An array of (string) dates formatted like "YYYY-MM-DD" with one for each in the specified date range. |

Average session length

Search for a user with a specified Amplitude ID, Device ID, User ID, or User ID prefix. Exceeding the request limits results in 429 errors.

Get user

This is the basic request format for the Event Segmentation API, including all available parameters.

Event Segmentation Chart

Get the list of events with the current week's totals, uniques, and % DAU.

Get events list

Get JSON results from any existing (saved) chart via chart ID.

Get Results from existing chart

Get active user numbers with minute granularity for the last two days.

Real-time Active Users

Revenue LTV

The `sync_ID` is in the URL of the streaming settings page. For example: \`https://analytics.amplitude.com/amplitude/connections/project/PROJECT_ID/setup-integration/event_streaming/DESTINATION_TYPE/**SYNC_ID**/settings\`

The `sync_ID` in the URL is base64-encoded. For example, `MzAwMDE2MjU=`. When submitting a request, you need the decoded value, for example `30001625`.

You can decode in the web console with this command `atob('MzAwMDE2MjU=')`

Basic Call

## Considerations

*   The specified date range is the time of when the event data was uploaded to Amplitude servers (see server_upload_time). The Export API returns events timestamped in UTC. Data is available to export at a minimum within 2 hours of when our servers received it. For example, data sent between 8-9PM begins loading at 9PM and is available via the Export API at 11PM. Note that there is no delay in platform reporting. The delay is only for data you wish to export.
*   Export API is not supported for a cross-project view because the view doesn’t own any data. To export all the data in the view, you would need to call the Export API on the underlying projects that actually ingested the data.
*   Size limit is 4GB. If the size exceeds 4GB, you will receive a 400 response. In this case, we recommend that you chose a smaller time range to export the data.  
    In case that an hour's worth of data exceeds 4GB, we recommend that the customers use the S3 export solution.
*   To export a whole day, Use T00 to T23. The maximum time range you can query at once is 365 days.
    

## Response

The response is a zipped archive of JSON files, with potentially multiple files per hour. Note that events prior to 2014-11-12 will be grouped by day instead of by the hour. If you request data for a time range during which no data has been collected for the project, then you will receive a 404 response from our server.

### Response Schema

``` json
{
 "server_received_time": UTC ISO-8601 formatted timestamp,
 "app": int,
 "device_carrier": string,
 "$schema":int,
 "city": string,
 "user_id": string,
 "uuid": UUID,
 "event_time": UTC ISO-8601 formatted timestamp,
 "platform": string,
 "os_version": string,
 "amplitude_id": long,
 "processed_time": UTC ISO-8601 formatted timestamp, 
 "user_creation_time": UTC ISO-8601 formatted timestamp,
 "version_name": string,
 "ip_address": string,
 "paying": boolean,
 "dma": string,
 "group_properties": dict,
 "user_properties": dict,
 "client_upload_time": UTC ISO-8601 formatted timestamp,
 "$insert_id": string,
 "event_type": string,
 "library":string,
 "amplitude_attribution_ids": string,
 "device_type": string,
 "device_manufacturer": string,
 "start_version": string,
 "location_lng": float,
 "server_upload_time": UTC ISO-8601 formatted timestamp,
 "event_id": int,
 "location_lat": float,
 "os_name": string,
 "amplitude_event_type": string,
 "device_brand": string,
 "groups": dict,
 "event_properties": dict,
 "data": dict,
 "device_id": string,
 "language": string,
 "device_model": string,
 "country": string,
 "region": string,
 "is_attribution_event": bool,
 "adid": string,
 "session_id": long,
 "device_family": string,
 "sample_rate": null,
 "idfa": string,
 "client_event_time": UTC ISO-8601 formatted timestamp,
}

```

Get Export

## Keys for the Identification Argument

| Key | Type | Description | Example |
| --- | --- | --- | --- |
| `group_type` | string | One type of group (e.g. account or company). | "org name", "org id" |
| `group_value` | string | One specific value of the `group_type`. | "group_type":"org id","group_value":"12345678" or "group_type":"account name","group_value":"Acme Corp" |
| `group_properties` |string| A dictionary of key-value pairs that represent additional data tied to the group. Each distinct value will show up as a group segment on the Amplitude dashboard. Note: You can store property values in an array, and date values are transformed into string values. In addition, group property operations ($set, $setOnce, $add, $append, $unset) are supported in this Group Identify API. | {"arr": "10000", "cs": \["Justin", "Ben"\], "renewal_date": “01/01/2018" } |

`group_properties` supports these operations:

| Operation | Description |
| --- | --- |
| `$set` | set the value of a property |
| `$setOnce` | set the value of a property, prevent overriding the property value |
| `$add` | add a numeric value to a numeric property |
| `$append and $prepend` | append and prepend the value to a group property array |
| `$unset` | remove a property |

Create Group

## Upload Request Body

| Name | Description |
| --- | --- |
| `api_key` | Required. String. Amplitude project API key. If you're using Postman, set this variable in the Amplitude API Environment. |
| `events` | Required. \[\]. Array of [Events](https://developers.amplitude.com/docs/http-api-v2#definition-Event) to upload. |
| `options` | Optional. \[\].Object |

## Keys for the Event Argument

The following keys can be sent within the JSON event object. Note that one of `user_id` or `device_id` is required, as well as the `event_type`.

*Note: '\[Amplitude\] Country', '\[Amplitude\] City', '\[Amplitude\] Region', and '\[Amplitude\] DMA' are user properties pulled using GeoIP. We use MaxMind's database, which is widely accepted as the most reliable digital mapping source, to lookup location information from the user's IP address. For any HTTP API events, if GeoIP information is unavailable, then we pull the information from the 'location_lat' and 'location_lng' keys if those keys are populated. If these location properties are manually set, then Amplitude will not modify that property.*

| Name | Description |
| --- | --- |
| `user_id` | Required if device_id isn't used. String. ID for the user. Must have a minimum length of 5 characters unless overridden with the `min_user_length` option. |
| `device_id` | Required if user_id isn't used. String. A device-specific identifier, such as the Identifier for Vendor on iOS. If a device_id is not sent with the event, it will be set to a hashed version of the user_id. |
| `event_type` | Required. String. A unique identifier for your event. The following event names are reserved for Amplitude use: "\[Amplitude\] Start Session", "\[Amplitude\] End Session", "\[Amplitude\] Revenue", "\[Amplitude\] Revenue (Verified)", "\[Amplitude\] Revenue (Unverified)", and "\[Amplitude\] Merged User". |
| `time` | Optional. The timestamp of the event in milliseconds since epoch. If time is not sent with the event, it will be set to the request upload time. |
| `event_properties` | Optional. Object. A dictionary of key-value pairs that represent additional data to be sent along with the event. You can store property values in an array. Date values are transformed into string values. Object depth may not exceed 40 layers. |
| `user_properties` | Optional. Object. A dictionary of key-value pairs that represent additional data tied to the user. You can store property values in an array. Date values are transformed into string values. Object depth may not exceed 40 layers. |
| `groups` | Optional. Object. This feature is only available to Enterprise customers who have purchased the [Accounts add-on](https://amplitude.zendesk.com/hc/en-us/articles/115001765532). This field adds a dictionary of key-value pairs that represent groups of users to the event as an event-level group. *Note: You can only track up to 5 unique group types and 10 total group values. Any groups past that threshold will* ***not*** *be tracked.* |
| `app_version` | Optional. String. The current version of your application. |
| `platform` | Optional. String. Platform of the device. |
| `os_name` | Optional. String. The name of the mobile operating system or browser that the user is using. |
| `os_version` | Optional. String. The version of the mobile operating system or browser the user is using. |
| `device_brand` | Optional. String. The device brand that the user is using. |
| `device_manufacturer` | Optional. String. The device manufacturer that the user is using. |
| `device_model` | Optional. String. The device model that the user is using. |
| `carrier` | Optional. String. The carrier that the user is using. |
| `country` | Optional. String. The current country of the user. |
| `region` | Optional. String. The current region of the user. |
| `city` | Optional. String. The current city of the user. |
| `dma` | Optional. String. The current Designated Market Area of the user. |
| `language` | Optional. String. The language set by the user. |
| `price` | Optional. Float. The price of the item purchased. Required for revenue data if the revenue field is not sent. You can use negative values to indicate refunds. |
| `quantity` | Optional. Integer. The quantity of the item purchased. Defaults to 1 if not specified. |
| `revenue` | Optional. Float. revenue = price * quantity. If you send all 3 fields of price, quantity, and revenue, then (price * quantity) will be used as the revenue value. You can use negative values to indicate refunds. |
| `productId` | Optional. String. An identifier for the item purchased. You must send a price and quantity or revenue with this field. |
| `revenueType` | Optional. String. The type of revenue for the item purchased. You must send a price and quantity or revenue with this field. |
| `location_lat` | Optional. Float. The current Latitude of the user. |
| `location_lng` | Optional. Float. The current Longitude of the user. |
| `ip` | Optional. String. The IP address of the user. Use "$remote" to use the IP address on the upload request. We will use the IP address to reverse lookup a user's location (city, country, region, and DMA). Amplitude has the ability to drop the location and IP address from events once it reaches our servers. You can submit a request to our platform specialist team [here](https://amplitude.zendesk.com/hc/en-us/requests/new) to configure this for you. |
| `idfa` | Optional. String. (iOS) Identifier for Advertiser. |
| `idfv` | Optional. String. (iOS) Identifier for Vendor. |
| `adid` | Optional. String. (Android) Google Play Services advertising ID |
| `android_id` | Optional. String. (Android) Android ID (not the advertising ID) |
| `event_id` | Optional. Integer. (Optional) An incrementing counter to distinguish events with the same user_id and timestamp from each other. We recommend you send an event_id, increasing over time, especially if you expect events to occur simultanenously. |
| `session_id` | Optional. LONG. The start time of the session in milliseconds since epoch (Unix Timestamp), necessary if you want to associate events with a particular system. A session_id of -1 is the same as no session_id specified. |
| `insert_id` | Optional. String. A unique identifier for the event. We will deduplicate subsequent events sent with an insert_id we have already seen before within the past 7 days. We recommend generation a UUID or using some combination of device_id, user_id, event_type, event_id, and time. |
| `plan` | Optional. Object. Tracking plan properties. Only branch, source, version properties are accepted. |
| `plan.branch` | Optional. String. The tracking plan branch name e.g. "main" |
| `plan.source` | Optional. String. The tracking plan source e.g. "web" |
| `plan.version` | Optional. String. The tracking plan version e.g. "1", "15" |

## Options


| Name | Description |
| --- | --- |
| `min_id_length` | Optional. Integer. Overrides the default minimum length of 5 for user_id & device_id fields. |

```


```

Upload Request

GET that shows limits of GET param length

# Keys for the Identification Argument

| Key | Type | Description |
| --- | --- | --- |
| user_id | string | (required unless device_id is present) A UUID (unique user ID) specified by you. *Note: If you send a request with a user_id that is not in the Amplitude system yet, then the user tied to the user_id will not be marked new until their first event.* |
| device_id | string | (required unless user_id is present) A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS. |
| user_properties | dictionary | A dictionary of key-value pairs that represent additional data tied to the user. Each distinct value will show up as a user segment on the Amplitude dashboard. Object depth may not exceed 40 layers. *Note: You can store property values in an array and date values are transformed into string values.*0 |
| groups | string | *(Enterprise only)* This feature is only available to Enterprise customers who have purchased the [Accounts add-on](https://amplitude.zendesk.com/hc/en-us/articles/115001765532). A dictionary of key-value pairs that represent groups of users. See this [excerpt](https://amplitude.zendesk.com/hc/en-us/articles/115001361248#setting-user-groups) in our Javascript SDK for more information on groups. Setting groups will allow you to use our [account-level reporting](https://amplitude.zendesk.com/hc/en-us/articles/115001765532) feature. *Note: You can only track up to 5 unique group types and 10 total groups. Any groups past that threshold will* ***not*** *be tracked.* |
| app_version | string | What version of the app the user is on. |
| platform1 | string | What platform is sending the data. |
| os_name1 | string | What mobile operating system or browser the user is on. |
| os_version1 | string | What version of the mobile operating system or browser the user is on. |
| device_brand1 | string | What device brand the user is on. |
| device_manufacturer1 | string | What device manufacturer the user is on. |
| device_model1 | string | What device model the user is on. |
| carrier1 | string | What carrier the user has. |
| country2 | string | What country the user is in. |
| region2 | string | What geographical region the user is in. |
| city2 | string | What city the user is in. |
| dma2 | string | The Designated Market Area of the user. |
| language | string | What language the user has set. |
| paying | string | Whether the user is paying or not. |
| start_version | string | What version of the app the user was first on. |

Identify API call Example

Retrieves a list of lookup tables in the project.

Get all lookup tables

Get a single lookup table

Create a new lookup table by uploading a CSV file.

Create lookup table

Delete a table

Update lookup table

Create Release: Query Parameters

Gets a list of users within Amplitude for that organization. This includes both pending and joined users, and supports pagination and filtering.

See [SCIM filter syntax](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2) for help with the filter parameter.

Get Users

Get User by ID

Updates the Amplitude user with the given ID. `id` must be a valid email address, and the user must have been previously invited to Amplitude.

If the `active` schema field is set to `false` on the request body, the user is removed from the organization and all access is lost. If this action is taken on a pending user (an invited user that hasn't accepted the invitation), the invitation is revoked.

User Update

Deletes the Amplitude user with the given ID. The ID must be a valid email, and the user must have been previously invited to Amplitude.  
If this action is taken on a pending user (an invited user that hasn't accepted the invitation), the invitation is revoked.

Delete User

`PUT`Updates an existing user with the given ID within Amplitude. The ID **must** be a valid email, and the user must have been previously invited to Amplitude.

If the `active` schema field is set to `false` on the request body, the user will be removed from the organization and all access is lost. If this action is taken on a Pending User (i.e. invite has been sent but has not yet accepted the invite), the invitation is revoked.

Creates a new user within Amplitude, sends an invitation link to the email requested, and returns a `201` Resource Created response if successful. The ID and Username **must** be valid emails, and the user must not have been previously invited/provisioned to your Amplitude organization to succeed.

The request body for the `POST` route should be a valid SCIM User Resource. **Note** the Groups field on the user will be ignored. If a user should be added to a group, please call the API routes pertaining to the **group** and not the user.

Create User

Get all groups in an Amplitude organization.

Get Groups

Create Groups

Get Group by ID

Delete Group

Update Group

Get all event categories in your project.

Get all Event Categories

Create an event category in your project.

Create an Event Category

Get the ID of an event category in your project.

Get an Event Category

Update an Event Category

Delete an Event Category

Retrieves all event types in a project. There are no required parameters for this request.

Get all Event Types

Creates an event type.

Note: You must [initialize the schema](https://help.amplitude.com/hc/en-us/articles/360047579451) before you can add event types via the API.

Create Event Type

Get an Event Type

Update an Event Type

Delete Event Type

Get Event Properties

Create Event Property

Update Event Property

Delete Event Property

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

Get All User Properties

Create User Property

Retrieves a single user property, by name.

Get User Property

Update User Property

Delete User Property

Maps a user ID to a global user ID. You can map a single user ID per JSON mapping object.

Mapping Request

Retrieves a list list deletion jobs scheduled in a time range; this time range should include the date you made the request on plus 30 days. For example, you made a deletion request on August 1st, 2018. Your deletion request should have `start_day = 2018-08-01` and `end_day = 2018-08-31`.

If the request returns no values, then no jobs are scheduled for that time range. Note: The largest permitted time range is six months.

## Response Object

The response for a GET request contains the following fields:

| key | description |
| --- | --- |
| `day` | The day the deletion job is scheduled to begin |
| `status` | The deletion job's status. **Staging**: The job hasn't started, and can be modified. More deletion requests may get scheduled into this job and you can remove requests from this job. **Submitted**: The job is submitted to run. It can't be modified. **Done**: The job has finished running. It can't be modified. |
| `amplitude_ids` | List of the Amplitude Ids of users to delete. |
| `app` | Project/app id. Appears if the deletion is applies to multiple projects. |

The `amplitude_ids` key contains these fields:

| key | description |
| --- | --- |
| `amplitude_id` | The Amplitude ID of the user to be deleted. |
| `requester` | The person who requested the Amplitude ID to be deleted |
| `requested_on_day` | The day this deletion was requested |

GET Deletion Requests

Request a user be scheduled for deletion using a JSON body. Specify up to 100 users at a time. A mix of Amplitude IDs and User IDs is permitted.

When a request is made, we confirm the validity of the requestor via the secret key and the end-user via the Amplitude ID. To reduce resource impact and ensure high availability, Amplitude batches requests for deletions. Batch jobs are scheduled for 10-13 days after the first request in a batch is made.

Requests in the batch can be revoked until three (3) days before the day the job is scheduled to run. During the three (3) day period, you can't edit batch. All deletion requests made during this time are added to a new batch job.

Following the three (3) day period, the request's status changes to 'submitted', and the batch can't be stopped. The purge process removes all data associated with the user from all Amplitude's systems, including associated recovery and back-up systems. After the job is finished, its status changes to "done". 

## JSON Body Parameter

The body parameter is required. It is the deletion request object listing the user_ids and amplitude_ids for the users to delete.

| key | description |
| --- | --- |
| `amplitude_ids` | Amplitude IDs for the users to delete. |
| `user_ids` | User IDs for the users to delete. |
| `requester` | The internal user who requested the deletion. This is useful for auditing. |
| `ignore_invalid_id` | When `true`, the job ignores invalid user IDs. Invalid user IDs are users that don't exist in the project. |
| `delete_from_org` | Delete user from the entire org instead of this project only. Can be used only with orgs that have the Portfolio feature enabled. Requests must be by `user_ids` only. Values can be either `True` or `False`. Defaults to `False`. |

## Response Object

The response for a POST request contains the following fields:

| key | description |
| --- | --- |
| `day` | The day the deletion job is scheduled to begin |
| `status` | The status of the deletion job |
| `amplitude_ids` and `user_ids` | List of the amplitude ids to delete |
| `app` | project/app id, only appears when the deletion is done for multiple projects |

POST Deletion Request (JSON)

Removes the specified ID from a deletion job.

Amplitude API Integration Profile

Data Collections

Operations

Build every single integration your customers need with AI