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.

​
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"
      }
    }
  ]
}

​
Response

A successful call returns a job object: 
{
  "job_id": "9536d797-7039-4d30-8c11-ac437367d732",
  "status": "queued",
  "submitted_at": "2025-02-02T12:34:56Z"
}
Use the job ID from the response to monitor the status of your bulk update job.

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

​
Limitations

  • File size up to 50 MB (for file uploads).
  • JSON/NDJSON list up to 10,000 users per request.
  • Up to 1,800 users per minute.
  • 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.