The Bulk Users & Companies Update HTTP API allows you to update user and company profiles in bulk. This API is intended for quickly synchronizing or modifying multiple profiles at once—either by sending JSON payloads directly or by uploading NDJSON files containing the updates. This API is different from the Historical Data Import API (for importing historical user/event data) and the Identify & Track API (for updating user/event properties in real time). The Bulk Profile Update API focuses solely on updating user and company profile properties.

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.

Use Cases

Bulk Update User Attributes: Use the JSON endpoint to update custom attributes for multiple users.
Bulk Update Company Information: Send an array of company records to update details like company name, partner contact, or company type.
Large-Scale Data Synchronization: When updating tens of thousands of users/companies, use the file upload endpoints with NDJSON formatted files for better performance and error handling.

Authentication

All requests require an API token in the Authorization header:

Authorization: Token {YOUR_API_KEY}

Your API key carries many privileges, so keep it secure and do not share it in public areas. All API requests must be made over HTTPS.

Limitations

File size up to 50 MB (for file uploads).
JSON/NDJSON list up to 10,000 users or companies per request.
Up to 1,200 rows processed per minute.
Only primitive types (string, number, boolean, null) are supported in metadata.

Endpoints

1. Update User Profiles (JSON)

Endpoint

POST https://analytex.userpilot.io/v1/users/bulk_identify

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

Headers

Content-Type: application/json
Accept: application/json, text/plain, */*
Authorization: Token {YOUR_API_KEY}

Request Body

Send a JSON payload containing an array of user profile objects:

{
  "users": [
    {
      "user_id": "user_001",
      "company_id": "comp001",
      "metadata": {
        "last_ticket_created": "2025-02-01T10:20:30Z",
        "tickets_created": "15",
        "tickets_resolved": "14",
        "tickets_pending": "1",
        "avg_resolution_time": "2h",
        "customer_satisfaction": "4.8",
        "escalation_count": "1"
      }
    },
    {
      "user_id": "user_002",
      "company_id": "comp002",
      "metadata": {
        "last_ticket_created": "2025-01-31T09:15:00Z",
        "tickets_created": "8",
        "tickets_resolved": "7",
        "tickets_pending": "1",
        "avg_resolution_time": "3h",
        "customer_satisfaction": "4.5",
        "escalation_count": "0"
      }
    }
  ]
}

Response

A successful call returns a job object:

{
  "job_id": "9536d797-7039-4d30-8c11-ac437367d732",
  "status": "queued",
  "submitted_at": "2025-02-02T12:34:56Z"
}

2. Update Company Profiles (JSON)

Endpoint

POST https://analytex.userpilot.io/v1/companies/bulk_identify

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

Headers

Content-Type: application/json
Accept: application/json, text/plain, */*
Authorization: Token {YOUR_API_KEY}

Request Body

Send a JSON payload containing an array of company profile objects:

{
  "companies": [
    {
      "company_id": "company_001",
      "metadata": {
        "subscription_status": "active",
        "subscription_plan": "enterprise",
        "deal_size": "500000",
        "monthly_active_users": "120",
        "platform_usage_score": "90",
        "account_manager": "Alice Manager"
      }
    },
    {
      "company_id": "company_002",
      "metadata": {
        "subscription_status": "trial",
        "subscription_plan": "basic",
        "deal_size": "15000",
        "monthly_active_users": "50",
        "platform_usage_score": "70",
        "account_manager": "Bob Manager"
      }
    }
  ]
}

Response

A successful call returns a job object:

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "submitted_at": "2025-02-02T12:35:10Z"
}

3. Update Profiles via File Upload (NDJSON)

For very large updates, you may upload NDJSON files containing user or company profiles.

3.1 Update User Profiles via File Upload

Endpoint

POST https://analytex.userpilot.io/v1/users/bulk_identify

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

Headers

Content-Type: multipart/form-data
Accept: application/json, text/plain, */*
Authorization: Token {YOUR_API_KEY}

Request Body

Submit the file using multipart/form-data. Include a key called file with your NDJSON file:

curl -X POST "https://analytex.userpilot.io/v1/users/bulk_identify" \
     -H "Authorization: Token {YOUR_API_KEY}" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/your/file.ndjson"

💡 Each line in the file should be a valid JSON object.

3.2 Update Company Profiles via File Upload

Endpoint

POST https://analytex.userpilot.io/v1/companies/bulk_identify

Headers

Content-Type: multipart/form-data
Accept: application/json, text/plain, */*
Authorization: Token {YOUR_API_KEY}

