Attachment Use Cases

Attachments are structured records that associate content — a file, a document, an image, or a text note — with a customer, organisation, or wallet. They are used for compliance evidence (PEP declarations, proof of address), operational notes, and any custom data that does not fit the core profile model.

Each attachment has:

• an attachmentType — a short string key identifying the purpose (e.g. PEP_TYPE_DECLARATION_STATUS, PROOF_OF_COMPLIANCE)
• a mediaType — the MIME type of the content (image/jpeg, application/pdf, text/plain, etc.)
• a base64EncodedAttachment — the binary content, base64-encoded
• an optional info field — a structured or free-text value validated by the attachment type config
• an optional fileName — the original file name, stored for reference

Adding an Attachment to a Customer

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/attachments
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "attachmentType": "PEP_TYPE_DECLARATION_STATUS",
  "mediaType": "text/plain",
  "base64EncodedAttachment": "Tm8=",
  "info": "NO",
  "fileName": "pep-declaration.txt"
}

Response (201 Created):

{
  "attachmentId": 8821043,
  "attachmentType": "PEP_TYPE_DECLARATION_STATUS",
  "mediaType": "text/plain",
  "base64EncodedAttachment": "Tm8=",
  "info": "NO",
  "fileName": "pep-declaration.txt",
  "created": "2026-05-19T10:15:00.000Z",
  "lastModified": "2026-05-19T10:15:00.000Z",
  "version": 1
}

The attachmentId is the permanent identifier for this attachment. Store it to retrieve, update, or delete it later.

Adding an Attachment to an Organisation

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/attachments
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "attachmentType": "PROOF_OF_COMPLIANCE",
  "mediaType": "application/pdf",
  "base64EncodedAttachment": "JVBERi0xLjQ...",
  "fileName": "compliance-certificate-2026.pdf"
}

Response (201 Created): Returns the attachment object with system-assigned attachmentId.

Adding an Attachment to a Wallet

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/attachments
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "attachmentType": "SUPPORTING_DOCUMENT",
  "mediaType": "image/jpeg",
  "base64EncodedAttachment": "/9j/4AAQSkZJRgAB...",
  "fileName": "receipt.jpg"
}

Retrieving Attachments

List all attachments on a customer

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/attachments
Authorization: Bearer {jwt}

Optional query parameters:

Response (200 OK):

[
  {
    "attachmentId": 8821043,
    "attachmentType": "PEP_TYPE_DECLARATION_STATUS",
    "mediaType": "text/plain",
    "info": "NO",
    "fileName": "pep-declaration.txt",
    "created": "2026-05-19T10:15:00.000Z"
  }
]

To avoid fetching binary content for list views, use fields=attachmentId,attachmentType,mediaType,fileName,created — this omits base64EncodedAttachment.

List all attachments on an organisation

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/attachments
Authorization: Bearer {jwt}

List all attachments on a wallet

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/attachments
Authorization: Bearer {jwt}

Get a single attachment

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/attachments/{attachmentId}
Authorization: Bearer {jwt}

Returns the full attachment including base64EncodedAttachment.

Updating an Attachment

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/attachments/{attachmentId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "attachmentId": 8821043,
  "attachmentType": "PEP_TYPE_DECLARATION_STATUS",
  "mediaType": "text/plain",
  "base64EncodedAttachment": "WWVz",
  "info": "YES",
  "fileName": "pep-declaration-updated.txt"
}

All fields are replaced. Include the full object, not just changed fields.

Deleting an Attachment

DELETE /eclipse-conductor/rest/v1/tenants/{tenantId}/attachments/{attachmentId}
Authorization: Bearer {jwt}

Response (204 No Content).

Supported Media Types

Validating Attachment Types and Values

Restricting which attachment types are accepted

Tenants can restrict which attachmentType values are accepted on customers and organisations. If a request uses a type outside the allowed list, it is rejected.

Configure allowed types via tenant config:

Validating the info field with regex

Once attachment types are restricted, the info field can also be validated against a regular expression per type. This is configured in the global property public.jwt.protected.attachment.type.config:

PEP_TYPE_DECLARATION_STATUS=^(YES|NO)$
PEP_TYPE=^(PEP|PIP|None)$
PEP_CATEGORY=\S+

Each line is ATTACHMENT_TYPE=regex. If the attachment type is listed and the info value does not match the regex, the create or update request is rejected immediately.

If info should accept any non-empty string, use \S+ as the regex.

Retrieving derived attachment types

To dynamically discover which attachment types are allowed for the current tenant (useful for building form dropdowns):

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/attachments/derived-attachment-types
Authorization: Bearer {jwt}

Response (200 OK):

{
  "customerAttachmentTypes": ["PEP_TYPE_DECLARATION_STATUS", "PEP_TYPE", "PEP_CATEGORY"],
  "organizationAttachmentTypes": ["PEP_TYPE_DECLARATION_STATUS", "PROOF_OF_COMPLIANCE"]
}

S3 Public Storage

For attachments that need to be publicly accessible (such as organisation logos or card art images), pass storageType: "public_s3" when creating an attachment on an organisation. Eclipse uploads the content to a public S3 bucket and stores the resulting URL in the info field.

Prerequisites: The tenant config key attachment.storage.publics3.bucket must be set to the target S3 bucket name.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/attachments
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "attachmentType": "PUBLIC_LOGO",
  "mediaType": "image/png",
  "base64EncodedAttachment": "iVBORw0KGgoAAAAN...",
  "fileName": "logo.png",
  "storageType": "public_s3"
}

The response info field contains a JSON object with the S3 URL: {"s3_logo": "https://bucket-name.s3-eu-west-1.amazonaws.com/uuid-logo.png"}.

Permissions Required