API version: Mar 01, 2022 23:19 pm Back to last version

The Bitbond Offering Manager API provides resource endpoints for fetching projects, creating orders and investments 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 comes in, an investment 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.

Allocating investments
Once an investor places an order for a project, the details of the bank account they need to send the funds to is revealed.
In order to complete the flow, the investor needs to send the amount designated for the investment to the IBAN provided along with the custom reference code generated. The reference code will be created out of the order code. When the funds reach the Bvdh bank account, a webhook is triggered on Bitbond's side containing the transaction's payload.
The investment is allocated to the user, order and project based on the reference code.

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:

  • 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_paid
    • Is triggered when the endpoint POST /admin/investments/:id/allocate is used and after the investment is successfully allocated in the system.
    • Is triggered when a bank payment transaction is received by the bank and after new investment is successfully allocated in the system.
    • Is triggered when admin user is seeding test environment with test investment data using Asset Manager Labs section (does not apply to production)
  • order_cancelled
    • Is triggered when admin user cancels the order in Asset Manager
  • investment_received
    • Is triggered automatically when investment funds are recieved on BVDH bank account
    • Is triggered when admin user manually allocates the investment in the Asset Manager
    • Is triggered when admin user is seeding test environment with test investment data using Asset Manager Labs section (does not apply to production)
  • 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)
  • 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
  • distribution_created
    • Is triggered when distribution to Blockchain was processed.
  • transaction_created (WIP)
