WatchEye
Browse endpoints
View as Markdown OpenAPI spec

Upload an attachment to an entity

POST /api/v1/entities/{entity_uuid}/attachments operationId: attachment.create

Base: https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/attachments

Upload a file and attach it to the specified entity, for example a trust deed, an ASIC extract, a signed declaration or a contract. The attachment inherits the entity's program and account, and is attributed to the calling API key.

Send the request as multipart/form-data with the file in the file field:

curl -X POST https://watcheye.globaldata.net.au/api/v1/entities/{entity_uuid}/attachments \
  -H "Authorization: Bearer {api_key}|{api_secret}" \
  -F "file=@Smith Family Trust Deed.pdf" \
  -F "category=Trust Deed" \
  -F "description=Signed copy received from the trustee"

Accepted files

Files can be up to 10 MB. The type is detected from the file contents, and these formats are accepted: PDF, images (JPEG, PNG, WEBP, GIF, HEIC), Word (DOC, DOCX), Excel (XLS, XLSX), CSV, plain text, RTF and email (EML, MSG). Any other type is rejected with 400.

Duplicates

The response includes a duplicates array listing every other attachment on the account with exactly the same contents (an empty array when there are none). The upload is accepted either way.

Attachments cannot be added to an archived entity; the request is rejected with 409. Unarchive the entity first to add an attachment.

Idempotency

This endpoint accepts the Idempotency-Key header so that retries on network failure are safe. A retry with the same key and the same file returns the original response; the same key sent with a different file is rejected with 422. See the Idempotency section of the API guide for the full contract.

Path parameters

FieldDescription
entity_uuidrequired string (uuid)

The entity UUID

Header parameters

FieldDescription
Idempotency-Key string [max 255 characters]

Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the Idempotent-Replay: true response header.

Honoured on POST requests only. See the Idempotency section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The file and its details

Responses

201

Attachment uploaded

application/json
FieldDescription
data object

An attachment: a file attached to an entity, such as a trust deed, an ASIC extract, a signed declaration or a contract. The contents are stored encrypted and are returned by the download endpoint.

Deleting an attachment is a soft-delete: subsequent show or list calls for it return 404. Attachments on an archived entity are archived with it and cannot be changed or deleted.
data.uuid string (uuid)

The attachment's UUID

Example: 3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
data.attachment_number string

A short public identifier for the attachment, shown in the portal

Example: EA-3C-9A1-0B7
data.entity_uuid string (uuid)

UUID of the entity the attachment is on
data.program_uuid string (uuid)

UUID of the program the entity belongs to
data.filename string

The name of the file as uploaded

Example: Smith Family Trust Deed.pdf
data.category string

What the file is. Any text up to 100 characters; Other when none is given. A category that matches an existing one on the account (ignoring case and extra spaces) is stored with the existing spelling, so trust deed is stored as Trust Deed. The categories offered in the portal are: Trust Deed, Company Constitution, Partnership Agreement, ASIC Extract, Companies House Extract, Identity Document, Proof of Address, Statutory Declaration, Declaration, Contract / Agreement, Correspondence, Financial Statement and Other.

Example: Trust Deed
data.description string or null

An optional description of the file (max 2000 characters)

Example: Signed copy received from the trustee
data.mime_type string

The type of the file, detected from its contents

Example: application/pdf
data.format string

A readable name for the type of file

Enum: PDF, Image, Word, Excel, CSV, Text, RTF, Email, Other

Example: PDF
data.size_bytes integer

The size of the file in bytes

Example: 248113
data.sha256 string

SHA-256 hash of the file contents, as lowercase hex. Files with the same hash have identical contents.

Example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
data.created_by object or null

Identifies who uploaded the file. The type discriminator picks the shape of the remaining fields:

  • { type: "user", uuid, username } - a portal user uploaded the file.
  • { type: "api_key", uuid, label } - an API key on this account uploaded the file.
  • null - the user or API key that uploaded the file is no longer available.
data.created_by.type string

Discriminator for the actor type.

Enum: user, api_key
data.created_by.uuid string (uuid)

UUID of the user or API key that uploaded the file.
data.created_by.username string

Username of the portal user. Present only when type is user.
data.created_by.label string

Label of the API key. Present only when type is api_key.
data.archived_at string (date-time) or null

ISO 8601 timestamp at which the attachment was archived with its entity (null if not archived)
data.created_at string (date-time)

Example: 2025-01-01T00:00:00Z
data.updated_at string (date-time)

Example: 2025-01-01T00:00:00Z
duplicates array of objects

Other attachments on this account with exactly the same contents
duplicates[].attachment_uuid string (uuid)

UUID of the matching attachment
duplicates[].attachment_number string

Public identifier of the matching attachment

Example: EA-7D-21B-4C0
duplicates[].entity_uuid string (uuid)

UUID of the entity the matching attachment is on
api_reference string (uuid)
409

Conflict - either the entity is archived, or a request with this Idempotency-Key is currently being processed

application/json
FieldDescription
message string

Example: Attachments cannot be added to an archived entity
422

Idempotency-Key was reused with a different request body

application/json
FieldDescription
message string

Example: Idempotency-Key was reused with a different request body.
Standard error responses: 400 401 403 404 429 5XX See common error responses
Previous List the attachments on an entity Next Show an attachment