Xflow Addresses API

openapi: 3.0.0
info:
  contact:
    email: support@xflowpay.com
    name: Xflow Support
    url: https://xflowpay.com
  description: The Xflow REST API. Please see https://docs.xflowpay.com/2024-02-05/api for more details.
  termsOfService: https://docs.xflowpay.com/platform-agreement
  title: Xflow Accounts Addresses API
  version: '2024-02-05'
servers:
- url: https://api.xflowpay.com/
security:
- bearerAuth: []
tags:
- name: Addresses
paths:
  /v1/addresses:
    get:
      description: Returns a list of addresses.
      operationId: ListAddresses
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - description: Xflow categorization of destination (for a store of value).
        in: query
        name: category
        required: false
        schema:
          items:
            enum:
            - partner_payment
            - user_payout
            - xflow_checkout
            - xflow_fee_advance
            - xflow_receive
            type: string
          type: array
      - description: Return results where the `created` field is equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.eq
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
        in: query
        name: currency
        required: false
        schema:
          items:
            type: string
          type: array
      - description: A cursor for use in pagination. `ending_before` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          type: string
      - description: Indicates whether the addressable is reusable for ACH debit.
        in: query
        name: is_reusable
        required: false
        schema:
          type: boolean
      - description: A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Unique identifier of an account object associated with this address.
        in: query
        name: linked_id
        required: false
        schema:
          type: string
      - description: A cursor for use in pagination. `starting_after` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with `obj_bar`, your subsequent call can include `starting_after=obj_bar` in order to fetch the next page of the list.
        in: query
        name: starting_after
        required: false
        schema:
          type: string
      - description: Valid status types associated with an address.
        in: query
        name: status
        required: false
        schema:
          items:
            enum:
            - activated
            - deactivated
            - expired
            - pending_deactivation
            type: string
          type: array
      - description: Type of destination (for a store of value).
        in: query
        name: type
        required: false
        schema:
          items:
            enum:
            - bank_account
            - wallet
            type: string
          type: array
      - description: This can be `affirm`, `afterpay`, `klarna` or `paypal_external`.
        in: query
        name: wallet.provider
        required: false
        schema:
          items:
            enum:
            - affirm
            - afterpay
            - klarna
            - paypal_external
            type: string
          type: array
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/address'
                    type: array
                  has_next:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  object:
                    description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
                    enum:
                    - list
                    type: string
                title: ListAddressesResponse
                type: object
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Addresses
    post:
      description: Create an address.
      operationId: CreateAddress
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                bank_account:
                  description: Bank account details.
                  properties:
                    bank_name:
                      description: Name of the bank where the account is opened.
                      type: string
                    domestic_credit:
                      description: Represents the prefix associated with the bank account for a local ACH credit.
                      type: string
                    number:
                      description: Unique bank account number.
                      type: string
                  title: CreateAddressRequestBankAccount
                  type: object
                billing_details:
                  description: Billing address.
                  properties:
                    city:
                      description: City details in the official address.
                      type: string
                    country:
                      description: Country details in the [ISO 3166-1 alpha 2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) in uppercase.
                      enum:
                      - IN
                      type: string
                    line1:
                      description: Line 1 in the official address.
                      type: string
                    line2:
                      description: Line 2 in the official address.
                      type: string
                    postal_code:
                      description: Postal code in the official address.
                      type: string
                    state:
                      description: State details in the official address.
                      type: string
                  title: CreateAddressRequestBillingDetails
                  type: object
                category:
                  description: Xflow categorization of destination (for a store of value).
                  enum:
                  - user_payout
                  - xflow_receive
                  type: string
                currency:
                  description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                  enum:
                  - INR
                  - AED
                  - AUD
                  - CHF
                  - CZK
                  - DKK
                  - EUR
                  - GBP
                  - HKD
                  - INR
                  - NOK
                  - PLN
                  - SEK
                  - SGD
                  - USD
                  type: string
                linked_id:
                  description: Unique identifier of an account object associated with this address.
                  type: string
                linked_object:
                  description: The type of object that this address object is associated with. This can only be `account` for now.
                  enum:
                  - account
                  type: string
                metadata:
                  additionalProperties:
                    type: string
                  description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
                  title: CreateAddressRequestMetadata
                  type: object
                name:
                  description: Name on the destination (for a store of value).
                  type: string
                supporting_documentation:
                  description: Documents required to prove the authenticity of this destination (for a store of value).
                  properties:
                    id_document:
                      description: A [file object identifier](https://docs.xflowpay.com/2024-02-05/api#file_object_id) which references a document that identifies this destination (for a store of value).
                      type: string
                  title: CreateAddressRequestSupportingDocumentation
                  type: object
                type:
                  description: Type of destination (for a store of value). This can only be a `bank_account` for now.
                  enum:
                  - bank_account
                  type: string
              required:
              - category
              - currency
              - linked_id
              - linked_object
              title: CreateAddressRequest
              type: object
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/address'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Addresses
  /v1/addresses/{address}:
    get:
      description: Retrieves the details of an address.
      operationId: RetrieveAddress
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: address
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/address'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Addresses
    post:
      description: Update the details of an address.
      operationId: UpdateAddress
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: address
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              properties:
                metadata:
                  additionalProperties:
                    type: string
                  description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
                  title: UpdateAddressRequestMetadata
                  type: object
              title: UpdateAddressRequest
              type: object
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/address'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Addresses
components:
  schemas:
    address:
      description: Address objects represent a destination (for a store of value), which is usually an Xflow account.
      properties:
        bank_account:
          description: Bank account details.
          properties:
            bank_name:
              description: Name of the bank where the account is opened.
              nullable: true
              type: string
            domestic_credit:
              description: Represents the prefix associated with the bank account for a local ACH credit.
              nullable: true
              type: string
            domestic_debit:
              description: Represents the prefix associated with the bank account for a local ACH debit.
              nullable: true
              type: string
            domestic_fast_credit:
              description: Represents the prefix associated with the bank account for fast local ACH credit.
              nullable: true
              type: string
            domestic_wire:
              description: Represents the prefix (if any) associated with the bank account for a domestic wire.
              nullable: true
              type: string
            global_wire:
              description: Represents the Business Identifier Code (BIC) associated with the bank account.
              nullable: true
              type: string
            iban:
              description: Represents the International Bank Account Number (IBAN) associated with the bank account.
              nullable: true
              type: string
            last4:
              description: Last 4 digits of the bank account number.
              type: string
            number:
              description: Unique bank account number.
              type: string
          title: AddressBankAccount
          nullable: true
          type: object
        billing_details:
          description: Billing address.
          properties:
            city:
              description: City details in the official address.
              nullable: true
              type: string
            country:
              description: Country details in the [ISO 3166-1 alpha 2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) in uppercase.
              enum:
              - IN
              type: string
            line1:
              description: Line 1 in the official address.
              nullable: true
              type: string
            line2:
              description: Line 2 in the official address.
              nullable: true
              type: string
            postal_code:
              description: Postal code in the official address.
              nullable: true
              type: string
            state:
              description: State details in the official address.
              nullable: true
              type: string
          title: AddressBillingDetails
          nullable: true
          type: object
        category:
          description: Xflow categorization of destination (for a store of value).
          enum:
          - partner_payment
          - user_payout
          - xflow_checkout
          - xflow_fee_advance
          - xflow_receive
          type: string
        created:
          description: The seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) at which the address object was created.
          format: unix-time
          type: integer
        currency:
          description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
          enum:
          - INR
          - AED
          - AUD
          - CHF
          - CZK
          - DKK
          - EUR
          - GBP
          - HKD
          - INR
          - NOK
          - PLN
          - SEK
          - SGD
          - USD
          type: string
        id:
          description: Unique identifier for the object.
          type: string
        is_reusable:
          description: Indicates whether the address is reusable for ACH debit.
          type: boolean
        linked_id:
          description: Unique identifier of an account object associated with this address.
          type: string
        linked_object:
          description: The type of object that this address object is associated with. This can only be `account` for now.
          enum:
          - account
          type: string
        livemode:
          description: Has the value true if the object exists in `livemode` or the value false if the object exists in `testmode`.
          type: boolean
        metadata:
          additionalProperties:
            type: string
          description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          title: AddressMetadata
          nullable: true
          type: object
        name:
          description: Name on the destination (for a store of value).
          nullable: true
          type: string
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - address
          type: string
        status:
          description: Valid status types associated with an address.
          enum:
          - activated
          - deactivated
          - expired
          - pending_deactivation
          type: string
        supporting_documentation:
          description: Documents required to prove the authenticity of this destination (for a store of value).
          properties:
            id_document:
              description: A [file object identifier](https://docs.xflowpay.com/2024-02-05/api#file_object_id) which references a document that identifies this destination (for a store of value).
              type: string
          title: AddressSupportingDocumentation
          nullable: true
          type: object
        type:
          description: Type of destination (for a store of value). This can be `bank_account` or `wallet`.
          enum:
          - bank_account
          - wallet
          type: string
        wallet:
          description: Wallet details.
          properties:
            email:
              description: Email registered with the wallet provider.
              nullable: true
              type: string
            provider:
              description: This can be `affirm`, `afterpay`, `klarna` or `paypal_external`.
              enum:
              - affirm
              - afterpay
              - klarna
              - paypal_external
              nullable: true
              type: string
          title: AddressWallet
          nullable: true
          type: object
      title: Address
      type: object
    error_object:
      description: 'Xflow uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.). Codes in the `5xx` range indicate an error with Xflow’s servers (these are rare).'
      properties:
        errors:
          description: An array of errors. Each element is a specific error.
          maxItems: 1
          minItems: 1
          items:
            properties:
              code:
                description: Enum value specific to the error. All Xflow error codes are defined [here](https://docs.xflowpay.com/latest/errors).
                enum:
                - account_activation_failed_missing_payout_address
                - account_activation_failed_missing_person
                - account_activation_failed_incorrect_number_of_persons
                - account_activation_failed_incorrect_relationship_for_person
                - account_email_invalid
                - account_id_invalid
                - account_not_unique_nickname
                - account_parameter_not_editable
                - account_partner_activate_disallowed
                - account_partner_deactivate_disallowed
                - account_platform_activate_disallowed
                - account_platform_create_disallowed
                - account_setting_parameter_not_editable
                - account_status_invalid
                - account_type_invalid
                - account_update_access_unauthorized
                - account_user_activate_disallowed
                - account_user_create_disallowed
                - action_invalid
                - action_not_enabled
                - action_unauthorized
                - address_cannot_be_deactivated
                - address_category_mismatch
                - address_category_not_allowed
                - address_domestic_credit_invalid
                - address_global_wire_invalid
                - address_global_wire_not_supported
                - address_parameter_not_editable
                - address_type_not_allowed
                - balance_insufficient
                - cancelled_request
                - country_code_invalid
                - country_code_not_supported
                - currency_amount_mismatch
                - currency_not_supported
                - date_invalid_format
                - deposit_account_address_mismatch
                - deposit_account_id_mismatch
                - deposit_parameter_not_editable
                - duplicate_currencies_not_supported
                - duplicate_values_found
                - event_type_invalid
                - fee_plan_parameter_not_editable
                - file_name_invalid
                - file_name_length_invalid
                - file_parameter_not_editable
                - file_purpose_mismatch
                - file_size_limit_exceeded
                - file_request_body_invalid
                - file_type_unsupported
                - header_parameter_invalid
                - header_parameter_missing
                - http_parameter_invalid
                - invalid_amount
                - invoice_date_invalid
                - invoice_due_date_invalid
                - metadata_count_exceeded
                - metadata_key_max_length_invalid
                - metadata_key_min_length_invalid
                - metadata_value_max_length_invalid
                - metadata_value_min_length_invalid
                - multiple_xflow_receive_same_category_not_allowed
                - minimum_required_values_not_present
                - object_not_found
                - parameter_address_invalid
                - parameter_character_invalid
                - parameter_empty
                - parameter_file_invalid
                - parameter_max_length_invalid
                - parameter_min_length_invalid
                - parameter_range_invalid
                - parameter_receivable_invalid
                - parameter_unexpected
                - parameter_value_invalid
                - payment_link_account_receivable_mismatch
                - payment_link_activate_disallowed
                - payment_link_deactivate_invalid
                - payment_link_expire_invalid
                - payment_link_extend_disallowed
                - payment_link_extend_invalid
                - payment_link_non_us_account_non_usd_currency
                - payment_link_parameter_not_editable
                - payment_link_receivable_count_exceed
                - payment_link_receivable_status_invalid
                - payout_parameter_not_editable
                - person_delete_not_allowed
                - person_parameter_not_editable
                - person_relationship_not_set
                - person_update_not_allowed
                - purpose_code_not_supported
                - receivable_additional_info_required
                - receivable_amount_invoice_amount_mismatch
                - receivable_amount_maximum_reconcilable_incorrect
                - receivable_cancel_disallowed
                - receivable_confirm_action_disallowed
                - receivable_creation_date_invoice_creation_date_mismatch
                - receivable_currency_invoice_currency_mismatch
                - receivable_due_date_invoice_due_date_mismatch
                - receivable_hold
                - receivable_invoice_document_incorrect
                - receivable_invoice_reference_number_exists
                - receivable_invoice_transaction_type_incorrect
                - receivable_parameter_not_editable
                - receivable_partner_country_invoice_partner_country_mismatch
                - receivable_partner_invoice_partner_mismatch
                - receivable_reconcile_action_disallowed
                - receivable_reconcile_amount_exceed
                - receivable_reference_number_invoice_reference_number_mismatch
                - receivable_unable_to_process
                - receivable_update_access_unauthorized
                - request_body_invalid
                - request_query_parameter_invalid
                - resource_locked
                - secret_key_invalid
                - secret_key_missing
                - testmode_action_only
                - timestamp_invalid
                - transfer_failed
                - transfer_parameter_not_editable
                - transfer_type_invalid
                - url_invalid
                - webhook_endpoint_limit_exceeded
                - webhook_endpoint_parameter_not_editable
                - website_invalid
                type: string
              message:
                description: Description of the error with guidance on how to recover.
                type: string
              metadata:
                additionalProperties:
           

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xflow/refs/heads/main/openapi/xflow-addresses-api-openapi.yml