Set a legal entity's image · Ownrecord docs

Uploads a legal entity's image, shown wherever its initials show today: the entity switcher and the entity's pages. Send the image base64-encoded in content: a square PNG, JPEG or WebP image of at most 512 KB and 1024 × 1024 pixels. The type is read from the bytes; SVG and GIF are refused.

The image is private: it is served at its avatar.url only to the organization's members and Ownrecord staff. Uploading the same image again changes nothing. Needs entities:write (organization owners and admins). Dry-run it to check an image without storing it.

At a glance

REST: PUT /api/v1/entities/{id}/avatar
MCP tool: entities_avatar_set
Operation ID: entities.avatar.set
Scope: Organization, or one of its legal entities or brands
Permission: entities:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the entities:write scope
Since: M13

Request

Path parameters

Field	Type	Description
`id`	`ent_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`content`	string	Yes	The image's bytes, base64-encoded: a square PNG, JPEG or WebP image of at most 512 KB and 1024 × 1024 pixels (256 × 256 is what the console uploads).

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`ent_…` ID
`object`	`"legal_entity"`
`orgId`	`org_…` ID
`slug`	string
`legalName`	string
`tradingName`	string or null
`avatar`	object or null
`establishment`	object
`establishment.country`	string
`establishment.subdivision`	string or null
`establishment.address`	object
`establishment.address.line1`	string
`establishment.address.line2`	string or null
`establishment.address.city`	string
`establishment.address.postalCode`	string or null
`establishment.address.region`	string or null
`establishment.address.country`	string
`establishment.companyRegistryId`	string
`establishment.euVatEstablished`	boolean
`homeTaxId`	object
`homeTaxId.type`	string
`homeTaxId.value`	string
`verification`	object
`verification.status`	one of `unverified`, `pending_review`, `verified`, `rejected`
`verification.method`	one of `vies`, `hmrc`, `ch_uid`, `document`
`verification.checkedAt`	date-time or null
`defaultCurrency`	string
`timezone`	string
`invoiceSettings`	object
`invoiceSettings.numberFormat`	string
`invoiceSettings.sequenceResetYearly`	boolean
`invoiceSettings.language`	string
`invoiceSettings.bilingual`	string or null
`invoiceSettings.footerText`	string or null
`invoiceSettings.bankTransfer`	object or null
`status`	one of `onboarding`, `active`, `suspended`, `archived`
`createdAt`	date-time
`updatedAt`	date-time

Examples

Upload the entity's image

HTTP

PUT /api/v1/entities/ent_01m4tx5nj8emwbyf7y9vcf47x2/avatar
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}

Response (200):

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "object": "legal_entity",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "slug": "acme-hr",
  "legalName": "Acme Digital d.o.o.",
  "tradingName": null,
  "avatar": {
    "fileId": "file_01m4tx5nj8emwbyf7y9vcf47yc",
    "url": "/media/file_01m4tx5nj8emwbyf7y9vcf47yc/63ef318d96b5d0d0ceba6e04a4e622b1158335cdc67c49e27839132c6f655058.png"
  },
  "establishment": {
    "country": "HR",
    "subdivision": null,
    "address": {
      "line1": "Ilica 1",
      "line2": null,
      "city": "Zagreb",
      "postalCode": "10000",
      "region": null,
      "country": "HR"
    },
    "companyRegistryId": "080000000",
    "euVatEstablished": true
  },
  "homeTaxId": {
    "type": "eu_vat",
    "value": "HR12345678901"
  },
  "verification": {
    "status": "unverified",
    "method": "vies",
    "checkedAt": null
  },
  "defaultCurrency": "EUR",
  "timezone": "Europe/Zagreb",
  "invoiceSettings": {
    "numberFormat": "{series}-{year}-{seq:06}",
    "sequenceResetYearly": true,
    "language": "en",
    "bilingual": null,
    "footerText": null,
    "bankTransfer": null
  },
  "status": "onboarding",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`content` isn't base64, or is far larger than an image may be (`param` names the field).	Fix the fields listed in `details.issues` and send the request again.
`image_type_unsupported`	400	The file isn't a still PNG, JPEG or WebP image (read from its bytes): SVG, GIF and animations are refused.	Export the image as PNG, JPEG or WebP (a still image, not an animation) and upload it again. The type is read from the file's bytes, not from its name.
`image_too_large`	400	The image is larger than 512 KB.	Resize or compress the image to at most 512 KB. Avatars and icons are shown at 256 × 256 pixels and logos within 600 × 200, so a small file loses nothing.
`image_dimensions`	400	The image is wider or taller than 1024 pixels, or not square (avatars and icons), or a logo outside 1:1 to 4:1.	Use a square image of at most 1024 × 1024 pixels for avatars and icons, and a logo between square and four times as wide as it is tall, at most 1024 pixels a side.
`upstream_timeout`	502	The file store didn't answer in time; nothing was recorded. Retry.	Retry the request with the same Idempotency-Key after a short wait.
`resource_not_found`	404	No entity with this ID is visible to the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The entity changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change legal entities here.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Upload the entity's image#

Errors#