> ## Documentation Index > Fetch the complete documentation index at: https://talktohumans.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update company > Update a specific company's workspace tags, account-scoped notes, and registered custom field values. ## OpenAPI ````yaml /openapi.yaml patch /v1/companies/{company_id} openapi: 3.0.3 info: title: TalkToHumans Public API version: 1.0.0 license: name: Proprietary description: > Read and organize the LinkedIn workspace data your team already manages in TalkToHumans: accounts, people, tags, notes, sequence state, conversations, and views. servers: - url: https://api.talktohumans.app description: TalkToHumans API security: - bearerAuth: [] tags: - name: Organization description: Workspace details for the current API key. - name: LinkedIn description: >- Accounts, contacts, companies, and conversations already synced into TalkToHumans. - name: Enrich description: Profile enrichment for LinkedIn people and companies. - name: Views description: Saved TalkToHumans views and lists. paths: /v1/companies/{company_id}: patch: tags: - LinkedIn summary: Update company description: | Update a specific company's workspace tags, account-scoped notes, and registered custom field values. operationId: updateCompany parameters: - name: company_id in: path required: true description: Company ID returned by `GET /v1/companies` (the `company_id` field). schema: type: string pattern: ^[1-9][0-9]*$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCompanyRequest' examples: setCustomFields: summary: Set custom fields description: Each custom field key is the field's registered name. value: account_id: '42' Deal stage: Negotiation ARR: 50000 setTags: summary: Replace workspace tags value: account_id: '42' tags: set: - name: Target account color: green clearNotes: summary: Clear notes value: account_id: '42' notes_json: null responses: '200': description: Company updated. content: application/json: schema: $ref: '#/components/schemas/UpdateCompanyEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: schemas: UpdateCompanyRequest: type: object additionalProperties: $ref: '#/components/schemas/CustomFieldValueInput' description: > Company update payload. Known system keys are documented below. Any additional top-level key is treated as a registered company custom field key, following the same convention as the contact update endpoint. Unknown custom field keys, keys that collide with system fields, and values that do not match the registered field type are rejected. minProperties: 1 properties: account_id: type: string description: >- LinkedIn account ID returned by `GET /v1/accounts`. Required to write notes and when the company exists under multiple LinkedIn accounts. pattern: ^[1-9][0-9]*$ tags: $ref: '#/components/schemas/ContactTagsPatch' notes_json: type: string nullable: true description: >- Valid JSON text to store as account-scoped notes. Use null or an empty string to clear notes. UpdateCompanyEnvelope: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/UpdateCompanyResponse' CustomFieldValueInput: nullable: true description: >- Value for a registered custom field key. Use null to clear. Date fields must use `YYYY-MM-DD` strings. oneOf: - type: string - type: number - type: boolean ContactTagsPatch: type: object additionalProperties: false description: >- Use `set` for exact replacement, or `add`/`remove` for incremental updates. `set` cannot be combined with `add` or `remove`. properties: add: type: array items: $ref: '#/components/schemas/ContactTagInput' remove: type: array items: type: string minLength: 1 maxLength: 64 set: type: array items: $ref: '#/components/schemas/ContactTagInput' UpdateCompanyResponse: type: object additionalProperties: false required: - company properties: company: $ref: '#/components/schemas/Company' Error: type: object additionalProperties: false required: - code - message properties: code: type: string description: Machine-readable error code. enum: - unauthorized - forbidden - not_found - bad_request - internal_error - conflict - rate_limit_exceeded - billing_payment_failed - billing_subscription_incomplete - billing_subscription_expired - billing_grace_period - billing_feature_not_available - billing_insufficient_credits - billing_invalid - upstream_error message: type: string description: Human-readable error message. debug: type: string description: Development-only debug details. ContactTagInput: type: object additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 64 color: type: string description: >- Supported values are green, orange, blue, red, purple, yellow, pink, and grey. Defaults to blue when omitted or unsupported. Company: type: object additionalProperties: $ref: '#/components/schemas/CustomFieldValue' description: | A company. nullable: true required: - company_id - provider_participant_id - name - industries - locations properties: company_id: type: string provider_participant_id: type: string public_identifier: type: string name: type: string headline: type: string linkedin_url: type: string format: uri avatar_url: type: string format: uri background_cover_url: type: string format: uri headcount: type: string employee_count: type: integer nullable: true founding_date: type: string website_url: type: string format: uri follower_count: type: integer nullable: true about: type: string notes_json: type: string description: Notes stored as JSON text. industries: type: array items: $ref: '#/components/schemas/Industry' locations: type: array items: $ref: '#/components/schemas/Location' tags: type: array description: >- Workspace tags on the company. Present on the dedicated company resource. items: $ref: '#/components/schemas/APITag' CustomFieldValue: nullable: true description: >- Custom field value. Text fields return strings, number fields return numbers, boolean fields return booleans, and date fields return `YYYY-MM-DD` strings. Null appears only when a value is explicitly cleared or absent in a write response. oneOf: - type: string - type: number - type: boolean Industry: type: object additionalProperties: false properties: name: type: string title: type: string industry_urn: type: string provider_industry_id: type: string hierarchy: type: string Location: type: object additionalProperties: false required: - is_primary - is_headquarter properties: linkedin_text: type: string display_text: type: string country_code: type: string region_code: type: string country: type: string country_full: type: string state: type: string city: type: string geographic_area: type: string is_primary: type: boolean is_headquarter: type: boolean APITag: type: object additionalProperties: false required: - name - color properties: name: type: string color: type: string enum: - green - orange - blue - red - purple - yellow - pink - grey responses: BadRequest: description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: Invalid request parameters Unauthorized: description: Missing, malformed, or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuthorization: value: code: unauthorized message: Authorization header is required invalidAuthorizationFormat: value: code: unauthorized message: Authorization header must use Bearer scheme invalidAPIKey: value: code: unauthorized message: Invalid API key Forbidden: description: >- API access is not enabled for the workspace, or the credential cannot access the requested workspace. content: application/json: schema: $ref: '#/components/schemas/Error' examples: forbidden: value: code: forbidden message: you don't have access to this organization featureUnavailable: value: code: billing_feature_not_available message: >- Feature 'TalkToHumansAPI' is not available in your current plan insufficientCredits: value: code: billing_insufficient_credits message: Insufficient credits NotFound: description: Requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found message: participant not found RateLimited: description: >- Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: Rate limit exceeded InternalServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error message: An internal error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: 'Pass your API key as `Authorization: Bearer `.' ````