Bulk Identify/Update Companies

Bulk identify and update company profiles using Userpilot’s HTTP API for large-scale company data synchronization.

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

Endpoint

[POST] https://analytex.userpilot.io/v1/companies/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
Authorization	Token {YOUR_API_KEY}	Yes
Accept	application/json, text/plain, */*	Yes

Request Body

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

JSON Payload Example

{
  "companies": [
    {
      "company_id": "company_001",
      "metadata": {
        "subscription_status": "active",
        "subscription_plan": "enterprise",
        "deal_size": "500000"
      }
    },
    {
      "company_id": "company_002",
      "metadata": {
        "subscription_status": "trial",
        "subscription_plan": "basic"
      }
    }
    // ... Additional companies 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": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "submitted_at": "2025-02-02T12:35:10Z"
}

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 company profiles.

Endpoint

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

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/companies/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 companies.

---

Rate Limits

The Bulk Updates API implements rate limiting to ensure efficient processing of large-scale company data operations while maintaining system stability. These limits help optimize performance for bulk company 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 bulk update)
• Company Processing: 1,800 companies 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 company processing speed to stay within the 1,800 companies 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 companies per request.
• Only primitive types (string, number, boolean, null) are supported in metadata.
• A company will not appear on the dashboard unless at least one user is associated with it.

---

Best Practices

• Validate Your Data: Ensure each record includes the required 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.