Events Bulk Import

The Import API allows you to import historical user data from other platforms into Userpilot. With this API, you can migrate data related to user and company identification, page views, and custom events. This enables a seamless transition and continuity of insights, providing a comprehensive view of user interactions.

This feature is available on the Enterprise plan only or as an add-on to the Growth plan. If interested in adding this feature please contact sales@userpilot.com or your designated Customer Success Manager (CSM).

Use Cases

Data Migration: Migrate historical data from other analytics platforms to Userpilot, ensuring no loss of valuable insights.
Retrospective Analysis: Analyze historical user behavior and feature engagement by importing past data on user actions, page views, and events.

PII Data NoticeBefore passing any Personally Identifiable Information (PII) such as names, emails, or other sensitive user data to Userpilot:

Security & Compliance: Verify internally with your legal, security, and compliance teams that doing so aligns with your organization’s data privacy policies and applicable regulations (e.g., GDPR, CCPA).
Data Type Mapping: Ensure correct data type mapping for all properties. Userpilot supports String, Numeric, and Date types. Make sure dates are in ISO8601 format and numeric values are properly formatted. Incorrect type mapping can cause issues with segmentation, analytics, and debugging.
Debugging: Proper data formatting is crucial for effective debugging and troubleshooting. Verify that your data maps correctly to Userpilot’s expected formats before implementation.

If you’re migrating from another provider, complete the import process before installing the SDK. This ensures historical data is ready for analysis once Userpilot starts tracking live events.

The Import API does not merge with a user’s or company’s existing (or live) property state, unlike real-time Identify calls. Each imported event is written as-is, so it’s meant for one-time historical backfill, not ongoing updates to current property values. If a user is later identified in real time, that identify can overwrite properties you imported. To keep current property values in sync, use the Bulk Update API instead.

Authorization

See the Authentication and Environment pages for details on API key usage and endpoint URLs. Authentication Method: Include your API key in the Authorization header:

Authorization: Token {{API_KEY}}

All API requests must be made over HTTPS.

Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API keys in publicly accessible areas.

Rate Limits

The Import API implements rate limiting to maintain system stability and ensure fair resource allocation across all users. These limits help prevent system overload while allowing efficient data migration workflows.

Rate Limit Details

Job Limitation: One import job at a time per application token
File Size: Up to 1 GB file size for import operations

Error Responses

401 Unauthorized: Returned when the API token is missing, invalid, or isn’t a write/admin token
409 Conflict: Returned when attempting to create a new import job while another is in progress
413 Payload Too Large: Returned when file size exceeds 1 GB

Best Practices

Check Job Status First: Always verify no existing import jobs are running before initiating a new one.Implement Retry Logic: When encountering a 409 Conflict error, wait for the current job to complete before retrying.Monitor Job Progress: Use the job status endpoints to track import progress and avoid conflicts.Optimize File Sizes: For very large datasets, consider splitting files to stay within the 1 GB limit.

Endpoints

For most users, the HTTP API endpoint URL is https://analytex.userpilot.io. If you are on Enterprise or EU hosting, refer to the Environment page in the application to retrieve your dedicated endpoint.

1. Request Data Import

Endpoint

POST {{ENDPOINT}}/v1/imports

The endpoint URL uses the analytex environment. For EU data residency, use analytex-eu instead. See Environment Settings for your specific endpoint.

Description

Initiates a data import job. Accepts a file in CSV or NDJSON format containing historical data.

Headers

Header	Value	Required
`Content-Type`	`multipart/form-data`	Yes
`Authorization`	`Token {{API_KEY}}`	Yes

Request Parameters

Parameter	Type	Required	Description
file	File	Yes	The CSV or NDJSON file containing the data to be imported. See the event schema for more details.

Data Format

The imported data should conform to a list of events. See the Import API Event Schema for details on supported event types and required fields.

Required fields vary by source. For example, source: web-client events require hostname and pathname (or a url field in their place), plus user_agent.

Example Import File

NDJSON
CSV

file.ndjson

{"event_type": "identify_user", "source": "backend-http-import", "user_id": "user_123", "inserted_at": "2024-07-28T08:55:35.874555", "metadata": { "name": "John Doe", "email": "john.doe@example.com", "location": "Dublin, Ireland" },"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"}
{"event_type": "identify_company", "source": "backend-http-import","company_id": "company_123","inserted_at": "2024-07-28T08:55:35.874555","metadata": {"name": "Acme Labs Inc.","industry": "Software","size": "200-500","location": "San Francisco, CA"}}

file.csv

event_type,event_name,source,user_id,company_id,hostname,pathname,country_code,screen_width,screen_height,operating_system,browser,browser_language,user_agent,device_type,inserted_at,metadata
identify_user,,web-client,User-7320-001,Company-607-001,campfire-example.userpilot.io,/profile/settings/,DE,1086,696,Mac,Edge,de-DE,Edge - Mozilla/5.0 (Mac) AppleWebKit/537.36,Mobile,2023-12-26 14:36:15.453703,"{""created_at"": ""1694172975"", ""name"": ""User-Alice"", ""prop_0"": ""value_743"", ""prop_1"": ""value_927""}"
page_view,,web-client,User-9491-002,Company-973-002,campfire-example.userpilot.io,/home/,DE,832,809,iOS,Chrome,fr-FR,Chrome - Mozilla/5.0 (iOS) AppleWebKit/537.36,Mobile,2024-04-13 14:36:15.453788,"{}"
track,created_project,web-client,User-6267-003,Company-584-003,campfire-example.userpilot.io,/profile/settings/,PS,1114,704,iOS,Safari,en-US,Safari - Mozilla/5.0 (iOS) AppleWebKit/537.36,Mobile,2024-05-05 14:36:15.453813,"{""created_at"": ""1730810175"", ""name"": ""User-Bob"", ""prop_0"": ""value_17""}"

