Identify Company

Identify and update company profiles in real time or in bulk using Userpilot’s HTTP API.

The Identify Company API allows you to create or update company profiles in real time, either individually or in bulk. Use this API to keep your company data in sync with Userpilot for analytics, segmentation, and B2B engagement.

Individual Identify

Endpoint

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

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
company_id	string	Yes	Unique identifier for the company
metadata	object	No	Key-value pairs describing the company (e.g., name, industry, etc.)

Example

{
  "company_id": "company_001",
  "metadata": {
    "name": "Acme Corporation",
    "industry": "SaaS",
    "plan": "Enterprise",
    "monthly_spend": 1000
  }
}

Response

A successful identification returns HTTP status code 200 OK.

The company_id field is required. Metadata values must be primitive types (string, number, boolean, null).

---

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

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)

For more details, advanced usage, and troubleshooting, please refer to the Bulk HTTP Identify & Update API documentation.

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.

---

Limitations

• File size up to 50 MB (for file uploads).
• JSON 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 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.

---