openapi: 3.0.0 info: title: Userpilot Analytics Real-time API version: 1.0.0 termsOfService: https://userpilot.io/terms-of-service/ description: "Userpilot's API suite for user identification, event tracking, data import/export, and user/company management.\n\nContact Support:\n Email: support@userpilot.com" contact: name: Userpilot url: https://userpilot.io email: support@userpilot.com license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://{environment}.userpilot.io description: Analytical data endpoint for Userpilot API. Choose the appropriate environment based on your data residency requirements and account type. variables: environment: description: The Userpilot environment endpoint for your account. Most customers use the default US region (analytex), while EU customers with data residency requirements use the EU region (analytex-eu). You can find your specific endpoint URL in your Userpilot dashboard under [Environment Settings](https://run.userpilot.io/environment). enum: - analytex - analytex-eu default: analytex tags: - name: Real-time paths: /v1/identify: parameters: [] post: tags: - Real-time summary: Identify parameters: - name: Content-Type in: header required: false example: application/json schema: type: string default: application/json - name: Accept in: header required: false example: application/json schema: type: string default: application/json - $ref: '#/components/parameters/AuthorizationHeader' responses: '401': headers: Content-Type: schema: type: string default: application/json example: application/json description: Unauthorized - Invalid API key content: application/json: schema: type: object properties: errors: type: array items: type: object properties: details: type: string error: type: string error_code: type: string format: color message: type: string requestBody: content: application/json: schema: type: object required: - user_id example: user_id: user_789456 metadata: name: Sarah Johnson email: sarah.johnson@techstartup.com job_title: Product Manager department: Product location: New York, NY hire_date: '2022-03-15' years_experience: 8 skills: Product Strategy, User Research, Agile subscription_plan: Pro last_login: '2024-01-15T10:30:00Z' preferences_language: en preferences_timezone: America/New_York preferences_notifications: email company: company_id: comp_techstartup_2024 name: TechStartup Inc. industry: SaaS size: 50-100 location: New York, NY website: https://techstartup.com subscription_tier: Enterprise annual_revenue: $5M-$10M founded_year: '2020' primary_product: Project Management Platform customer_count: 2500 team_engineering: 25 team_sales: 15 team_marketing: 8 team_support: 12 properties: user_id: type: string description: The unique identifier for the user. This is the ID that Userpilot uses to identify the user. example: '123987' metadata: type: object description: 'Optional user metadata. You can add, remove, or modify any properties as needed for your use case. Note: Only string values are supported (numbers and dates should be sent as strings).' additionalProperties: true properties: custom_user_property: type: string description: 'example: Name, Job title, etc.' company: type: object description: Company information. If provided, `company_id` is required. Additional company properties are optional metadata. required: - company_id properties: company_id: type: string description: The unique identifier for the company. This is the ID that Userpilot uses to identify the company. example: company_123 custom_company_property: type: string description: 'example: Company name, Industry, etc.' additionalProperties: true /v1/users/bulk_identify: parameters: [] post: tags: - Real-time summary: Users - Bulk Identify and Update parameters: - name: Content-Type in: header required: false example: application/json schema: type: string default: application/json - name: Accept in: header required: false example: application/json schema: type: string default: application/json - $ref: '#/components/parameters/AuthorizationHeader' responses: '202': headers: Date: schema: type: string default: application/json example: Mon, 19 May 2025 07:29:12 GMT Content-Type: schema: type: string default: application/json example: application/json; charset=utf-8 Content-Length: schema: type: integer default: 379 example: '379' Connection: schema: type: string example: keep-alive cache-control: schema: type: string example: max-age=0, private, must-revalidate server: schema: type: string example: Cowboy x-request-id: schema: type: string example: GEDdGIKmRewi6ZIAEYcB description: Accepted - Bulk identify content: application/json: schema: type: object properties: end_time: nullable: true file_size: type: integer filename: type: string job_id: type: string format: uri links: type: string format: style start_time: type: string status: type: string enum: - queued - validating - processing - pending_refresh - completed - failed total_rows: type: integer type: type: string requestBody: content: application/json: example: users: - user_id: user_123 company_id: comp_techstartup_2024 metadata: name: John Smith email: john.smith@techstartup.com job_title: Support Manager tickets_created: '2024-01-15T08:00:00Z' tickets_resolved: '2024-01-15T16:30:00Z' tickets_pending: 3 avg_resolution_time: 3.25 customer_satisfaction: 95% escalation_count: 10 - user_id: user_456 company_id: comp_techstartup_2024 metadata: name: Emma Davis email: emma.davis@techstartup.com job_title: Support Specialist tickets_created: '2024-01-15T09:15:00Z' tickets_resolved: '2024-01-15T17:45:00Z' tickets_pending: 5 avg_resolution_time: 4.5 customer_satisfaction: 92% escalation_count: 8 schema: type: object properties: users: type: array items: type: object required: - user_id properties: user_id: type: string description: The unique identifier for the user. This is the ID that Userpilot uses to identify the user. example: '123987' company_id: type: string description: (Optional) The unique identifier for the company. This is the ID that Userpilot uses to identify the company. example: company_123 metadata: type: object description: 'Optional user metadata. You can add, remove, or modify any properties as needed for your use case. Note: Only string values are supported.' additionalProperties: true properties: custom_user_property: type: string description: 'example: Name, Job title, etc.' components: parameters: AuthorizationHeader: name: Authorization in: header required: true description: 'API authentication token in the format: `Token {{API_KEY}}` Obtain your API key from the [Userpilot Environment Settings](https://run.userpilot.io/environment).' schema: type: string default: Token ABC_1234_EFGH_5678 example: Token ABC_1234_EFGH_5678