Uploading the File

curl -X POST "{{ENDPOINT}}/v1/imports" \
-H "Authorization: Token {{API_KEY}}" \
-F "file=@/path/to/import_data.ndjson"

Response

Success
Error

{
  "end_time": null,
  "file_size": 2234,
  "filename": "2024-10-28.ndjson",
  "job_id": "imports:jobs:NX-51f4acf7:f681073b-21ac-4276-9af5-c662dc05fb25",
  "links": "/v1/background_jobs/imports:jobs:NX-51f4acf7:f681073b-21ac-4276-9af5-c662dc05fb25",
  "start_time": "2024-11-28T10:34:11.376662",
  "status": "queued",
  "total_rows": 0,
  "type": "import"
}

{
  "errors": [
    {
      "details": null,
      "error": "Conflict",
      "error_code": "409",
      "message": "The request could not be completed due to a conflict with the current state of the target resource."
    }
  ]
}

2. Get All Import Job Statuses

Endpoint

GET {{ENDPOINT}}/v1/background_jobs

Description

Fetches the status of all import jobs, allowing users to monitor the progress of multiple imports at once.

Headers

Header	Value	Required
`Authorization`	`Token {{API_KEY}}`	Yes

Example Request

curl -X GET "{{ENDPOINT}}/v1/background_jobs" \
-H "Authorization: Token {{API_KEY}}"

Response

Returns a list of job objects, each with details such as job_id, status, start_time, end_time, total_rows, and reason_for_failure (if any). status can be queued, pending_refresh (data written, finalizing before completion), completed, or failed.

[
  {
    "elapsed_time": 6,
    "end_time": "2025-05-19T07:23:00.354452",
    "file_size": 757,
    "filename": "2024-10-28.ndjson",
    "job_id": "imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
    "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
    "start_time": "2025-05-19T07:22:54.409499",
    "status": "completed",
    "total_rows": 3,
    "type": "import"
  },
  {
    "elapsed_time": 0,
    "end_time": "2025-05-19T07:09:49.883288",
    "file_size": 416,
    "filename": "2024-10-28.ndjson",
    "job_id": "imports:jobs:NX-ac54070e:1fd8f0d4-cd97-432f-86fe-3df9effc1912",
    "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:1fd8f0d4-cd97-432f-86fe-3df9effc1912",
    "reason_for_failure": [
      "Required field `user_id` not provided in the row: %{\"event_name\" => \"\", \"event_type\" => \"identify_user\", \"metadata\" => %{\"avg_resolution_time\" => \"2h\", \"customer_satisfaction\" => \"4.8\", \"escalation_count\" => \"1\", \"last_ticket_created\" => \"2025-02-01T10:20:30Z\", \"tickets_created\" => \"15\", \"tickets_pending\" => \"1\", \"tickets_resolved\" => \"14\"}}"
    ],
    "start_time": "2025-05-19T07:09:49.880967",
    "status": "failed",
    "total_rows": 0,
    "type": "import"
  }
  //... more jobs
]

3. Get Job Status by ID

Endpoint

GET {{ENDPOINT}}/v1/background_jobs/:job_id

Description

Fetches the status of a specific import job using its job_id, useful for tracking a single import job.

Headers

Header	Value	Required
`Authorization`	`Token {{API_KEY}}`	Yes

Path Parameters

Parameter	Type	Required	Description
job_id	String	Yes	The unique identifier of the import job

Example Request

curl -X GET "{{ENDPOINT}}/v1/background_jobs/:job_id" \
-H "Authorization: Token {{API_KEY}}"

Response

Returns job details including job_id, status, start_time, end_time, total_rows, and reason_for_failure (if any).

{
  "elapsed_time": 6,
  "end_time": "2025-05-19T07:23:00.354452",
  "file_size": 757,
  "filename": "2024-10-28.ndjson",
  "job_id": "imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
  "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
  "start_time": "2025-05-19T07:22:54.409499",
  "status": "completed",
  "total_rows": 3,
  "type": "import"
}

For required validation rules for your import file, see the Row Validation Rules page.

For best practices on importing user and company data, see Best Practices for Accumulative Properties.

For any questions or concerns please reach out to support@userpilot.com

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

Use Cases

Authorization

Rate Limits

Rate Limit Details

Error Responses

Best Practices

Endpoints

1. Request Data Import

Endpoint

Description

Headers

Request Parameters

Data Format

Example Import File

Response

2. Get All Import Job Statuses

Endpoint

Description

Headers

Example Request

Response

3. Get Job Status by ID

Endpoint

Description

Headers

Path Parameters

Example Request

Response

​Use Cases

​Authorization

​Rate Limits

​Rate Limit Details

​Error Responses

​Best Practices

​Endpoints

​1. Request Data Import

​Endpoint

​Description

​Headers

​Request Parameters

​Data Format

​Example Import File

​Response

​2. Get All Import Job Statuses

​Endpoint

​Description

​Headers

​Example Request

​Response

​3. Get Job Status by ID

​Endpoint

​Description

​Headers

​Path Parameters

​Example Request

​Response

Use Cases

Authorization

Rate Limits

Rate Limit Details

Error Responses

Best Practices

Endpoints

1. Request Data Import

Endpoint

Description

Headers

Request Parameters

Data Format

Example Import File

Response

2. Get All Import Job Statuses

Endpoint

Description

Headers

Example Request

Response

3. Get Job Status by ID

Endpoint

Description

Headers

Path Parameters

Example Request

Response