> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Balance > Create a new balance record with local and accounting currency information, foreign exchange rates, and account relationships. ## OpenAPI ````yaml POST /v1/balances openapi: 3.1.0 info: title: Well Document API version: 1.0.0 description: API for uploading and managing financial documents in the Well platform servers: - url: https://api.wellapp.ai security: [] paths: /v1/balances: post: summary: Create a balance record description: >- Create a new balance record with local and accounting currency information, foreign exchange rates, and account relationships. parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BalanceCreateRequest' example: 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 responses: '201': description: Balance created successfully content: application/json: schema: $ref: '#/components/schemas/BalanceCreateResponse' example: 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 '400': description: Bad request - validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized - invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' components: parameters: AuthorizationHeader: name: Authorization in: header required: true schema: type: string description: Bearer token for authentication schemas: BalanceCreateRequest: type: object properties: data: type: object properties: type: type: string enum: - balance attributes: type: object properties: balance_at_from: type: string format: date-time description: Define opening datetime (ISO 8601 UTC) balance_at_to: type: string format: date-time description: Define closing datetime (ISO 8601 UTC) relationships: type: object properties: transactions: $ref: '#/components/schemas/TransactionsRelationshipDataSimple' account: $ref: '#/components/schemas/AccountRelationshipDataSimple' workspaces: $ref: '#/components/schemas/WorkspacesRelationshipDataSimple' required: - account required: - type - attributes - relationships required: - data BalanceCreateResponse: type: object properties: data: type: object properties: type: type: string enum: - balance id: type: string format: uuid attributes: type: object properties: local_balance: type: object properties: opening_booked: type: string opening_value: type: string closing_booked: type: string closing_value: type: string currency: type: string accounting_balance: type: object properties: opening_booked: type: string opening_value: type: string closing_booked: type: string closing_value: type: string currency: type: string foreign_exchange: type: array items: type: object properties: currency_rate: type: string currency_pair: type: string currency_rate_source: type: string currency_rate_at: type: string balance_at_from: type: string balance_at_to: type: string relationships: type: object properties: transactions: $ref: '#/components/schemas/TransactionRelationshipData' account: $ref: '#/components/schemas/AccountRelationshipData' workspaces: $ref: '#/components/schemas/WorkspacesRelationshipData' BadRequestError: type: object properties: code: type: string example: SCHEMA_VALIDATION_ERROR description: Error code identifier status: type: integer example: 400 description: HTTP status code title: type: string example: Validation Error description: Error title message: type: string example: The request is invalid description: Detailed error message details: type: array items: type: object properties: instancePath: type: string description: Path to the invalid field in the request schemaPath: type: string description: Path to the validation rule in the schema keyword: type: string description: Validation keyword that failed params: type: object description: Parameters related to the validation failure message: type: string description: Human-readable validation error message description: Array of detailed validation errors meta: type: object properties: log_id: type: string format: uuid example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b description: Unique identifier for tracking this error in logs required: - log_id required: - code - status - title - message - meta UnauthorizedError: type: object properties: code: type: string example: UNAUTHORIZED description: Error code identifier status: type: integer example: 401 description: HTTP status code title: type: string example: Unauthorized description: Error title message: type: string example: You are not authorized to access this resource description: Detailed error message meta: type: object properties: log_id: type: string format: uuid example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b description: Unique identifier for tracking this error in logs required: - log_id required: - code - status - title - message - meta TransactionsRelationshipDataSimple: type: object properties: data: type: array items: type: object properties: type: type: string enum: - transaction id: type: string AccountRelationshipDataSimple: type: object properties: data: type: object properties: type: type: string enum: - payment_mean id: type: string WorkspacesRelationshipDataSimple: type: object properties: data: type: array items: oneOf: - properties: type: type: string enum: - workspace external_workspace_id: type: string description: External workspace identifier - properties: type: type: string enum: - workspace id: type: string format: uuid description: UUID of the workspace TransactionRelationshipData: type: object properties: data: type: object properties: type: type: string const: transaction description: Resource type identifier id: type: string format: uuid description: Unique identifier for the transaction attributes: type: object properties: scheme: type: string enum: - sepa - swift - ach - faster_payments - instant_credit_transfer description: Payment scheme used for the transaction external_ids: type: object properties: transaction_id: type: string description: External transaction identifier from payment provider payment_request_id: type: string description: Payment request identifier end_to_end_id: type: string description: End-to-end reference for tracing the transaction requested_execution_date: type: string format: date description: Date when transaction execution was requested executed_at: type: string format: date-time description: Timestamp when transaction was executed booking_date: type: string format: date description: Date when transaction was booked value_date: type: string format: date description: Value date of the transaction instructed_amount: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code amount: type: number minimum: 0 description: Amount instructed for the transaction settlement_amount: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code amount: type: number minimum: 0 description: Amount settled for the transaction foreign_exchange: type: object properties: currency_rate: type: string description: Exchange rate applied currency_pair: type: string pattern: ^[A-Z]{6}$ description: Currency pair (e.g., EURUSD) currency_rate_source: type: string description: Source of the exchange rate currency_rate_at: type: string format: date-time description: Timestamp when exchange rate was applied transaction_type: type: string enum: - transfer - direct_debit - card_payment - standing_order - fee description: Type of transaction status: type: string enum: - pending - completed - failed - cancelled - rejected description: Current status of the transaction category_purpose: type: string description: ISO 20022 category purpose code purpose_code: type: string description: ISO 20022 purpose code remittance_information: type: object properties: unstructured: type: string description: Unstructured remittance information structured_reference: type: string description: Structured creditor reference reference_type: type: string enum: - SCOR - RADM - RPIN - FXDR - DISP - PUOR - SCNR description: Type of structured reference fees: type: array items: type: object properties: type: type: string enum: - transfer_fee - exchange_fee - processing_fee - commission description: Type of fee amount: type: number minimum: 0 description: Fee amount currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code created_at: type: string format: date-time description: Timestamp when transaction was created updated_at: type: string format: date-time description: Timestamp when transaction was last updated AccountRelationshipData: type: object properties: data: type: object properties: type: type: string const: payment_means description: Resource type identifier id: type: string format: uuid description: Unique identifier for the payment means attributes: type: object properties: type: type: string enum: - account_details - card_details - wallet_details description: Type of payment means status: type: string enum: - pending - active - inactive - suspended - expired - blocked default: pending description: Current status of payment means account_details: type: object properties: iban: type: string pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}$ description: International Bank Account Number bic: type: string pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ description: Bank Identifier Code account_number: type: string maxLength: 50 description: Local account number sort_code: type: string pattern: ^[0-9]{6}$ description: UK bank sort code routing_number: type: string pattern: ^[0-9]{9}$ description: US bank routing number currency: type: string pattern: ^[A-Z]{3}$ description: Account base currency (ISO 4217) card_details: type: object properties: masked_pan: type: string pattern: ^\*{4}-\*{4}-\*{4}-[0-9]{4}$ description: Masked card number brand: type: string enum: - visa - mastercard - amex - discover - diners - jcb - unionpay description: Card brand card_type: type: string enum: - credit - debit - prepaid - corporate - virtual description: Card type expiry_month: type: integer minimum: 1 maximum: 12 description: Card expiry month expiry_year: type: integer minimum: 2025 description: Card expiry year cardholder_name: type: string maxLength: 100 description: Name on card digital_wallet: type: object properties: provider: type: string enum: - paypal - apple_pay - google_pay - samsung_pay - alipay - wechat_pay description: Wallet provider wallet_id: type: string maxLength: 255 description: Wallet identifier wallet_type: type: string enum: - personal - business - merchant description: Type of wallet account bank_details: type: object properties: bank_name: type: string maxLength: 255 description: Full bank name bank_code: type: string maxLength: 20 description: Bank identifier code branch_name: type: string maxLength: 255 description: Branch name branch_code: type: string maxLength: 20 description: Branch identifier metadata: type: object properties: source: type: string enum: - manual - bank_feed - api - import - sync description: How this payment means was created external_id: type: string maxLength: 255 description: External system identifier compliance: type: object properties: kyc_status: type: string enum: - pending - in_progress - completed - failed - expired description: KYC verification status aml_status: type: string enum: - pending - cleared - flagged - blocked description: AML check status sanctions_check: type: string enum: - pending - passed - flagged - blocked description: Sanctions screening result last_compliance_check: type: string format: date-time description: Last compliance verification timestamp nickname: type: string maxLength: 100 description: User-friendly name description: type: string maxLength: 500 description: Additional description tags: type: array items: type: string description: Custom tags for categorization created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp WorkspacesRelationshipData: type: object properties: data: type: array items: $ref: '#/components/schemas/WorkspaceReference' WorkspaceReference: type: object properties: type: type: string const: workspace attributes: type: object properties: name: type: string description: type: string avatar_color: type: string trusted: type: boolean created_at: type: string format: date-time ````