Introduction

​

Overview

• All requests are JSON over HTTPS with Bearer auth.
• Crypto endpoints are namespaced under /crypto-exchange within the same base URL.

​

Environments & Base URLs

Your tenant uses customer‑scoped hostnames.

• Dev: https://client-api.dev.{your-domain}.io
• Prod: https://client-api.{your-domain}.io

export CLIENT_API_BASE="https://client-api.dev.{your-domain}.io" # or prod

​

Authentication (Cognito)

​

What you need

• User Pool ID and Region
• Web App Client ID (no client secret for public web/mobile apps)
• (Optional) Hosted UI domain if you use Cognito’s OAuth2/PKCE login

​

How it works

1. Your web/mobile app authenticates the end user against Cognito:
   • Hosted UI + PKCE (recommended) or a library like AWS Amplify Auth.
2. Cognito returns short‑lived JWTs:
   • ID token (user identity claims)
   • Access token (authorization for APIs)
   • Refresh token (to renew tokens silently)
3. Your app calls Finhost Client API with the Access token in the header:

Authorization: Bearer <access_token>

4. On expiry, renew tokens via the refresh token (Amplify or Hosted UI session) and retry.

​

Example — fetch profile (JS)

const res = await fetch(`${CLIENT_API_BASE}/client`, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const me = await res.json();

​

Example — cURL

curl --request GET \
  --url "$CLIENT_API_BASE/client" \
  --header "Authorization: Bearer $TOKEN"

​

Canonical integration flows

​

A) Individual onboarding (KYC → account → bank details → payments)

1. Initiate client — POST /client
   Copy

   curl -X POST "$CLIENT_API_BASE/client" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "name": "John", "surname": "Doe", "nationality": "UKR",
       "birthday": "2017-07-21", "phone": "+380689873682"
     }'
   
2. Accept contract (client) — POST /v2/clients/contract-accept
   Copy

   curl -X POST "$CLIENT_API_BASE/v2/clients/contract-accept" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"contractId": "regularContract"}'
   
3. Get KYC access token — GET /v1/kyc/access-token (for Sumsub Web SDK)
   Copy

   curl -X GET "$CLIENT_API_BASE/v1/kyc/access-token" \
     -H "Authorization: Bearer $TOKEN"
   
4. Create account — POST /v1/accounts
   Copy

   curl -X POST "$CLIENT_API_BASE/v1/accounts" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"title":"Main EUR","currency":"EUR","companyId":"<uuid>","variantId":"<id>"}'
   
5. Fetch bank details — GET /v1/ext-accounts/{extAccountId}
   Copy

   curl -X GET "$CLIENT_API_BASE/v1/ext-accounts/<extAccountId>" \
     -H "Authorization: Bearer $TOKEN"
   
   GET /account/details/{account} is deprecated. Use /v1/ext-accounts/{extAccountId} instead.
6. Initiate external transfer — POST /v2/transfer
   Copy

   curl -X POST "$CLIENT_API_BASE/v2/transfer" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "amount":"42",
       "from": {"type":"individual","accountId":"<uuid>"},
       "payment": {"method":"sepa","recipient": {"iban":"GB33...","bicSwift":"BUKBGB22","name":"John","surname":"Doe","country":"GB"}}
     }'
   
7. List transactions (cursor) — GET /v1/transactions
   Copy

   curl -X GET "$CLIENT_API_BASE/v1/transactions?accountId=<uuid>&limit=50&sortOrder=descending&lastKey=<cursor>" \
     -H "Authorization: Bearer $TOKEN"
   

​

B) Company onboarding (KYB)

1. List companies — GET /v2/companies
2. Get KYB access token — GET /v2/companies/{companyId}/kyb-access-token
3. Accept contract (company) — POST /v2/companies/contract-accept

​

Crypto features (under Client API)

• List orders (paginated) — GET /crypto-exchange/orders
  Copy

  curl -X GET "$CLIENT_API_BASE/crypto-exchange/orders?pageLimit=10&pageSort=desc&pageKey=<cursor>" \
    -H "Authorization: Bearer $TOKEN"
  
• Get order — GET /crypto-exchange/orders/{orderId} (eventual consistency)
• Create order — POST /crypto-exchange/orders
• Create wallet (external account) — POST /crypto-exchange/wallets
• Create payout (transaction) — POST /crypto-exchange/payouts

​

Status codes & patterns

• 200 OK — successful GET/POST (lists, tokens, reads)
• 201 Created — resource/operation created (transfers, accounts, orders)
• 400 / 403 / 404 — validation/auth/lookup errors
• 500 — server error

• Include Authorization: Bearer <access_token> on every request.
• Set Content-Type: application/json for bodies.
• Prefer cursor pagination (lastKey or pageKey) over offset.
• Prefer new endpoints under /v2 when available.
• Avoid deprecated paths such as /account/details/{account}.

​

Quick reference

​

Next steps

• Configure Cognito (User Pool, Web Client ID, Hosted UI/PKCE) and CORS allow‑lists.
• Use Dev for integration; switch env vars to Prod at go‑live.
• Enable crypto features if required; endpoints will be available under /crypto-exchange.