# Postbox

The Postbox serves as a communication channel between Solaris and its customers for banking documents.

As a bank, Solaris must regularly provide certain documentation to its customers. With Postbox, Solaris uploads this documentation to a central repository, which you then provide to your customers via your frontend using the Solaris Postbox API.

This guide describes how to implement this feature in your solution.

## Types of documents

Currently, Solaris provides the following types of documents via Postbox:

* **Balance confirmations**
* **Fee summary statements** (Currently only for Spain). Fee summary statements can also be requested. See [Fee summary statements](/api-reference/digital-banking/account-management#tag/Fee-summary-statements) for details.


## How to implement Postbox

Ensure that your Postbox implementation supports **all** types of Postbox documents.

The process for retrieving Solaris documents and providing them to customers is as follows:

1. Solaris produces a new document and uploads it to the Postbox as an **item**.
2. Solaris notifies partners of the new **item** (and provides the `item_id`) using the [POSTBOX_ITEM_CREATED webhook](#postbox_item_created).
3. Call the `GET Index Postbox items` endpoint to retrieve all Postbox items. You can filter the response based on which items to show to the customers (e.g., by document type).
  * [Endpoint for persons](/api-reference/onboarding/compliance#operation/solaris_postbox_person_items_all)
  * [Endpoint for businesses](/api-reference/onboarding/compliance#operation/solaris_postbox_business_items_all)
4. Call the [GET Retrieve a Postbox item](/api-reference/onboarding/compliance#operation/solaris_postbox_items_find) endpoint to retrieve the metadata around a specific item to display to a single customer.
5. Call the [GET Download document](/api-reference/onboarding/compliance#operation/solaris_postbox_item_document_find) endpoint to download the actual document contained in the item.
6. Display the downloaded PDF document to the customer.
7. If the document requires a **confirmation** (specified in the `customer_confirmation` property), your solution must collect the customer's confirmation and send it to Solaris using the [POST Create confirmation](/api-reference/onboarding/compliance#operation/solaris_postbox_item_confirmations_create) endpoint.


## Diagram: Postbox overview

![Postbox overview](/assets/postbox-overview.fb8bc57a28ca47b0802dbc4cbb92e162cea1a56703bb4255ed43d903133cfae6.71dde5d8.png)

## Postbox entities

### Postbox items

An **item** represents a document that Solaris created for the customer, along with its associated metadata. An item can belong to **either** a `Person` **or** a `Business`.

Each item has an associated **document**. The document is stored as a binary and must be retrieved using the [GET Download document](/api-reference/onboarding/compliance#operation/solaris_postbox_item_document_find) endpoint.

Items may include two properties that require additional action from your solution:

* `customer_notification`: If `true`, this item has a higher priority, and customers should receive a notification to read it from your solution.
* `customer_confirmation`: If `true`, you must collect the customer's confirmation for this item and send it to Solaris using the [POST Create confirmation](/api-reference/onboarding/compliance#operation/solaris_postbox_item_confirmations_create) method.


### Confirmations

A **confirmation** represents an instance when the customer acknowledges that they have read (and accepted) the contents of an item.

Solaris only requires confirmations for specific types of documents, not for all documents.

## Webhooks

### POSTBOX_ITEM_CREATED

Subscribe to the `POSTBOX_ITEM_CREATED` webhook to receive notifications whenever Solaris publishes a new Postbox item.

**Example payload:**


```json
{
  "id": "d347d967ae8c4d58b93e6698b386cae9pbxi",
  "belongs_to": "3e0b990bb0f49eb1a43904e78461c0cbcper",
  "owner_type": "Person",
  "created_at": "2022-01-04T13:45:05Z",
  "document_date": "2021-06-30",
  "document_type": "BALANCE_CONFIRMATION",
  "name": "Item's name",
  "description": "Description",
  "customer_notification": true,
  "customer_confirmation": false,
  "document_size": 1667317,
  "document_content_type": "application/pdf"
}
```

## Postbox API endpoints

You must implement the following API endpoints to use the Postbox feature:

* `GET Index Postbox items`
  * [For a person](/api-reference/onboarding/compliance#operation/solaris_postbox_person_items_all)
  * [For a business](/api-reference/onboarding/compliance#operation/solaris_postbox_business_items_all)
* [GET Retrieve a Postbox item](/api-reference/onboarding/compliance#operation/solaris_postbox_items_find)
* [GET Download Postbox item document](/api-reference/onboarding/compliance#operation/solaris_postbox_item_document_find)


## Postbox testing

Solaris offers the following endpoints for testing the Postbox feature:

### POST Create a Postbox item for a person

Creates a Postbox item for the person specified in the request URL. Note that you can only use this endpoint for testing purposes on the testing, staging, and sandbox environments.

[View full API reference](/api-reference/onboarding/compliance#operation/solaris_postbox_person_items_emulation_create)

### POST Create a Postbox item for a business

Creates a Postbox item for the business specified in the request URL. Note that you can only use this endpoint for testing purposes on the testing, staging, and sandbox environments.

[View full API reference](/api-reference/onboarding/compliance#operation/solaris_postbox_business_items_emulation_create)

### POST Generate Postbox PDF document

Generates an empty PDF document on Solaris' servers for use as a Postbox item. Note the following:

* The `Content-Type` header for this request must be `application/json`.
* This endpoint can only be used on the testing, staging, and sandbox environments.


[View full API reference](/api-reference/onboarding/compliance#operation/solaris_postbox_documents_emulation_create)