Bulk HTTP Identify & Update API

The Bulk HTTP Users & companies Update 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 our 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.

Use Cases Example

  1. Bulk Update User Attributes:

    Use the JSON endpoint to update custom attributes for multiple users.

  2. Bulk Update Company Information:

    Send an array of company records to update details like company name, partner contact, or company type.

  3. 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

Userpilot API uses API tokens to authenticate requests. You can view your API key in the Environment Page.

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

Authentication to the API is performed via HTTP custom auth token, use  -H 'Authorization: token {YOUR_WRITE_TOKEN}'   to add your token.

HTTP Endpoints

For most users, the HTTP API endpoint URL is https://analytex.userpilot.io  as the examples show.

However, if you are on Enterprise or EU hosting, refer to the Environment Page in the application to retrieve your dedicated endpoint.

Note: All API requests must be made over HTTPS.

Endpoints Limitation

This API has the following limitation:

  • The File Size is up to 50 MB.
  • Users and Companies List (JSON) is up to 10,000 rows
  • After identifying by the API, it can serve 1,200 rows per minute

Endpoints Overview

This API exposes the following endpoints:

1. Update User Profiles (JSON)

Endpoint

POST https://{analytics_endpoint}.userpilot.io/v1/users/bulk_identify

Request Headers

Header Value Required
Content-Type application/json Yes
Accept application/json, text/plain, */* Yes
Authorization Token {YOUR_WRITE_TOKE} Yes

Request Body

Send a JSON payload that contains an array of user profile objects. For example:

{
  "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"
      }
    },
    {
      "user_id": "user_003",
      "company_id": "comp003",
      "metadata": {
        "last_ticket_created": "2024-12-15T11:00:00Z",
        "tickets_created": "20",
        "tickets_resolved": "15",
        "tickets_pending": "5",
        "avg_resolution_time": "4h",
        "customer_satisfaction": "3.9",
        "escalation_count": "3"
      }
    }
  ]
}

Response

A successful call will return a JSON object with information about the job created to process your bulk update. For example:

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

2. Update Company Profiles (JSON)

Endpoint

POST https://{analytics_endpoint}.userpilot.io/v1/companies/bulk_identify

Request Headers

Header Value Required
Content-Type application/json Yes
Accept application/json, text/plain, */* Yes
Authorization Token {YOUR_WRITE_TOKEN} Yes
Origin https://your-app-domain.com (if applicable) Optional

Request Body

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

{
  "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"
      }
    },
    {
      "company_id": "company_003",
      "metadata": {
        "subscription_status": "canceled",
        "subscription_plan": "pro",
        "deal_size": "250000",
        "monthly_active_users": "0",
        "platform_usage_score": "20",
        "account_manager": "Charlie Manager"
      }
    }
  ]
}

Response

On success, you will receive a job object similar to the one from the user endpoint:

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

3. Update Profiles via File Upload

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

3.1 Update User Profiles via File Upload

Endpoint

POST https://{analytics_endpoint}.userpilot.io/v1/users/bulk_identify

Request Headers

Header Value Required
Content-Type multipart/form-data Yes
Accept application/json, text/plain, */* Yes
Authorization Token {YOUR_WRITE_TOKEN} Yes

Request Body

Submit the file using multipart/form-data. For example, include a key called file with your NDJSON file:

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

đź’ˇTip: Ensure the file is formatted as NDJSON, with each line representing one JSON object.

3.2 Update Company Profiles via File Upload

Endpoint

POST https://{analytics_endpoint}.userpilot.io/v1/companies/bulk_identify

Request Headers

Header Value Required
Content-Type multipart/form-data Yes
Accept application/json, text/plain, */* Yes
Authorization Token {YOUR_WRITE_TOKEN} Yes

Request Body

Similarly, use multipart/form-data with a key named file containing your NDJSON file:

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

4. Bulk Update Job Monitoring

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

4.1 List All Bulk Update Jobs

Endpoint

GET https://{analytics_endpoint}.userpilot.io/v1/background_jobs/

Request Headers

Header Value Required
Authorization Token {YOUR_WRITE_TOKEN} Yes
Accept application/json, text/plain, */* Yes

Response

The API 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"
    },
    {
        "elapsed_time": 8,
        "end_time": "2025-03-08T17:52:12.239986",
        "file_size": 233,
        "filename": "NX-51f4acf7_identify_user_85cf80f4-db59-42d7-8d3a-a3a29a0cbe5a.ndjson",
        "job_id": "bulk:jobs:NX-51f4acf7:24223e9b-f9c7-4ae0-a3ea-6fe505b95665",
        "links": "/v1/background_jobs/bulk:jobs:NX-51f4acf7:24223e9b-f9c7-4ae0-a3ea-6fe505b95665",
        "start_time": "2025-03-08T17:52:04.783645",
        "status": "completed",
        "total_rows": 2,
        "type": "identify_user"
    },
    {
        "elapsed_time": 72,
        "end_time": "2025-03-06T21:32:24.755519",
        "file_size": 791312,
        "filename": "import-test-file.ndjson",
        "job_id": "imports:jobs:NX-51f4acf7:7e10abae-1f2f-4fda-9749-b89e044bae90",
        "links": "/v1/background_jobs/imports:jobs:NX-51f4acf7:7e10abae-1f2f-4fda-9749-b89e044bae90",
        "start_time": "2025-03-06T21:31:12.512485",
        "status": "completed",
        "total_rows": 310,
        "type": "import"
    },
    {
        "elapsed_time": 1455,
        "end_time": "2025-03-06T21:57:06.246824",
        "file_size": 791312,
        "filename": "import-test-file.ndjson",
        "job_id": "imports:jobs:NX-51f4acf7:84beb965-642b-4014-8a04-71a936cc903b",
        "links": "/v1/background_jobs/imports:jobs:NX-51f4acf7:84beb965-642b-4014-8a04-71a936cc903b",
        "start_time": "2025-03-06T21:32:51.212120",
        "status": "completed",
        "total_rows": 310,
        "type": "import"
    },
]

4.2 Get Bulk Update Job Status by ID

Endpoint

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

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

Request Headers

Header Value Required
Authorization Token {YOUR_WRITE_TOKEN} Yes
Accept application/json, text/plain, */* Yes

Response

The 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 that each record in your JSON or NDJSON file 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. This helps catch errors and ensures that all records are processed.

  • Rate Limits and Retries:

    If you experience rate limits or timeouts, consider batching your requests and monitoring job statuses before submitting additional batches.

Troubleshooting

  • Authentication Errors:

    Verify that your API token is correct and that it is being sent in the Authorization header as shown.

  • Invalid Payload:

    If the API returns an error regarding your payload, check that your JSON is well-formed and that required fields are present.

  • Job Failures:

    Use the job status endpoint to inspect error messages. This information can help determine if specific records failed validation or encountered processing issues.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles