Upload Request
POST https://api.amplitude.com/2/httpapi
Upload Request Body
| Name | Description |
|---|---|
api_key | Required. String. Amplitude project API key. If you're using Qodex, set this variable in the Amplitude API Environment. |
events | Required. []. Array of Events 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 'locationlat' and 'locationlng' 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 deviceid isn't used. String. ID for the user. Must have a minimum length of 5 characters unless overridden with the `minuser_length` option. |
device_id | Required if userid isn't used. String. A device-specific identifier, such as the Identifier for Vendor on iOS. If a deviceid 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. 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 $remoteto 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 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 userid and timestamp from each other. We recommend you send an eventid, 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 sessionid of -1 is the same as no sessionid specified. |
insert_id | Optional. String. A unique identifier for the event. We will deduplicate subsequent events sent with an insertid we have already seen before within the past 7 days. We recommend generation a UUID or using some combination of deviceid, userid, eventtype, 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 userid & deviceid fields. |
Request Body
{"api_key"=>"{{api_key}}", "events"=>[{"user_id"=>"datamonster@gmail.com", "device_id"=>"C8F9E604-F01A-4BD9-95C6-8E5357DF265D", "event_type"=>"watch_tutorial", "time"=>1396381378123, "event_properties"=>{"load_time"=>0.8371, "source"=>"notification", "dates"=>["monday", "tuesday"]}, "user_properties"=>{"age"=>25, "gender"=>"female", "interests"=>["chess", "football", "music"]}, "groups"=>{"team_id"=>"1", "company_name"=>["Amplitude", "DataMonster"]}, "app_version"=>"2.1.3", "platform"=>"iOS", "os_name"=>"Android", "os_version"=>"4.2.2", "device_brand"=>"Verizon", "device_manufacturer"=>"Apple", "device_model"=>"iPhone 9,1", "carrier"=>"Verizon", "country"=>"United States", "region"=>"California", "city"=>"San Francisco", "dma"=>"San Francisco-Oakland-San Jose, CA", "language"=>"English", "price"=>4.99, "quantity"=>3, "revenue"=>-1.99, "productId"=>"Google Pay Store Product Id", "revenueType"=>"Refund", "location_lat"=>37.77, "location_lng"=>-122.39, "ip"=>"127.0.0.1", "idfa"=>"AEBE52E7-03EE-455A-B3C4-E57283966239", "idfv"=>"BCCE52E7-03EE-321A-B3D4-E57123966239", "adid"=>"AEBE52E7-03EE-455A-B3C4-E57283966239", "android_id"=>"BCCE52E7-03EE-321A-B3D4-E57123966239", "event_id"=>23, "session_id"=>1396381378123, "insert_id"=>"5f0adeff-6668-4427-8d02-57d803a2b841"}]}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string |
RESPONSES
status: OK
{"code":200,"server_upload_time":1645223965262,"payload_size_bytes":1731,"events_ingested":1}