​
Individual Identify

​
Endpoint

[POST] https://analytex.userpilot.io/v1/identify

​
Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationToken {YOUR_API_KEY}Yes
X-API-Version2020-09-22Yes

​
Request Body

FieldTypeRequiredDescription
user_idstringYesUnique identifier for the user
metadataobjectNoKey-value pairs describing the user
companyobjectNoObject with at least an id field for company association

​
Example

{
  "user_id": "user_001",
  "metadata": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "company": {
    "id": "company_001"
  }
}

​
Response

A successful identification returns HTTP status code 202 Accepted.
The user_id field is required. If you include a company object, it must have at least an id field.

​
Bulk Identify

For full details on how to use the Bulk HTTP Identify & Update API, including endpoints, authentication, request/response examples, limitations, best practices, and troubleshooting see the dedicated documentation page: Bulk HTTP Identify & Update API Below is a summary for quick reference:

​
Endpoint

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

​
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)
For more details, advanced usage, and troubleshooting, please refer to the Bulk HTTP Identify & Update API documentation.

​
Bulk Identify: JSON Payload

​
Endpoint

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

​
Headers

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

​
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"
}
Use the job ID from the response to monitor the status of your bulk update job.

​
Bulk Identify: File Upload (NDJSON)

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

​
Endpoint

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

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

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

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