> ## Documentation Index > Fetch the complete documentation index at: https://docs.usertour.io/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a company ## OpenAPI ````yaml /api-reference-v2/openapi.json put /v2/projects/{projectId}/environments/{environmentId}/companies/{id} openapi: 3.0.0 info: title: Usertour API v2 description: >- Project-scoped v2 API. Authenticate with a personal API token — an opaque `utp_...` string (NOT a JWT: do not try to decode it), created in the Usertour app under Settings → API, sent as `Authorization: Bearer utp_...`. version: '2.0' contact: {} servers: - url: https://api.usertour.io security: [] tags: [] paths: /v2/projects/{projectId}/environments/{environmentId}/companies/{id}: put: tags: - Companies summary: Create or update a company operationId: ApiCompaniesController_upsert parameters: - name: id required: true in: path description: Company external ID schema: type: string - name: environmentId required: true in: path description: Environment ID schema: type: string - name: projectId required: true in: path description: Project ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertCompanyBodyDto' responses: '200': description: Company created or updated content: application/json: schema: $ref: '#/components/schemas/CompanyDto' '400': description: >- Invalid request — E1017 validation (may carry `issues`; an invalid orderBy/limit is also E1017), E1015 invalid scope, E0003 invalid against current domain state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '401': description: Missing or expired API key — E1010, E1020. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '403': description: >- Refused — E1000 invalid key, E1011 project not in token scope, E1012 insufficient scope, E1029 environment not in token scope, E1032 environment creation needs a token without env-targeted capabilities (its allowlist cannot cover a not-yet-existing environment). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '429': description: >- Rate limit exceeded — E1013. The limit follows the project's plan (100/500/1000/3000 requests per minute); unknown credentials share a per-IP bucket. Every response also carries X-RateLimit-Limit / -Remaining / -Reset for pacing; a 429 adds the standard Retry-After header (seconds to back off). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - bearer: [] components: schemas: UpsertCompanyBodyDto: type: object properties: attributes: description: >- Custom attributes to set on the company (merged into existing attributes). Attributes with an unknown codeName AUTO-CREATE a definition (dataType inferred from the value) — a mistyped key silently creates a new attribute instead of updating the real one. Each key must be a valid codeName: start with a letter, then letters/digits/underscores, 2–100 chars. type: object additionalProperties: {} additionalProperties: false CompanyDto: type: object properties: id: type: string description: External company id — the id your app supplied at group/upsert. object: type: string enum: - company attributes: type: object additionalProperties: {} createdAt: type: string format: date-time users: type: array items: type: object properties: id: type: string object: type: string enum: - user attributes: type: object additionalProperties: {} createdAt: type: string format: date-time required: - id - object - attributes - createdAt description: 'null = not expanded (pass expand: ["users"]); [] = expanded, none.' nullable: true memberships: type: array items: type: object properties: id: type: string description: >- Internal membership record id (not addressable anywhere) — join on userId/companyId instead. object: type: string enum: - companyMembership attributes: type: object additionalProperties: {} createdAt: type: string format: date-time companyId: type: string description: External company id — the id companies are addressed by. userId: type: string description: External user id — the id users are addressed by. user: type: object properties: id: type: string object: type: string enum: - user attributes: type: object additionalProperties: {} createdAt: type: string format: date-time required: - id - object - attributes - createdAt required: - id - object - attributes - createdAt - companyId - userId description: >- null = not expanded (pass expand: ["memberships"]); [] = expanded, none. nullable: true required: - id - object - attributes - createdAt - users - memberships ErrorResponseDto: type: object properties: error: type: object properties: code: type: string description: >- Stable machine-readable code (e.g. E1017). Match on this, never on `message`. message: type: string description: Human-readable summary. Wording may change between releases. issues: description: >- Validation errors (E1017) may carry one entry per problem so every field can be fixed in a single round-trip. Absent on other errors. type: array items: type: object properties: rule: type: string description: >- Which validation layer rejected it: schema | reactive_condition | action_not_allowed | step_shape | reference_target | auto_start | media_url. New values may be added; treat an unknown value as a generic validation failure. message: type: string path: description: >- Path into the request body (e.g. `steps[0].triggers[0].when[1]`). type: string required: - rule - message doc_url: type: string description: Base URL of the API documentation. required: - error securitySchemes: bearer: scheme: bearer bearerFormat: utp_... personal API token (opaque) type: http ````