Request Body

Use multipart/form-data with a key named file containing your NDJSON file:

curl -X POST "https://analytex.userpilot.io/v1/companies/bulk_identify" \
     -H "Authorization: Token {YOUR_API_KEY}" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/your/file.ndjson"

4. Bulk Update Job Monitoring

After submitting a bulk update, a job is created to process your profiles asynchronously.

4.1 List All Bulk Update Jobs

Endpoint

GET https://analytex.userpilot.io/v1/background_jobs/

Headers

Authorization: Token {YOUR_API_KEY}
Accept: application/json, text/plain, */*

Response

Returns a list of jobs with their statuses, IDs, and submission timestamps:

[
  {
    "elapsed_time": 7,
    "end_time": "2025-03-08T18:50:14.150722",
    "file_size": 233,
    "filename": "NX-51f4acf7_identify_user_316e590e-755c-4b37-b6a0-0c34912b3210.ndjson",
    "job_id": "bulk:jobs:NX-51f4acf7:96b94fed-e9fe-4aa9-bce5-4f904ee3c533",
    "links": "/v1/background_jobs/bulk:jobs:NX-51f4acf7:96b94fed-e9fe-4aa9-bce5-4f904ee3c533",
    "start_time": "2025-03-08T18:50:07.217364",
    "status": "completed",
    "total_rows": 2,
    "type": "identify_user"
  }
]

4.2 Get Bulk Update Job Status by ID

Endpoint

GET https://analytex.userpilot.io/v1/background_jobs/{job_id}

Replace {job_id} with the ID of the job you want to inspect.

Headers

Authorization: Token {YOUR_API_KEY}
Accept: application/json, text/plain, */*

Response

Returns details about the specific job, including its current status and any errors encountered:

{
  "job_id": "9536d797-7039-4d30-8c11-ac437367d732",
  "status": "completed",
  "processed_count": 1500,
  "error_count": 0,
  "submitted_at": "2025-02-02T12:34:56Z",
  "completed_at": "2025-02-02T12:45:00Z"
}

Best Practices

Validate Your Data: Ensure each record includes the required identifiers (user_id or company_id) and that metadata is formatted correctly.
Monitor Jobs: Always use the job monitoring endpoints to check the status of your bulk updates.
Rate Limits and Retries: If you experience rate limits or timeouts, batch your requests and monitor job statuses before submitting more.

Troubleshooting

Authentication Errors: Verify your API token and that it is sent in the Authorization header.
Invalid Payload: Ensure your JSON/NDJSON is well-formed and required fields are present.
Job Failures: Use the job status endpoint to inspect error messages for failed records or processing issues.

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

​Use Cases

​Authentication

​Limitations

​Endpoints

​1. Update User Profiles (JSON)

​Endpoint

​Headers

​Request Body

​Response

​2. Update Company Profiles (JSON)

​Endpoint

​Headers

​Request Body

​Response

​3. Update Profiles via File Upload (NDJSON)

​3.1 Update User Profiles via File Upload

​Endpoint

​Headers

​Request Body

​3.2 Update Company Profiles via File Upload

​Endpoint

​Headers

​Request Body

​4. Bulk Update Job Monitoring

​4.1 List All Bulk Update Jobs

​Endpoint

​Headers

​Response

​4.2 Get Bulk Update Job Status by ID

​Endpoint

​Headers

​Response

​Best Practices

​Troubleshooting

Use Cases

Authentication

Limitations

Endpoints

1. Update User Profiles (JSON)

Endpoint

Headers

Request Body

Response

2. Update Company Profiles (JSON)

Endpoint

Headers

Request Body

Response

3. Update Profiles via File Upload (NDJSON)

3.1 Update User Profiles via File Upload

Endpoint

Headers

Request Body

3.2 Update Company Profiles via File Upload

Endpoint

Headers

Request Body

4. Bulk Update Job Monitoring

4.1 List All Bulk Update Jobs

Endpoint

Headers

Response

4.2 Get Bulk Update Job Status by ID

Endpoint

Headers

Response

Best Practices

Troubleshooting