openapi: 3.0.0 info: title: Bitbond Offering Manager API documentation description: | The Bitbond Offering Manager API provides resource endpoints for fetching projects, creating orders and payments and collecting KYC information about the investors. The API requires a token based authentication. A bearer token will be provided by Bitbond that will need to be included in the 'Authentication' header for each request to the server, along with an HMAC 'X-Signature' header. The HMAC signature will be used to verify the authenticity of the sender and the integrity of the request in transit. ## Authorization API clients are authorized with bearer tokens. Tokens can be generated in the admin panel as a key/secret pair. Secret are used to build HMAC-SHA1 signatures on a client side. **Signature generation pseudo code** ``` /** * HMAC a hashing function using SHA1 algorythm * @param {String} secret The secret used to hash the message * @param {String} message Message to be hashed * @return {Bin} Binary digest */ HMAC = func(secret, message) /** * signatureKey returns derived key * @param {String} secret The secret from tokens key/secret pair. * @param {String} date UTC request date in YYYY-MM-DD format * @param {String} method Request method POST, GET, DELETE etc * @param {String} path Request path, e.g. /api/v1/access_tokens * @return {Bin} Derived key used to generate payload signature */ signatureKey = func(secret, date, method, path) { HMAC(HMAC(HMAC("bitbond" + secret, date), method), path) } /** * signature returns request signature * @param {String} key The secret from tokens key/secret pair. * @param {String} payload Raw request body * @return {String} Request signature */ signature = func(key, payload) { HMAC(key, payload).toString() } ``` **Example in JavaScript** ``` import hmacSHA1 from 'crypto-js/hmac-sha1'; let generateSigningKey = (secret, dateStamp, method, path) => { let key = hmacSHA1(dateStamp, `bitbond${secret}`) key = hmac(method, key) key = hmac(path, key) return key } let dateStamp = (new Date()).toISOString().substring(0, 10) let method = request.method let path = request.url.getPathWithQuery() let body = request.body && request.body.raw || '' let signingKey = generateSigningKey(secret, dateStamp, method, path) let signature = hmacSHA1(body, signingKey).toString() ``` ### Headers To authorize API access this header needs to be added to the request. ``` Authorization: Bearer [token] X-Signature: [signature] ``` **Creating orders** ### To create an order the following necessities need to be met: - The current user needs to be approved. A user is approved automatically when they go through a successful video identification session. When a user is approved the approved_at is set to a non-null value and the approved attribute is set to true. - An order can only be created for a live project. A live project has its start_date before now and its end_date after. - The investment terms need to be accepted by a user for the project they want to invest into. The investment terms are accepted by user for a project by successfully creating terms through the investment_terms endpoint. - The order amount must be greater than the project minimum required investment amount. **Creating users** The **locale** attribute takes **en** or **de** as values, with **en** being set by default when no value is specified. When an order is created it will have status **new** and a unique order code will be generated. The order code will be used as a reference code when sending payments. Once a new payment is created, the details of the payment are analysed and the order status changes accordingly to **paid**, if the amount sent matches the order, **underpaid**, if the amount sent is lower than the order and **overpaid** if the amount sent is larger than the order. An order can also have status **cancelled**, either by admin action or by user action. When an order distribution on the blockchain is initiated the order status changes to **settled**. ### Creating identities An identity contains personal data about a user. Identities are of many types ranging from individuals, legal representatives, and business owners. They share common attributes described in the Identity model. Generally an individual investor will have one identity that collects information regarding contact details, citizenship and taxes. A business investor will hold one legal representative, that will need to be kyc-ed via video identification, and multiple business owners. ### VIDEO IDENTIFICATION FLOW The video identification process is handled through IDnow, as the video identification provider. There are a few requirements to be able to start a video identification process: - an identity needs to be created with contact data and financial information ``` POST /users/{user_id}/identities ``` - an address needs to be added for the identity ``` POST /users/{user_id}/identities/{identity_id}/addresses ``` - the bank account details need to be filled in for the user ``` POST /users/{user_id}/bank_accounts ``` - the identity terms need to be create for the identity ``` POST /users/{user_id}/identities/{identity_id}/identity_terms ``` If a video identification session is attempted without the above requirements to be met, an error will be thrown. There are two steps to perform a video identification session: - Initiate the session by making a POST request to the ``` /kyc/identities/{identity_id}/video_identifications ``` endpoint - Make a GET request to the ``` /kyc/identities/{identity_id}/video_identifications/{id} ``` endpoint to verify the video_identifications object has the idnow_id and the redirect_url attributes filled in. A polling mechanism might be needed to fetch the latest data. When the redirect_url attribute is present, the user can be redirected to their video provider (IDnow) session. Once the user goes through the video identification session, a webhook is triggered to synchronize data from the video provider (IDnow) to Bitbond. In order to check the status of the video session make a GET request to the /kyc/identities/{identity_id}/video_identifications/{id} endpoints to verify the object has the status attribute filled in. The video_identifications object can be accessed through the /identities/{id} endpoint as well. **IMPORTANT NOTE**: On staging, the video identification provider (IDnow) does not automatically trigger the webhook to synchronize data on Bitbond's side, therefore the video_identification object status attribute will never be updated. At the moment, upon going through the video identification session, the user is not redirected back into the investor application. This feature is work in progress. ## Webhooks Webhook URLs can be added through Admin frontend application. API will automatically retry a webhook if the response status code will be anything other than `200`. Webhooks are called with payload in POST request body when the following events happen: - `distribution_created` - Is triggered when distribution to Blockchain was processed. - `kyc_approved` - Is triggered after successfull auto-approval process when investor finishes the KYC process. - `kyc_rejected` - Is triggered when admin user rejects the investor in Asset Manager - `kyc_video_identification_success` - Is triggered after the investor goes through a successful IDNOW KYC process. - Is tiggered when KYC process is mocked using Asset Manager `Labs` section (does not apply to production) - `order_created` - Is triggered when the endpoint `POST /users/:user_id/projects/:project_id/orders` is used and after a new order is successfully created. - `order_status_changed` - Is triggered when status of an order is updated manually - Is triggered when payment is created and order status is changed - `project_prepared_for_distribution` - Is triggered when project has done a preparation for distribution cycle. - `transaction_created` (WIP) ### Webhook payloads - `distribution_created` ``` { event: 'distribution_created', order_id: {String} UUID, user_id: {String} UUID, project_id: {String} UUID, } ``` - `kyc_approved` ``` { event: 'kyc_approved', user_id: {String} UUID } ``` - `kyc_rejected` ``` { event: 'kyc_rejected', user_id: {String} UUID } ``` - `kyc_video_identification_success` ``` { event: 'kyc_video_identification_success', user_id: {String} UUID } ``` - `order_created` ``` { event: 'order_created', order_id: {String} UUID, user_id: {String} UUID, project_id: {String} UUID, } ``` - `order_status_changed` ``` { event: 'order_status_changed', order_id: {String} UUID, user_id: {String} UUID, project_id: {String} UUID, status: {String}, } ``` - `project_prepared_for_distribution` ``` { event: 'project_prepared_for_distribution', project_id: {String} UUID, code: {String}, percentage: {Number} } ``` - `transaction_created` (WIP) ``` { event: 'transaction_created', transaction_id: {String} UUID, custody_account_holder_id: {String} UUID, custody_account_id: {String} UUID, user_id: {String} UUID } ``` version: 1.3.4 servers: - url: https://client-subdomain.bitbond.net/api/v1 description: Every client gets their unique subdomain used for endpoint calls. tags: - name: addresses - name: bank_accounts - name: businesses - name: business_owners - name: config - name: custody description: Custody endpoints describe how to create and access custody account holders, custody accounts and transactions. Custody assets are the starting point, each user can only have one custody account per asset. Assets are created by Bitbond at the request of the custody partner. Once an asset has been created a list of all the partner's assets can be fetched with the `/custody_assets` endpoint. To create a custody account for a user you will need the asset ID you wish to create the account for. Once the user has a custody account it is possible to fetch their transactions and create new transactions for the relevant asset. - name: files - name: identities - name: identity_documents - name: identity_terms - name: kyc - name: kyc_verification - name: legal_representatives - name: orders - name: pep_status - name: projects - name: surveys - name: users paths: /projects/{project_id}/payouts: get: description: Returns the payouts list tags: - payouts parameters: - $ref: '#/components/parameters/ProjectIdParam' responses: '200': description: Project payouts list content: application/json: schema: type: array items: $ref: '#/components/schemas/Payout' /projects/{project_id}/payouts/{id}: get: description: Fetch a project payouts's details based on the id. tags: - payouts parameters: - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The payout with the id content: application/json: schema: $ref: '#/components/schemas/Payout' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects: get: description: Returns the projects list tags: - projects responses: '200': description: Projects list content: application/json: schema: type: array items: $ref: '#/components/schemas/Project' post: description: Create a project tags: - projects requestBody: description: The project information. required: true content: application/json: schema: $ref: '#/components/schemas/ProjectForm' responses: '201': description: Project created and returned content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /projects/{id}: get: description: Fetch a project's details based on the id. tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The project with the id content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: description: Update the project information based on id tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: The project information required: true content: application/json: schema: $ref: '#/components/schemas/ProjectForm' responses: '201': description: Project updated and returned content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' delete: description: Delete the project. tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Project deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /projects/by_code/{code}: get: description: Fetch a project's details based on the project code. tags: - projects parameters: - $ref: '#/components/parameters/ProjectCodeParam' responses: '200': description: The project with the code content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects/{id}/distribution_list: get: description: Fetch a project's distribution list as a `text/csv; charset=utf-8` response. tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The project's distribution list CSV content: text/csv: schema: example: | address,amount 0x4e399cfcb61e59e5dbae3bfcda9c36f700012d7f,42 0xc418353e4526d2a1df4176036c6e0b1a9a0e5aae,21 type: string '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects/{project_id}/prepare_for_distribution: post: description: Start a background process that prepares the project for distribution. tags: - projects parameters: - $ref: '#/components/parameters/ProjectIdParam' responses: '200': description: The project's details content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects/{id}/prepare_for_distribution_status: get: description: Fetch a project's prepare for distribution status based on the id. tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The project's prepare for distribution status code and percentage. content: application/json: schema: $ref: '#/components/schemas/ProjectPrepareForDistributionStatus' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects/{id}/stats: get: description: Fetch a project's statistical information based on the id. tags: - projects parameters: - $ref: '#/components/parameters/ResourceIdParam' - in: query name: status schema: type: string required: false description: 'Filter project orders by status. Values: open, paid, settled, cancelled' responses: '200': description: The project with the id content: application/json: schema: $ref: '#/components/schemas/ProjectStats' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /projects/{project_id}/snapshots: get: description: Fetch a project's snapshots. tags: - snapshots parameters: - $ref: '#/components/parameters/ProjectIdParam' responses: '200': description: Snapshots list content: application/json: schema: type: array items: $ref: '#/components/schemas/Snapshot' /projects/{project_id}/snapshots/{id}: get: description: Fetch a project snapshot details based on the id. tags: - snapshots parameters: - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The Snapshot with the id content: application/json: schema: $ref: '#/components/schemas/Snapshot' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /payouts/{payout_id}/user_payouts: get: description: Fetch all User Payouts for given Payout. tags: - user_payouts parameters: - $ref: '#/components/parameters/PayoutIdParam' responses: '200': description: User Payouts list content: application/json: schema: type: array items: $ref: '#/components/schemas/UserPayout' /payouts/{payout_id}/user_payouts/{id}: get: description: Fetch a User Payout details based on the id. tags: - user_payouts parameters: - $ref: '#/components/parameters/PayoutIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The User Payout with the id content: application/json: schema: $ref: '#/components/schemas/UserPayout' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /config: get: description: Fetch the configuration data, like timezone and supported countries for the current user. tags: - config responses: '200': description: The configuration data for the current user content: application/json: schema: type: array items: $ref: '#/components/schemas/Config' /custody_assets: get: description: Assets tags: - custody responses: '200': description: Returns list of assets content: application/json: schema: type: array items: $ref: '#/components/schemas/CustodyAsset' /orders: get: description: Returns the orders list with a certain status received after a timestamp tags: - orders parameters: - $ref: '#/components/parameters/StatusParam' - $ref: '#/components/parameters/UpdatedAtParam' responses: '200': description: Orders list content: application/json: schema: type: array items: $ref: '#/components/schemas/Order' /payments: get: description: Returns payments for specific project or specific user (depend's on provided param id) tags: - payments parameters: - in: query name: project_id schema: type: string required: false description: 'Project ID' - in: query name: user_id schema: type: string required: false description: 'User ID' responses: '200': description: Payments content: application/json: schema: type: array items: $ref: '#/components/schemas/Payment' '404': $ref: '#/components/responses/NotFound' /users: post: description: Create a user. The 'locale' attribute takes 'en' or 'de' as values, with 'en' being set by default when no value is specified. tags: - users requestBody: description: The current user information. The 'locale' attribute takes 'en' or 'de' as values, with 'en' being set by default when no value is specified. required: true content: application/json: schema: $ref: '#/components/schemas/UserForm' responses: '201': description: Current user created and returned content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' get: description: Returns the user information based on the email address tags: - users parameters: - $ref: '#/components/parameters/EmailParam' responses: '200': description: User information content: application/json: schema: $ref: '#/components/schemas/User' /users/{id}/destroy_payments: delete: description: Delete all user's payments. tags: - users parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Payments deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/projects/{project_id}/by_order_status/{status}: get: description: Returns the users that have orders with a certain status in a project tags: - users parameters: - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/OrderStatusParam' responses: '200': description: Users that have orders with a certain status in a project content: application/json: schema: type: array items: $ref: '#/components/schemas/User' /users/{id}: get: description: Fetch the current user information. tags: - users parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The current user information content: application/json: schema: $ref: '#/components/schemas/User' put: description: Update the current user information tags: - users parameters: - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: The current user information required: true content: application/json: schema: $ref: '#/components/schemas/UserForm' responses: '201': description: The current user updated and returned content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' delete: description: Delete a user based on id. tags: - users parameters: - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: User deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/projects: get: description: Fetch the list of projects the current user has payments or orders in. tags: - users parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The projects list of the current user content: application/json: schema: type: array items: $ref: '#/components/schemas/Project' /users/{user_id}/projects/{project_id}/orders: get: description: Fetch the orders list of a project for the current user. tags: - orders parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - in: query name: status schema: type: string required: false description: 'Filter orders by status. Values: open, paid, settled, cancelled' - in: query name: distributable schema: type: boolean required: false description: Filter orders ready to be distributable - in: query name: updated_at schema: type: string required: false description: Filter orders that has been updated from a specific date - in: query name: order_code schema: type: string required: false description: Filter orders by its `order_code` responses: '200': description: The orders list of the project content: application/json: schema: type: array items: $ref: '#/components/schemas/Order' post: description: Create an order for a project for the current user. In order to create an order the current user needs to be approved and the investment terms accepted. An order can only be created for a live project. A live project has its start_date before now and its end_date after. A user is approved automatically when they go through a successful video identification session. When a user is approved the approved_at is set to a non-null value and the approved attribute is set to true. The investment terms are accepted by user for a project by successfully creating terms through the investment_terms endpoint. The order amount must be greater than the project minimum required investment amount. tags: - orders parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' requestBody: description: Order information required: true content: application/json: schema: $ref: '#/components/schemas/OrderForm' responses: '201': description: Order created and returned content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: 'Server cannot or will not process the request if user is not approved' '401': $ref: '#/components/responses/Unauthorized' '405': description: 'Method not allowd if project is not on sale or if the volume limit was reached' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/projects/{project_id}/orders/{id}: get: description: Fetch an order's details. tags: - orders parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The orders details content: application/json: schema: $ref: '#/components/schemas/Order' '404': $ref: '#/components/responses/NotFound' /users/{user_id}/projects/{project_id}/orders/{id}/cancel: post: description: Cancel an order for a project. tags: - orders parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '201': description: Order updated and returned content: application/json: schema: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /users/{user_id}/projects/{project_id}/orders/{order_id}/payments: get: description: Fetch the payments list of a order for the current user and project. tags: - payments parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/OrderIdParam' responses: '200': description: The payments list of the order content: application/json: schema: type: array items: $ref: '#/components/schemas/Payment' post: description: Create an payment for an order. Depending of the payment `amount`, Order status will be updated to one of following type - `paid`, `underpaid` or `overpaid`. tags: - payments parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' requestBody: description: Payment information required: true content: application/json: schema: $ref: '#/components/schemas/PaymentForm' responses: '201': description: Payment created and returned content: application/json: schema: $ref: '#/components/schemas/Payment' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/projects/{project_id}/orders/{order_id}/payments/{id}: get: description: Fetch the payments details of an order for the user and project. tags: - payments parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/OrderIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The payment details content: application/json: schema: $ref: '#/components/schemas/Payment' delete: description: Delete the payment of an order for the user and project. The order status will be recalculated and if it changes the corresponding webhook will be triggered. tags: - payments parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' - $ref: '#/components/parameters/OrderIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The deleted payment details content: application/json: schema: $ref: '#/components/schemas/Payment' /users/{user_id}/projects/{project_id}/investment_terms: get: description: Fetch the investment terms of a project for the current user. tags: - investment_terms parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' responses: '200': description: The investment terms list of the project content: application/json: schema: type: array items: $ref: '#/components/schemas/InvestmentTerm' post: description: Create investment terms for a project for the current user. tags: - investment_terms parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ProjectIdParam' requestBody: description: Investment term information required: true content: application/json: schema: $ref: '#/components/schemas/InvestmentTermForm' responses: '201': description: InvestmentTerm created and returned content: application/json: schema: $ref: '#/components/schemas/InvestmentTerm' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/custody_account_holders: get: description: User account holders tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: List of custody account holders content: application/json: schema: type: array items: $ref: '#/components/schemas/CustodyAccountHolder' post: description: User account holder tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' responses: '201': description: Custody account holder created content: application/json: schema: $ref: '#/components/schemas/CustodyAccountHolder' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /users/{user_id}/custody_account_holders/{id}: get: description: User account holder tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Returns a custody account holder record. content: application/json: schema: $ref: '#/components/schemas/CustodyAccountHolder' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts: get: description: User accounts tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' responses: '200': description: List of custody accounts content: application/json: schema: type: array items: $ref: '#/components/schemas/CustodyAccount' post: description: User account tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' requestBody: description: Custody asset information required: true content: application/json: schema: $ref: '#/components/schemas/CustodyAccountForm' responses: '201': description: Custody account created content: application/json: schema: $ref: '#/components/schemas/CustodyAccount' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}: get: description: User account tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Returns a custody account record. content: application/json: schema: $ref: '#/components/schemas/CustodyAccount' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}/balance: get: description: Account balance tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Returns a custody account balance. content: application/json: schema: $ref: '#/components/schemas/CustodyBalance' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions: get: description: Account transactions tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/CustodyAccountIdParam' - in: query name: limit required: true description: Number of transactions to return. schema: type: number - in: query name: order description: Order of transactions by timestamp (asc or desc). schema: type: string - in: query name: offset description: Offset by which to fetch transactions from. schema: type: string - in: query name: cursor description: Transaction cursor to start fetching from. schema: type: number responses: '200': description: Returns a list of account transactions. content: application/json: schema: type: array items: $ref: '#/components/schemas/CustodyTransaction' post: description: Transaction. The idem_key attribute needs to be unique to guard against double submissions. tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/CustodyAccountIdParam' requestBody: description: Withdrawal transaction information required: true content: application/json: schema: $ref: '#/components/schemas/CustodyTransactionForm' responses: '201': description: Returns new transaction record. content: application/json: schema: $ref: '#/components/schemas/CustodyTransaction' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/{id}: get: description: Account transaction with specific ID tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/CustodyAccountIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Returns a signle account transaction. content: application/json: schema: $ref: '#/components/schemas/CustodyTransaction' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/withdrawable_balance: get: description: Withdrawable balance tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/CustodyAccountIdParam' responses: '200': description: Returns the withdrawable balance. content: application/json: schema: type: number /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/estimated_fee: get: description: Estimated fee tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' - $ref: '#/components/parameters/CustodyAccountIdParam' responses: '200': description: Returns the estimated fee. content: application/json: schema: type: number /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_balances: get: description: Balances tags: - custody parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/CustodyAccountHolderIdParam' responses: '200': description: Returns list of balances content: application/json: schema: type: array items: $ref: '#/components/schemas/CustodyBalance' /users/{user_id}/surveys: get: description: Fetch the surveys filled in by the current user. The name param is optional, if it's missing, all the surveys created by the user will be returned. tags: - surveys parameters: - $ref: '#/components/parameters/UserIdParam' - in: query name: name schema: type: string responses: '200': description: The surveys list filled in by current user content: application/json: schema: type: array items: $ref: '#/components/schemas/Survey' post: description: Create a named survey for the current user. The data object will contain key value pairs that will reflect the choices made by the user to different survey questions. The key will be unique for each question. tags: - surveys parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Survey information required: true content: application/json: schema: $ref: '#/components/schemas/SurveyForm' responses: '201': description: Survey created and returned content: application/json: schema: $ref: '#/components/schemas/Survey' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc: get: description: Fetch the status of the KYC flow of a personal investor or a business investor. tags: - kyc parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The status of the KYC flow of a personal investor or a business investor content: application/json: schema: $ref: '#/components/schemas/KycStatus' /users/{user_id}/kyc/identities: get: description: Fetch the personal identities associated with the current user. tags: - identities parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The personal identities of the current user content: application/json: schema: type: array items: $ref: '#/components/schemas/Identity' post: description: Create a personal identity for the current user. 'second_country_of_taxation' and 'second_tax_id_number' attributes are required only when exclusively_taxable_in_country_of_taxation is set to false tags: - identities parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Identity information required: true content: application/json: schema: $ref: '#/components/schemas/IdentityForm' responses: '201': description: Personal identity created and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{id}: get: description: Fetch the personal identity for the current user based on the id. tags: - identities parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The identity with the id content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' patch: description: Update the personal identity for the current user. tags: - identities parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Identity information required: true content: application/json: schema: $ref: '#/components/schemas/IdentityForm' responses: '201': description: Personal identity updated and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' delete: description: Delete the personal identity for the current user. tags: - identities parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Personal identity deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{identity_id}/identity_terms: get: description: Fetch the identity terms associated with the identity or legal representative. tags: - identity_terms parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '200': description: The identity terms of the identity or legal representative content: application/json: schema: type: array items: $ref: '#/components/schemas/IdentityTerm' '404': $ref: '#/components/responses/NotFound' post: description: Create an identity term for the identity or legal representative. tags: - identity_terms parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' requestBody: description: Identity term information required: true content: application/json: schema: $ref: '#/components/schemas/IdentityTermForm' responses: '201': description: Identity term created and returned content: application/json: schema: $ref: '#/components/schemas/IdentityTerm' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{identity_id}/pep_status: get: description: Fetch the pep status associated with the identity or legal representative. tags: - pep_status parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '200': description: The pep status of the identity or legal representative content: application/json: schema: $ref: '#/components/schemas/PepStatus' '404': $ref: '#/components/responses/NotFound' post: description: Create a PEP status for the identity or legal representative. tags: - pep_status parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' requestBody: description: PEP status information required: true content: application/json: schema: $ref: '#/components/schemas/PepStatusForm' responses: '201': description: PEP status created and returned content: application/json: schema: $ref: '#/components/schemas/PepStatus' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{identity_id}/addresses: get: description: Fetch the address of a personal investor, a legal representative or a business owner entity tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '200': description: The address of a personal investor, a legal representative or a business owner entity content: application/json: schema: $ref: '#/components/schemas/Address' '404': $ref: '#/components/responses/NotFound' post: description: Create an address for a personal investor, legal representative or a business owner entity tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' requestBody: description: Address information required: true content: application/json: schema: $ref: '#/components/schemas/AddressForm' responses: '201': description: Address created and returned content: application/json: schema: $ref: '#/components/schemas/Address' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{identity_id}/addresses/{id}: patch: description: Update the address for a personal investor, legal representative or business owner entity tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Address information required: true content: application/json: schema: $ref: '#/components/schemas/AddressForm' responses: '201': description: Address updated and returned content: application/json: schema: $ref: '#/components/schemas/Address' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/legal_representatives: get: description: Fetch the legal representatives for a business user. tags: - legal_representatives parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The legal representatives of the current business user content: application/json: schema: type: array items: $ref: '#/components/schemas/Identity' post: description: Create an legal representative for the current business user. 'second_country_of_taxation' and 'second_tax_id_number' attributes are required only when exclusively_taxable_in_country_of_taxation is set to false tags: - legal_representatives parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Legal representative information required: true content: application/json: schema: $ref: '#/components/schemas/LegalRepresentativeForm' responses: '201': description: Legal representative created and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/legal_representatives/{id}: get: description: Fetch the legal representative for the current business user based on the id. tags: - legal_representatives parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The legal representative with the id content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' patch: description: Update the legal representative for the current business user. tags: - legal_representatives parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Legal representative information required: true content: application/json: schema: $ref: '#/components/schemas/LegalRepresentativeForm' responses: '201': description: Legal representative updated and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' delete: description: Delete the legal representative for the current business user. tags: - legal_representatives parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Legal representative deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/business_owners: get: description: Fetch the business owners for the current business user. tags: - business_owners parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The business owners of the current business user content: application/json: schema: type: array items: $ref: '#/components/schemas/Identity' post: description: Create a business owner for the current business user. tags: - business_owners parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Business owner information required: true content: application/json: schema: $ref: '#/components/schemas/BusinessOwnerForm' responses: '201': description: Business owner created and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/business_owners/{id}: get: description: Fetch the business owner for the current business user based on the id. tags: - business_owners parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The legal representative with the id content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' patch: description: Update the business owner for the current business user. tags: - business_owners parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Business owner information required: true content: application/json: schema: $ref: '#/components/schemas/BusinessOwnerForm' responses: '201': description: Business owner updated and returned content: application/json: schema: $ref: '#/components/schemas/Identity' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' delete: description: Delete the business owner for the current business user. tags: - business_owners parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: Legal representative deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{id}/file/{type}/{number}: post: description: Add a file attachment to the identity. tags: - files parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' - $ref: '#/components/parameters/FileTypeParam' - $ref: '#/components/parameters/FileNumberParam' - $ref: '#/components/parameters/FileIssuedParam' - $ref: '#/components/parameters/FileExpiresParam' - $ref: '#/components/parameters/FileIssuingAuthorityParam' - $ref: '#/components/parameters/FileIssuingCountryParam' requestBody: description: The identity file information required: true content: application/json: schema: $ref: '#/components/schemas/AttachmentForm' responses: '201': description: File attachment created and returned content: application/json: schema: $ref: '#/components/schemas/IdentityAttachment' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{id}/file: get: description: Fetch the list of the identity file attachments. tags: - files parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The list of the identity file attachments content: application/json: schema: type: array items: $ref: '#/components/schemas/IdentityAttachment' '400': $ref: '#/components/responses/BadRequest' /users/{user_id}/kyc/identities/{identity_id}/video_identifications: post: description: Start the IDnow video identification session. In order to start a video identification session, the identity terms need to be accepted through the identity_terms POST method. An identity with address and bank account needs to exist before starting the identification. tags: - kyc parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '201': description: An empty video identification created and returned content: application/json: schema: $ref: '#/components/schemas/VideoIdentification' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/identities/{identity_id}/video_identifications/{id}: get: description: Fetch the IDnow video identification session data tags: - kyc parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: The video identification for the identity content: application/json: schema: $ref: '#/components/schemas/VideoIdentification' '404': $ref: '#/components/responses/NotFound' /users/{user_id}/kyc/identities/{identity_id}/kyc_verification: post: tags: - kyc parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' requestBody: description: The Kyc Verification information required: true content: application/json: schema: $ref: '#/components/schemas/KycVerificationForm' responses: '201': description: Kyc Verification created and returned content: application/json: schema: $ref: '#/components/schemas/KycVerification' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' get: tags: - kyc parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '200': description: Kyc Verification for Identity content: application/json: schema: $ref: '#/components/schemas/VideoIdentification' '404': $ref: '#/components/responses/NotFound' /users/{user_id}/kyc/identities/{identity_id}/kyc_verification/identity_document: get: description: Fetch the identity document associated with the kyc verification. tags: - identity_documents parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' responses: '200': description: The identity documents of the kyc verification content: application/json: schema: $ref: '#/components/schemas/IdentityDocument' '404': $ref: '#/components/responses/NotFound' post: description: Create an identity document for the kyc verification. tags: - identity_documents parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/IdentityIdParam' requestBody: description: Identity document information required: true content: application/json: schema: $ref: '#/components/schemas/IdentityDocumentForm' responses: '201': description: Identity document created and returned content: application/json: schema: $ref: '#/components/schemas/IdentityDocument' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses: get: description: Fetch the businesses for the current user. tags: - businesses parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The businesses of the current user content: application/json: schema: type: array items: $ref: '#/components/schemas/Business' '404': $ref: '#/components/responses/NotFound' post: description: Create a business entry for the current user. 'second_country_of_taxation' and 'second_tax_id_number' attributes are required only when exclusively_taxable_in_country_of_taxation is set to false tags: - businesses parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Business information required: true content: application/json: schema: $ref: '#/components/schemas/BusinessForm' responses: '201': description: Business created and returned content: application/json: schema: $ref: '#/components/schemas/Business' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses/{id}: patch: description: Update the business information. tags: - businesses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Business information required: true content: application/json: schema: $ref: '#/components/schemas/BusinessForm' responses: '201': description: Business updated and returned content: application/json: schema: $ref: '#/components/schemas/Business' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses/{business_id}/addresses: get: description: Fetch the address of the business. tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/BusinessIdParam' responses: '200': description: The address of the business content: application/json: schema: $ref: '#/components/schemas/Address' '404': $ref: '#/components/responses/NotFound' post: description: Create an address entry for the business. tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/BusinessIdParam' requestBody: description: Address information required: true content: application/json: schema: $ref: '#/components/schemas/AddressForm' responses: '201': description: Address created and returned content: application/json: schema: $ref: '#/components/schemas/Address' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses/{business_id}/addresses/{id}: patch: description: Update the address for the business. tags: - addresses parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/BusinessIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Address information required: true content: application/json: schema: $ref: '#/components/schemas/AddressForm' responses: '201': description: Address updated and returned content: application/json: schema: $ref: '#/components/schemas/Address' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses/file/{type}: post: description: Add file attachment to the current business. tags: - files parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/FileTypeParam' requestBody: description: The business file information required: true content: application/json: schema: $ref: '#/components/schemas/AttachmentForm' responses: '201': description: File attachment created and returned content: application/json: schema: $ref: '#/components/schemas/BusinessAttachment' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/kyc/businesses/file: get: description: Fetch the list of business file attachments. tags: - files parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The list of business file attachments content: application/json: schema: type: array items: $ref: '#/components/schemas/BusinessAttachment' '400': $ref: '#/components/responses/BadRequest' /users/{user_id}/bank_accounts: get: description: Fetch the bank accounts of the current user. tags: - bank_accounts parameters: - $ref: '#/components/parameters/UserIdParam' responses: '200': description: The bank accounts of the current user content: application/json: schema: $ref: '#/components/schemas/BankAccount' '404': $ref: '#/components/responses/NotFound' post: description: Create bank account for the current user. tags: - bank_accounts parameters: - $ref: '#/components/parameters/UserIdParam' requestBody: description: Bank account information required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountForm' responses: '201': description: Bank account created and returned content: application/json: schema: $ref: '#/components/schemas/BankAccount' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/bank_accounts/{id}: patch: description: Update the bank account for the current user tags: - bank_accounts parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' requestBody: description: Bank account information required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountForm' responses: '201': description: Bank account updated and returned content: application/json: schema: $ref: '#/components/schemas/BankAccount' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/files/{id}: delete: description: Delete the file attachment a business or an identity. tags: - files parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/ResourceIdParam' responses: '200': description: File deleted $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: responses: Success: description: 'Request successful' Unauthorized: description: 'Authorization information is missing or invalid.' NotFound: description: 'Resource not found.' UnprocessableEntity: description: 'Request body has errors or invalid.' ServerError: description: 'Unexpected server error.' BadRequest: description: 'Server cannot or will not process the request' MethodNotAllowed: description: 'Request method is known by the server but is not supported by the target resource' schemas: User: type: object properties: id: type: string format: uuid user_code: type: string email: type: string nullable: false locale: type: string terms_acceptance: type: boolean email_confirmed: type: boolean approved_at: type: string format: datetime rejected_at: type: string format: datetime created_at: type: string format: datetime nullable: false business_investor: type: boolean kyc_status: type: string approved: type: boolean rejected: type: boolean invested: type: boolean identities: $ref: '#/components/schemas/Identity' UserForm: type: object required: - email - terms_acceptance - business_investor properties: email: type: string business_investor: type: boolean terms_acceptance: type: boolean locale: type: string description: accepted values are 'en' and 'de' KycStatus: type: object properties: identity: type: boolean address: type: boolean bank_account: type: boolean video_identification: type: boolean email: type: boolean business: type: boolean legal_reps: type: boolean documents: type: boolean Identity: type: object properties: id: type: string format: uuid user_id: type: string format: uuid company_role: type: string tax_id_number: type: string first_name: type: string last_name: type: string phone_number: type: string citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_birth: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format date_of_birth: type: string format: datetime video_identification_completed_at: type: string format: datetime place_of_birth: type: string family_status: type: string gender: type: string not_us_income_tax: type: boolean trading_on_behalf_of_self: type: boolean title: type: string name_affix: type: string mifid_status: type: string enum: ['skipped', 'passed', 'failed'] name_at_birth: type: string second_citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_tax_id_number: type: string share: type: number format: decimal sole_right_of_representation: type: boolean exclusively_taxable_in_country_of_taxation: type: boolean type: type: string video_identification_completed: type: boolean address: $ref: '#/components/schemas/Address' video_identifications: type: array items: $ref: '#/components/schemas/VideoIdentification' attachments: type: array items: $ref: '#/components/schemas/IdentityAttachment' term: $ref: '#/components/schemas/IdentityTerm' IdentityForm: type: object required: - citizenship - date_of_birth - first_name - last_name - country_of_taxation - not_us_income_tax - tax_id_number - exclusively_taxable_in_country_of_taxation - second_country_of_taxation - second_tax_id_number - country_of_birth - gender - place_of_birth - family_status properties: mifid_status: type: string enum: ['skipped', 'passed', 'failed'] tax_id_number: type: string first_name: type: string last_name: type: string phone_number: type: string citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_birth: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format date_of_birth: type: string format: datetime description: must have YYYY-MM-DD format place_of_birth: type: string family_status: type: string description: proposed values Single, Married, Registered partnership, Divorced gender: type: string description: proposed values Female, Male, Other not_us_income_tax: type: boolean trading_on_behalf_of_self: type: boolean title: type: string name_affix: type: string name_at_birth: type: string second_citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_tax_id_number: type: string exclusively_taxable_in_country_of_taxation: type: boolean IdentityTerm: type: object properties: custody_wallet_terms_acceptance: type: boolean custody_wallet_privacy_acceptance: type: boolean IdentityTermForm: type: object properties: terms: type: object required: - custody_wallet_terms_acceptance - custody_wallet_privacy_acceptance properties: custody_wallet_terms_acceptance: type: boolean custody_wallet_privacy_acceptance: type: boolean LegalRepresentativeForm: type: object required: - citizenship - date_of_birth - first_name - last_name - country_of_taxation - not_us_income_tax - exclusively_taxable_in_country_of_taxation - second_country_of_taxation - second_tax_id_number - country_of_birth - gender - place_of_birth - family_status - sole_right_of_representation properties: company_role: type: string tax_id_number: type: string first_name: type: string last_name: type: string citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_birth: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format date_of_birth: type: string format: datetime place_of_birth: type: string family_status: type: string description: proposed values Single, Married, Registered partnership, Divorced gender: type: string description: proposed values Female, Male, Diverse not_us_income_tax: type: boolean trading_on_behalf_of_self: type: boolean title: type: string name_affix: type: string name_at_birth: type: string second_citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_tax_id_number: type: string sole_right_of_representation: type: boolean exclusively_taxable_in_country_of_taxation: type: boolean BusinessOwnerForm: type: object required: - citizenship - date_of_birth - first_name - last_name - country_of_taxation - not_us_income_tax - exclusively_taxable_in_country_of_taxation - second_country_of_taxation - second_tax_id_number - share properties: tax_id_number: type: string first_name: type: string last_name: type: string citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format date_of_birth: type: string format: datetime title: type: string name_affix: type: string name_at_birth: type: string second_citizenship: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format share: type: number format: decimal IdentityAttachment: type: object properties: id: type: string format: uuid file: type: object filename: type: string document_type: type: string document_id_number: type: string issued_at: type: string format: datetime expires_at: type: string format: datetime issuing_authority: type: string issuing_country: type: string content_type: type: string Address: type: object properties: id: type: string format: uuid street_additional: type: string city: type: string country: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format state: type: string street: type: string number: type: string zipcode: type: string AddressForm: type: object properties: address: type: object required: - city - country - street - number - zipcode properties: city: type: string country: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format state: type: string nullable: false description: cannot be null street: type: string number: type: string zipcode: type: string street_additional: type: string BankAccount: type: object properties: id: type: string format: uuid iban: type: string bic: type: string bank_name: type: string account_owner: type: string BankAccountForm: type: object properties: bank_account: type: object required: - iban - account_owner properties: iban: type: string bic: type: string minLength: 8 maxLength: 11 bank_name: type: string account_owner: type: string VideoIdentification: type: object properties: id: type: string format: uuid identity_id: type: string format: uuid idnow_id: type: string redirect_url: type: string statuses: type: array items: type: string data: type: object url: type: string has_files: type: boolean completed: type: boolean success: type: boolean rejected: type: boolean pending: type: boolean reason: type: string identificationtime: type: string format: datetime status: type: string KycVerification: type: object properties: id: type: string format: uuid date: type: string format: date method_type: type: string enum: [video_ident, id_copy, auto_ident, in_person, no_verification] created_at: type: string format: datetime Business: type: object properties: id: type: string format: uuid name: type: string legal_name: type: string tax_id_number: type: string legal_form: type: string register_number: type: string country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_tax_id_number: type: string exclusively_taxable_in_country_of_taxation: type: boolean BusinessForm: type: object required: - legal_name - register_number - tax_id_number - country_of_taxation - legal_form - exclusively_taxable_in_country_of_taxation - second_country_of_taxation - second_tax_id_number properties: legal_name: type: string tax_id_number: type: string legal_form: type: string register_number: type: string country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_country_of_taxation: type: string description: two-letter country codes in ISO 3166-1 alpha-2 format second_tax_id_number: type: string exclusively_taxable_in_country_of_taxation: type: boolean BusinessAttachment: type: object properties: id: type: string format: uuid filename: type: string document_type: type: string AttachmentForm: type: object required: - attachment properties: attachment: type: object CustodyAccount: type: object properties: id: type: string account_holder_id: type: string wallet_address_id: type: string address: type: string asset: $ref: '#/components/schemas/CustodyAsset' CustodyAccountHolder: type: object properties: id: type: string internal_id: type: string name: type: string email: type: string kyc_data: type: object properties: address: $ref: '#/components/schemas/Address' identity: $ref: '#/components/schemas/Identity' idnow_id: type: string idnow_id: type: string accounts: type: array items: $ref: '#/components/schemas/CustodyAccount' CustodyAsset: type: object properties: id: type: string name: type: string description: type: string wallet_id: type: string network: type: string code: type: string issuer_address: type: string url: type: string details: type: object CustodyBalance: type: object properties: account_id: type: string balance: type: number CustodyTransaction: type: object properties: id: type: string amount: type: number from_address: type: string destination_address: type: string reference: type: string asset_code: type: string asset_issuer: type: string tx_hash: type: string confirmed_at: type: string format: datetime failed_at: type: string format: datetime created_at: type: string format: datetime status: type: string cursor: type: integer CustodyTransactionForm: type: object properties: transaction: type: object required: - amount - destination_address - idem_key properties: amount: type: number destination_address: type: string idem_key: type: string reference: type: string CustodyAccountForm: type: object properties: custody_account: type: object required: - asset_id properties: asset_id: type: string format: uuid KycVerificationForm: type: object properties: date: type: string format: date method_type: type: string enum: [video_ident, id_copy, auto_ident, in_person, no_verification] IdentityDocument: type: object properties: id: type: string format: uuid kyc_verification_id: type: string format: uuid country: type: string document_type: type: string issue_date: type: string format: date issued_by: type: string nationality: type: string number: type: string valid_until: type: string format: date created_at: type: string format: datetime updated_at: type: string format: datetime IdentityDocumentForm: type: object properties: identity_document: type: object required: - check_date properties: country: type: string document_type: type: string issue_date: type: string format: date issued_by: type: string nationality: type: string number: type: string valid_until: type: string format: date ProjectForm: type: object properties: project: type: object required: - code - sale_starts_at - coupon_bps - min_investment - account_name - iban - bvdh_customer_id - currency - free_float_bps - number_of_tokens - minimum_subscription_bps - token_price properties: code: type: string chain: type: string default: Ethereum enum: [Avalanche, Ethereum, Polygon, Stellar] sale_starts_at: type: string format: datetime sale_ends_at: type: string format: datetime free_float_bps: type: number number_of_tokens: type: number format: float minimum_subscription_bps: type: number token_price: type: number format: float currency: type: string coupon_bps: type: integer min_investment: type: number format: float published_at: type: string format: datetime account_name: type: string has_investment_survey: type: boolean transferability: type: string enum: [open, white_list] bvdh_customer_id: type: string iban: type: string bic: type: string Payout: type: object properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string created_at: type: string format: datetime nullable: false snapshot_at: type: string format: datetime nullable: false distribution_amount: type: number taxable_share_bps: type: number UserPayout: type: object properties: id: type: string format: uuid user_id: type: string token_amount: type: number format: float payout_amount: type: number format: float wallet_address_id: type: string format: uuid wallet_address: type: string created_at: type: string format: datetime nullable: false Project: type: object properties: id: type: string format: uuid code: type: string chain: type: string default: Ethereum enum: [Avalanche, Ethereum, Polygon, Stellar] description: type: string nullable: true free_float_bps: type: number number_of_tokens: type: string minimum_subscription_bps: type: number token_price: type: string currency: type: string coupon_bps: type: integer min_investment: type: number format: float on_sale: type: boolean pre_sale: type: boolean post_sale: type: boolean sale_starts_at: type: string format: datetime sale_ends_at: type: string format: datetime published: type: boolean account_name: type: string has_investment_survey: type: boolean transferability: type: string enum: [open, white_list] bvdh_customer_id: type: string iban: type: string bic: type: string ProjectPrepareForDistributionStatus: type: object properties: code: type: string enum: [pending, in_progress, done, incomplete] description: "pending: not yet started\n\nin_progress: in progress\n\ndone: done\n\nincomplete: some orders have not yet been prepared for distribution" percentage: type: number nullable: true description: The percentage of orders already prepared for distribution ProjectStats: type: object properties: total_invested: type: number InvestmentTerm: type: object properties: id: type: string format: uuid user_id: type: string format: uuid project_id: type: string format: uuid documents_understood: type: boolean read_printed_securities_info_sheet: type: boolean InvestmentTermForm: type: object properties: terms: type: object required: - read_printed_securities_info_sheet - documents_understood properties: read_printed_securities_info_sheet: type: boolean documents_understood: type: boolean Order: type: object properties: id: type: string format: uuid amount: type: number format: float cancelled_at: type: string format: datetime nullable: true currency: type: string sender_iban: type: string nullable: true user_id: type: string format: uuid created_at: type: string format: datetime nullable: false updated_at: type: string format: datetime nullable: false project_code: type: string disposable_capital: type: boolean nullable: true suitable_income: type: boolean nullable: true order_code: type: string status: $ref: '#/components/schemas/OrderStatus' payment_details: type: object properties: account_name: type: string bank_name: type: string bic: type: string iban: type: string reference_code: type: string wallet_address: type: string nullable: true external_metadata: type: object format: json OrderForm: type: object properties: order: type: object required: - amount - currency properties: amount: type: string currency: type: string sender_iban: type: string disposable_capital: type: boolean suitable_income: type: boolean external_metadata: type: object format: json OrderStatus: type: object properties: id: type: string format: uuid order_id: type: string format: uuid title: type: string reason: type: string nullable: true Payment: type: object properties: id: type: string format: uuid amount: type: number format: float created_at: type: string format: datetime order_id: type: string format: uuid project_id: type: string format: uuid PaymentForm: type: object properties: amount: type: number format: float PepStatus: type: object properties: id: type: string format: uuid identity_id: type: string format: uuid is_exposed: type: boolean is_sanctioned: type: boolean check_date: type: string format: datetime source: type: string nullable: true reason: type: string nullable: true created_at: type: string format: datetime updated_at: type: string format: datetime PepStatusForm: type: object properties: pep_status: type: object required: - check_date properties: is_exposed: type: boolean is_sanctioned: type: boolean check_date: type: string format: datetime source: type: string nullable: true reason: type: string nullable: true Survey: type: object properties: name: type: string data: type: object format: json SurveyForm: type: object properties: survey: type: object required: - name - data properties: name: type: string data: type: object Config: type: object properties: timezone: type: string format: datetime supported_countries: type: array items: type: string Snapshot: type: object properties: id: type: string format: uuid asset_id: type: string count: type: number total_amount: type: number balances: type: array items: properties: account: type: string balance: type: number format: float parameters: ResourceIdParam: name: id in: path description: 'Resource ID' required: true schema: type: string PageParam: name: page in: query description: 'Pagination page' required: false schema: type: integer ProjectCodeParam: name: code in: path description: Project code/symbol required: true schema: type: string ProjectIdParam: name: project_id in: path description: Project id required: true schema: type: string OrderIdParam: name: order_id in: path description: Order id required: true schema: type: string UserIdParam: name: user_id in: path description: User id required: true schema: type: string IdentityIdParam: name: identity_id in: path description: Identity or Legal representative id required: true schema: type: string BusinessIdParam: name: business_id in: path description: Business id required: true schema: type: string CustodyAccountIdParam: name: custody_account_id in: path description: Custody account id required: true schema: type: string CustodyAccountHolderIdParam: name: custody_account_holder_id in: path description: Custody account holder id required: true schema: type: string FileTypeParam: name: type in: path description: File type required: true schema: type: string enum: - commercial_register - authorization - legal_structure FileNumberParam: name: number in: path description: Document ID number required: true schema: type: string FileIssuedParam: name: issued_at in: query description: Document issued at date required: true schema: type: string FileExpiresParam: name: expires_at in: query description: Document expires at date required: true schema: type: string FileIssuingAuthorityParam: name: issuing_authority in: query description: Document issuing authority required: true schema: type: string FileIssuingCountryParam: name: issuing_country in: query description: Document issuing country required: true schema: type: string EmailParam: name: email in: query description: User email required: true schema: type: string UpdatedAtParam: name: updated_at in: query description: Order updated_at attribute required: true schema: type: string StatusParam: name: status in: query description: Order status attribute required: true schema: type: string OrderStatusParam: name: status in: path description: Order status attribute required: true schema: type: string PayoutIdParam: name: payout_id in: path description: Payout id required: true schema: type: string