Webhook payloads
  • order_created
{
  event: 'order_created',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • order_paid
{
  event: 'order_paid',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • order_cancelled
{
  event: 'order_cancelled',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • investment_received
{
  event: 'investment_received',
  investment_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • kyc_video_identification_success
{
  event: 'kyc_video_identification_success',
  user_id: {String} UUID
}
  • kyc_approved
{
  event: 'kyc_approved',
  user_id: {String} UUID
}
  • kyc_rejected
{
  event: 'kyc_rejected',
  user_id: {String} UUID
}
  • distribution_created
{
  event: 'distribution_created',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • 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
}

This is the documentation for version 0.0.1 of the API. Last update on Mar 1, 2022.

Base URL
http://api.example.com

Fetch the address of a personal investor

GET /users/{user_id}/kyc/identities/{identity_id}/addresses

Fetch the address of a personal investor, a legal representative or a business owner entity

Path parameters
  • user_id Required / string

    User id

  • identity_id Required / string

    Identity or Legal representative id

Responses
  • 200 object

    The address of a personal investor, a legal representative or a business owner entity

  • 404

    Resource not found.

GET /users/{user_id}/kyc/identities/{identity_id}/addresses
curl \
 -X GET http://api.example.com/users/{user_id}/kyc/identities/{identity_id}/addresses
Response example (200)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Create an address for a personal investor

POST /users/{user_id}/kyc/identities/{identity_id}/addresses

Create an address for a personal investor, legal representative or a business owner entity

Path parameters
  • user_id Required / string

    User id

  • identity_id Required / string

    Identity or Legal representative id

Body Required

Address information

Responses
  • 201 object

    Address created and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

POST /users/{user_id}/kyc/identities/{identity_id}/addresses
curl \
 -X POST http://api.example.com/users/{user_id}/kyc/identities/{identity_id}/addresses \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Update the address for a personal investor

PATCH /users/{user_id}/kyc/identities/{identity_id}/addresses/{id}

Update the address for a personal investor, legal representative or business owner entity

Path parameters
  • user_id Required / string

    User id

  • identity_id Required / string

    Identity or Legal representative id

  • id Required / string

    Resource ID

Body Required

Address information

Responses
  • 201 object

    Address updated and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

PATCH /users/{user_id}/kyc/identities/{identity_id}/addresses/{id}
curl \
 -X PATCH http://api.example.com/users/{user_id}/kyc/identities/{identity_id}/addresses/{id} \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Fetch the address of the business

GET /users/{user_id}/kyc/businesses/{business_id}/addresses

Fetch the address of the business.

Path parameters
Responses
GET /users/{user_id}/kyc/businesses/{business_id}/addresses
curl \
 -X GET http://api.example.com/users/{user_id}/kyc/businesses/{business_id}/addresses
Response example (200)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Create an address entry for the business

POST /users/{user_id}/kyc/businesses/{business_id}/addresses

Create an address entry for the business.

Path parameters
Body Required

Address information

Responses
  • 201 object

    Address created and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

POST /users/{user_id}/kyc/businesses/{business_id}/addresses
curl \
 -X POST http://api.example.com/users/{user_id}/kyc/businesses/{business_id}/addresses \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Update the address for the business

PATCH /users/{user_id}/kyc/businesses/{business_id}/addresses/{id}

Update the address for the business.

Path parameters
  • user_id Required / string

    User id

  • business_id Required / string

    Business id

  • id Required / string

    Resource ID

Body Required

Address information

Responses
  • 201 object

    Address updated and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

PATCH /users/{user_id}/kyc/businesses/{business_id}/addresses/{id}
curl \
 -X PATCH http://api.example.com/users/{user_id}/kyc/businesses/{business_id}/addresses/{id} \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Fetch the bank accounts of the current user

GET /users/{user_id}/bank_accounts

Fetch the bank accounts of the current user.

Path parameters
  • user_id Required / string

    User id

Responses
GET /users/{user_id}/bank_accounts
curl \
 -X GET http://api.example.com/users/{user_id}/bank_accounts
Response example (200)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Create bank account for the current user

POST /users/{user_id}/bank_accounts

Create bank account for the current user.

Path parameters
  • user_id Required / string

    User id

Body Required

Bank account information

Responses
  • 201 object

    Bank account created and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

POST /users/{user_id}/bank_accounts
curl \
 -X POST http://api.example.com/users/{user_id}/bank_accounts \
 -H "Content-Type: application/json" \
 -d '{"bank_account":{"iban":"string","bic":"string","bank_name":"string","account_owner":"string"}}'
Request example
{
  "bank_account": {
    "iban": "string",
    "bic": "string",
    "bank_name": "string",
    "account_owner": "string"
  }
}
Response example (201)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Update the bank account for the current user

PATCH /users/{user_id}/bank_accounts/{id}

Update the bank account for the current user

Path parameters
  • user_id Required / string

    User id

  • id Required / string

    Resource ID

Body Required

Bank account information

Responses
  • 201 object

    Bank account updated and returned

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

PATCH /users/{user_id}/bank_accounts/{id}
curl \
 -X PATCH http://api.example.com/users/{user_id}/bank_accounts/{id} \
 -H "Content-Type: application/json" \
 -d '{"bank_account":{"iban":"string","bic":"string","bank_name":"string","account_owner":"string"}}'
Request example
{
  "bank_account": {
    "iban": "string",
    "bic": "string",
    "bank_name": "string",
    "account_owner": "string"
  }
}
Response example (201)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Fetch the businesses for the current user

GET /users/{user_id}/kyc/businesses

Fetch the businesses for the current user.

Path parameters
  • user_id Required / string

    User id

Responses
GET /users/{user_id}/kyc/businesses
curl \
 -X GET http://api.example.com/users/{user_id}/kyc/businesses
Response example (200)
[
  {
    "id": "string",
    "name": "string",
    "legal_name": "string",
    "tax_id_number": "string",
    "legal_form": "string",
    "register_number": "string",
    "country_of_taxation": "string",
    "second_country_of_taxation": "string",
    "second_tax_id_number": "string",
    "exclusively_taxable_in_country_of_taxation": true
  }
]

Create a business entry for the current user

POST /users/{user_id}/kyc/businesses

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

Path parameters
  • user_id Required / string

    User id

Body Required

Business information

Responses
POST /users/{user_id}/kyc/businesses
curl \
 -X POST http://api.example.com/users/{user_id}/kyc/businesses \
 -H "Content-Type: application/json" \
 -d '{"legal_name":"string","tax_id_number":"string","legal_form":"string","register_number":"string","country_of_taxation":"string","second_country_of_taxation":"string","second_tax_id_number":"string","exclusively_taxable_in_country_of_taxation":true}'
Request example
{
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}
Response example (201)
{
  "id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}

Update the business information

PATCH /users/{user_id}/kyc/businesses/{id}

Update the business information.

Path parameters
  • user_id Required / string

    User id

  • id Required / string

    Resource ID

Body Required

Business information

Responses
PATCH /users/{user_id}/kyc/businesses/{id}
curl \
 -X PATCH http://api.example.com/users/{user_id}/kyc/businesses/{id} \
 -H "Content-Type: application/json" \
 -d '{"legal_name":"string","tax_id_number":"string","legal_form":"string","register_number":"string","country_of_taxation":"string","second_country_of_taxation":"string","second_tax_id_number":"string","exclusively_taxable_in_country_of_taxation":true}'
Request example
{
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}
Response example (201)
{
  "id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}

Fetch the business owners for the current business user

GET /users/{user_id}/kyc/business_owners

Fetch the business owners for the current business user.

Path parameters
  • user_id Required / string

    User id

Responses
GET /users/{user_id}/kyc/business_owners
curl \
 -X GET http://api.example.com/users/{user_id}/kyc/business_owners
Response example (200)
[
  {
    "id": "string",
    "user_id": "string",
    "company_role": "string",
    "tax_id_number": "string",
    "first_name": "string",
    "last_name": "string",
    "phone_number": "string",
    "citizenship": "string",
    "country_of_birth": "string",
    "date_of_birth": "string",
    "video_identification_completed_at": "string",
    "place_of_birth": "string",
    "family_status": "string",
    "gender": "string",
    "not_pep": true,
    "not_us_income_tax": true,
    "trading_on_behalf_of_self": true,
    "title": "string",
    "name_affix": "string",
    "name_at_birth": "string",
    "second_citizenship": "string",
    "country_of_taxation": "string",
    "second_country_of_taxation": "string",
    "second_tax_id_number": "string",
    "share": 42.0,
    "sole_right_of_representation": true,
    "exclusively_taxable_in_country_of_taxation": true,
    "type": "string",
    "video_identification_completed": true,
    "address": [
      {
        "id": "string",
        "street_additional": "string",
        "city": "string",
        "country": "string",
        "state": "string",
        "street": "string",
        "number": "string",
        "zipcode": "string"
      }
    ],
    "video_identifications": [
      {
        "id": "string",
        "identity_id": "string",
        "idnow_id": "string",
        "redirect_url": "string",
        "statuses": [
          "string"
        ],
        "data": {},
        "url": "string",
        "has_files": true,
        "completed": true,
        "success": true,
        "rejected": true,
        "pending": true,
        "reason": "string",
        "identificationtime": "string",
        "status": "string"
      }
    ],
    "attachments": [
      {
        "id": "string",
        "file": {},
        "filename": "string",
        "document_type": "string",
        "document_id_number": "string",
        "issued_at": "string",
        "expires_at": "string",
        "issuing_authority": "string",
        "issuing_country": "string",
        "content_type": "string"
      }
    ],
    "term": [
      {
        "custody_wallet_terms_acceptance": true,
        "custody_wallet_privacy_acceptance": true
      }
    ]
  }
]

Create a business owner for the current business user

POST /users/{user_id}/kyc/business_owners

Create a business owner for the current business user.

Path parameters
  • user_id Required / string

    User id

Body Required

Business owner information

Responses
POST /users/{user_id}/kyc/business_owners
curl \
 -X POST http://api.example.com/users/{user_id}/kyc/business_owners \
 -H "Content-Type: application/json" \
 -d '{"tax_id_number":"string","first_name":"string","last_name":"string","citizenship":"string","date_of_birth":"string","not_pep":true,"title":"string","name_affix":"string","name_at_birth":"string","second_citizenship":"string","country_of_taxation":"string","share":42.0}'
Request example
{
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "citizenship": "string",
  "date_of_birth": "string",
  "not_pep": true,
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "share": 42.0
}
Response example (201)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_pep": true,
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Fetch the business owner for the current business user based on the id

GET /users/{user_id}/kyc/business_owners/{id}

Fetch the business owner for the current business user based on the id.

Path parameters
  • user_id Required / string

    User id

  • id Required / string

    Resource ID

Responses
GET /users/{user_id}/kyc/business_owners/{id}
curl \
 -X GET http://api.example.com/users/{user_id}/kyc/business_owners/{id}
Response example (200)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_pep": true,
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Delete the business owner for the current business user

DELETE /users/{user_id}/kyc/business_owners/{id}

Delete the business owner for the current business user.

Path parameters
  • user_id Required / string

    User id

  • id Required / string

    Resource ID

Responses
  • 200

    Request successful

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

DELETE /users/{user_id}/kyc/business_owners/{id}
curl \
 -X DELETE http://api.example.com/users/{user_id}/kyc/business_owners/{id}

Update the business owner for the current business user

PATCH /users/{user_id}/kyc/business_owners/{id}

Update the business owner for the current business user.

Path parameters
  • user_id Required / string

    User id

  • id Required / string

    Resource ID

Body Required

Business owner information

Responses
PATCH /users/{user_id}/kyc/business_owners/{id}
curl \
 -X PATCH http://api.example.com/users/{user_id}/kyc/business_owners/{id} \
 -H "Content-Type: application/json" \
 -d '{"tax_id_number":"string","first_name":"string","last_name":"string","citizenship":"string","date_of_birth":"string","not_pep":true,"title":"string","name_affix":"string","name_at_birth":"string","second_citizenship":"string","country_of_taxation":"string","share":42.0}'
Request example
{
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "citizenship": "string",
  "date_of_birth": "string",
  "not_pep": true,
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "share": 42.0
}
Response example (201)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_pep": true,
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Fetch the configuration data

GET /config

Fetch the configuration data, like timezone and supported countries for the current user.

Responses
GET /config
curl \
 -X GET http://api.example.com/config
Response example (200)
[
  {
    "timezone": "string",
    "supported_countries": [
      "string"
    ]
  }
]

Fetch the credits available for the current user

GET /users/{user_id}/credits

Fetch the credits available for the current user.

Path parameters
  • user_id Required / string

    User id

Responses
GET /users/{user_id}/credits
curl \
 -X GET http://api.example.com/users/{user_id}/credits
Response example (200)
[
  {
    "id": "string",
    "amount": 42.0,
    "currency": "string",
    "redeemed_at": "string",
    "redeemed": true,
    "created_at": "string"
  }
]

Redeem the credits available for the current user towards an investment in a project

GET /users/{user_id}/credits/redeem/{project_id}

Redeem the credits available for the current user towards an investment in a project. Credits can only be redeemed in on sale projects.

Path parameters
Responses
  • 200 array[object]

    The credits redeemed and returned

  • 400

    Server cannot or will not process the request

  • 401

    Authorization information is missing or invalid.

GET /users/{user_id}/credits/redeem/{project_id}
curl \
 -X GET http://api.example.com/users/{user_id}/credits/redeem/{project_id}
Response example (200)
[
  {
    "id": "string",
    "amount": 42.0,
    "currency": "string",
    "redeemed_at": "string",
    "redeemed": true,
    "created_at": "string"
  }
]

Assets

GET /custody_assets

Assets

Responses
GET /custody_assets
curl \
 -X GET http://api.example.com/custody_assets
Response example (200)
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "wallet_id": "string",
    "protocol": "string",
    "network": "string",
    "code": "string",
    "issuer_address": "string",
    "url": "string",
    "details": {}
  }
]

User account holders

GET /users/{user_id}/custody_account_holders

User account holders

Path parameters
  • user_id Required / string

    User id

Responses