---
# System prepended metadata

title: S3 API Specification

---

# S3 API Specification

*Bare-bones endpoint map for the S3 service*

This document should describe _which_ endpoints are available on the S3 service, as well as details around use-cases and necessary access permissions. It _should not_ worry about defining the input and return types of the endpoints, as those are defined in the `data-model-specification` package.

**Note: All endpoints transact in [JSON:API](https://jsonapi.org/format).**

## Endpoints

### `GET /:securityId/transactions`

* **Permissions:** Only accessible to OAuth users associated with the Issuer of the given security and having the `s3.view-dashboard-info` permission.

### `GET /:securityId/shareholders`

* **Return Data** `S3.Api.Shareholder[]` (JSON:API body)
* **Permissions:** Only accessible to OAuth users associated with the Issuer of the given security and having the `s3.view-dashboard-info` permission.

### `GET /:securityId/dashboard-info`

**Not yet implemented**

This endpoint is used by issuers to get data about the security, including shareholder counts (US, non-US and Total), bids/asks, spread, activity, etc....

* **Permissions:** Only accessible to OAuth users associated with the Issuer of the given security and having the `s3.view-dashboard-info` permission.

### `GET /:securityId/shareholder-counts`

This endpoint is used to get current shareholder counts, optionally filtered by country using the `filter` parameter.

* **Query Parameters:**
    * `filter` - Should be formatted for the [`dsl-queries`](https://www.npmjs.com/package/@openfinance/dsl-queries) library. May contain `country =|in|!= [country or set]`. The special value `non-us` will yield an array of length 1 where the result is an `S3.Api.ShareholderCount` object representing all non-US countries.
* **Return Data:** `Array<S3.Api.ShareholderCount>`
* **Permissions:** Accessible to any authenticated API Key with `s3.view-shareholder-counts` permissions.

### `POST /transfers`

A 'transfer' in S3 land is any discrete movement of a quantity of assets from one wallet to another. This can be one of three types of transfer:

1. A wallet-to-wallet transfer where a given entity moves tokens between two of their own wallets;
2. A distribution transfer, where an issuer distribute tokens to an investor; or
3. An investor-to-investor trade executed by an exchange.

This endpoint is used by issuers and exchanges to initiate the latter two types of transfer.

#### Endpoint Characteristics

* **Query Parameters:** (none)
* **Input Data:** `S3.Api.Transfer` (JSON:API body)
* **Return Data:** `S3.Api.Transfer` (JSON:API body)
* **Permissions:** Only accessible to authenticated API Keys with `s3.execute-transfer` permission.

### `GET /transfer-obstructions/:resolutionCode`

**Not yet implemented**

This allows someone to take a resolution code from an S3 transfer and get a meaningful list of human-readable obstructions for it.
