Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt

Use this file to discover all available pages before exploring further.

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

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/json, text/plain, */*Yes
AuthorizationToken {YOUR_API_KEY}Yes

​
Request Body

FieldTypeRequiredDescription
usersarrayYesArray of user objects
user_idstringYesUnique identifier for the user
company_idstringNoUnique identifier for the company (if applicable)
metadataobjectNoKey-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 a job object: 
{
  "job_id": "9536d797-7039-4d30-8c11-ac437367d732",
  "status": "queued",
  "submitted_at": "2025-02-02T12:34:56Z"
}
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.

​
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

HeaderValueRequired
Content-Typemultipart/form-dataYes
Acceptapplication/json, text/plain, */*Yes
AuthorizationToken {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.

​
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

When you exceed these limits, the API returns:
  • 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.