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

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

​
Request Body

FieldTypeRequiredDescription
companiesarrayYesArray of company objects
company_idstringYesUnique identifier for the company
metadataobjectNoKey-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"
      }
    }
  ]
}

​
Response

A successful call returns a job object: 
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "submitted_at": "2025-02-02T12:35:10Z"
}
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 company profiles.

​
Endpoint

[POST] https://analytex.userpilot.io/v1/companies/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/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.

​
Limitations

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