Bulk Identify/Update Users

The Bulk Identify Users API allows you to create or update multiple user profiles in a single request. This is ideal for large-scale data synchronization, initial user imports, or batch updates from your CRM or database systems.

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.

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

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

Request Body

Field	Type	Required	Description
`users`	array	Yes	Array of user objects
`user_id`	string	Yes	Unique identifier for the user
`company_id`	string	No	Unique identifier for the company (if applicable)
`metadata`	object	No	Key-value pairs describing the user (primitives only)

JSON Payload 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"
      }
    }
    // ... Additional users up to 10,000 total
  ]
}

Optimize Your Payload: Use the full 10,000 record limit to maximize processing efficiency. The example above shows the structure for individual records - you can include up to 10,000 such records in a single request.

Response

A successful call returns 202 Accepted with a job object:

{
  "job_id": "bulk:jobs:{APP_TOKEN}:9536d797-7039-4d30-8c11-ac437367d732",
  "status": "queued",
  "start_time": "2025-02-02T12:34:56.000000",
  "end_time": null,
  "total_rows": 0,
  "file_size": 84,
  "filename": "{APP_TOKEN}_identify_user_9536d797-7039-4d30-8c11-ac437367d732.ndjson",
  "links": "/v1/background_jobs/bulk:jobs:{APP_TOKEN}:9536d797-7039-4d30-8c11-ac437367d732",
  "type": "identify_user"
}

Monitor Your Job: Use the job ID from the response to track the status of your bulk update job. Remember that only one bulk update job (user or company) can run at a time.

Row-level validation (e.g. a missing user_id) doesn’t fail the request itself: the job is still accepted and queued. Invalid rows fail individually during processing; check the job status endpoint for a reason_for_failure field explaining what went wrong with each failed row.

File Upload (NDJSON)

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

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

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

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.

File size is limited to 50 MB. Each request can contain up to 10,000 users.

Response

A successful call returns the same job object shape as the JSON payload endpoint above, with one difference: filename reflects the name of the file you uploaded instead of an auto-generated name.

Rate Limits

The Bulk Updates API implements rate limiting to ensure efficient processing of large-scale user data operations while maintaining system stability. These limits help optimize performance for bulk user profile updates and synchronizations.

Rate Limit Details

Job Limitation: One job at a time - The system processes only one bulk update job at a time (either user or company operations)
User Processing: 1,800 users per minute service consumption rate
JSON Payload: Up to 10,000 records per request
File Upload: Up to 50 MB file size

Error Responses

The API returns the following 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 job while another is in progress
413 Payload Too Large: Returned when file size exceeds 50 MB or payload exceeds 10,000 records

Best Practices

Check Job Status: Always verify no existing bulk update jobs are running before initiating a new one.Optimize Batch Sizes: Use the full 10,000 record limit for JSON payloads to maximize efficiency.Monitor Processing: Track your user processing speed to stay within the 1,800 users per minute limit.Handle File Uploads: For large datasets, use file uploads (up to 50 MB) instead of JSON payloads.

Limitations

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

Best Practices

Validate Your Data: Ensure each record includes the required identifiers (user_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.
Stuck Jobs: If a job’s processing time is taking much longer than expected, contact support@userpilot.com for help.

APIs

Real-time HTTP