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,800 companies 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.