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 support@userpilot.co.

​
Use Cases

  1. Data Migration: Migrate historical data from other analytics platforms to Userpilot, ensuring no loss of valuable insights.
  2. Retrospective Analysis: Analyze historical user behavior and feature engagement by importing past data on user actions, page views, and events.
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.

​
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 is limited to one import job per application token at a time. If you attempt to create another import job while one is already in progress, the API will return a 409 Conflict error.

​
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

​
Description

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

​
Headers

HeaderValueRequired
Content-Typemultipart/form-dataYes
AuthorizationToken {{API_KEY}}Yes

​
Request Parameters

ParameterTypeRequiredDescription
fileFileYesThe 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.

​
Example Import File

file.ndjson
{"event_type": "identify_user", "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","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"}}
Uploading the File 
curl -X POST "{{ENDPOINT}}/v1/imports" \
-H "Authorization: Token {{API_KEY}}" \
-F "file=@/path/to/import_data.ndjson"

​
Response

{
  "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
}

​
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

HeaderValueRequired
AuthorizationToken {{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). 
[
  {
    "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
  },
  {
    "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
  }
  //... more jobs
]

​
3. Get Job Status by ID

​
Endpoint

GET {{ENDPOINT}}/api/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

HeaderValueRequired
AuthorizationToken {{API_KEY}}Yes

​
Path Parameters

ParameterTypeRequiredDescription
job_idStringYesThe unique identifier of the import job

​
Example Request

curl -X GET "{{ENDPOINT}}/api/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
}
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.
If you have any questions or encounter any issues, please don’t hesitate to reach out to our support team. We’re here to help! 📧 Contact Support: support@userpilot.co