Skip to main content
POST
/
v1
/
balances
Create a balance record
curl --request POST \
  --url https://api.wellapp.ai/v1/balances \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "balance",
  "attributes": {
    "local_balance": {
      "opening_booked": "123.32",
      "opening_value": "124.42",
      "closing_booked": "123.32",
      "closing_value": "124.42",
      "currency": "USD"
    },
    "accounting_balance": {
      "opening_booked": "123.32",
      "opening_value": "124.42",
      "closing_booked": "123.32",
      "closing_value": "124.42",
      "currency": "EUR"
    },
    "foreign_exchange": [
      {
        "currency_rate": "1.2546",
        "currency_pair": "EURUSD",
        "currency_rate_source": "European Central Bank",
        "currency_rate_at": "2025-06-01T14:30:00Z"
      },
      {
        "currency_rate": "1.2546",
        "currency_pair": "EURUSD",
        "currency_rate_source": "European Central Bank",
        "currency_rate_at": "2025-06-03T14:30:00Z"
      }
    ],
    "balance_at_from": "2025-06-01T10:00:00Z",
    "balance_at_to": "2025-06-03T10:00:00Z"
  },
  "relationships": {
    "transactions": {
      "data": [
        {
          "type": "transaction",
          "id": "uuid1"
        }
      ]
    },
    "account": {
      "data": {
        "type": "payment_mean",
        "id": "uuid2"
      }
    },
    "workspaces": {
      "data": [
        {
          "type": "workspace",
          "id": "workspace_tenant"
        }
      ]
    }
  }
}'
{
  "type": "balance",
  "id": "balance1",
  "attributes": {
    "local_balance": {
      "opening_booked": "123.32",
      "opening_value": "124.42",
      "closing_booked": "123.32",
      "closing_value": "124.42",
      "currency": "USD"
    },
    "accounting_balance": {
      "opening_booked": "123.32",
      "opening_value": "124.42",
      "closing_booked": "123.32",
      "closing_value": "124.42",
      "currency": "EUR"
    },
    "foreign_exchange": [
      {
        "currency_rate": "1.2546",
        "currency_pair": "EURUSD",
        "currency_rate_source": "European Central Bank",
        "currency_rate_at": "2025-06-01T14:30:00Z"
      }
    ],
    "balance_at_from": "2025-06-01T10:00:00Z",
    "balance_at_to": "2025-06-03T10:00:00Z"
  },
  "relationships": {
    "transactions": {
      "data": [
        {
          "type": "transaction",
          "id": "uuid1"
        }
      ]
    },
    "account": {
      "data": {
        "type": "payment_mean",
        "id": "uuid2"
      }
    },
    "workspaces": {
      "data": [
        {
          "type": "workspace",
          "id": "workspace_tenant"
        }
      ]
    }
  },
  "included": {
    "transaction": [
      {
        "type": "transaction",
        "id": "uuid1",
        "attributes": {
          "scheme": "sepa",
          "external_ids": {
            "transaction_id": "TXN_SEPA_20250601_001",
            "payment_request_id": "PAY_REQ_001",
            "end_to_end_id": "E2E_20250601_ACME_001"
          },
          "requested_execution_date": "2025-06-01",
          "executed_at": "2025-06-01T10:30:00Z",
          "booking_date": "2025-06-01",
          "value_date": "2025-06-01",
          "instructed_amount": {
            "currency": "EUR",
            "amount": 50
          },
          "settlement_amount": {
            "currency": "USD",
            "amount": 54.25
          },
          "foreign_exchange": {
            "currency_rate": "1.0850",
            "currency_pair": "EURUSD",
            "currency_rate_source": "European Central Bank",
            "currency_rate_at": "2025-06-01T10:00:00Z"
          },
          "transaction_type": "transfer",
          "status": "completed",
          "category_purpose": "CBFF",
          "purpose_code": "SALA",
          "remittance_information": {
            "unstructured": "Balance related transaction",
            "structured_reference": "RF18539007547034",
            "reference_type": "SCOR"
          },
          "fees": [
            {
              "type": "transfer_fee",
              "amount": 1.5,
              "currency": "EUR"
            }
          ],
          "created_at": "2025-06-01T10:30:00Z",
          "updated_at": "2025-06-01T10:30:00Z"
        }
      }
    ],
    "account": [
      {
        "type": "payment_means",
        "id": "uuid2",
        "attributes": {
          "type": "account_details",
          "scheme": "ACH",
          "status": "active",
          "account_details": {
            "account_number": "1234567890",
            "routing_number": "021000021",
            "account_type": "checking",
            "currency": "USD"
          },
          "bank_details": {
            "bank_name": "JPMorgan Chase Bank, N.A.",
            "bank_code": "CHASUS33",
            "branch_name": "New York Main Branch",
            "branch_code": "NY001"
          },
          "compliance": {
            "kyc_status": "verified",
            "aml_status": "cleared"
          },
          "nickname": "Main Operating Account",
          "description": "Primary USD account for operations",
          "tags": [
            "usd",
            "operating",
            "primary"
          ],
          "created_at": "2025-06-01T10:00:00Z",
          "updated_at": "2025-06-01T10:00:00Z"
        }
      }
    ],
    "workspaces": [
      {
        "type": "workspace",
        "id": "workspace_tenant",
        "attributes": {
          "name": "Main Workspace",
          "description": "Primary workspace for financial operations",
          "created_at": "2025-06-01T08:00:00Z",
          "updated_at": "2025-06-01T12:00:00Z",
          "avatar_color": "#4A90E2",
          "external_workspace_id": "workspace-001",
          "auto_extract_enabled": true
        }
      }
    ]
  }
}

Headers

Authorization
string
required

Bearer token for authentication

Body

application/json
data
object
required

Response

Balance created successfully

data
object
I