# Postbox API

The Postbox is designed to serve 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 can upload all of this documentation to a
central repository, and then you can provide it to your customers through your
frontend using the Solaris Postbox API.

This document describes how to implement this feature in your solution using the
Postbox API.

## 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 this [section](/api-reference/digital-banking/account-management/#tag/Fee-summary-statements) for more details.


## How to implement Postbox

Please ensure that your Postbox implementation supports **all** types of Postbox documents.

Here is the process for retrieving Solaris documents and providing them to the customers:

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 be displayed 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 then 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 has created for the customers
and 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 would require additional action from your solution:

- `customer_notification`: If `true`, then this item has a higher priority and
customers should receive a notification to read it from your solution.
- `customer_confirmation`: If `true`, then 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 will only require 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 in order 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.

[Click here to view the 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.

[Click here to view the 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. Please 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.


[Click here to view the full API reference.](/api-reference/onboarding/compliance/#operation/solaris_postbox_documents_emulation_create)