Create a Bank Account

Use accounts endpoint to create a bank account

POST to /accounts

This endpoint allows users to create a bank account. It also allows for the ability to associate this newly created account to existing Alloy entities.

HTTP Request: POST https://sandbox.alloy.co/v1/accounts

💡 Important Note: This route does not create Entities

The route will return a bank_account_token if successful. This token is necessary for subsequent calls to GET the account and PATCH the account.

Successful Response Code: 201

Other /accounts routes:

• Return the saved information for the BankAccount based on the bank_account_token:
  • HTTP Request: GET https://sandbox.alloy.co/v1/accounts/{bank_account_token or external_account_id}
• Update fields for the bank account specified by the bank_account_token:
  • HTTP Request: PATCH https://sandbox.alloy.co/v1//accounts/{bank_account_token or external_account_id}
  Please be aware that the request still needs to pass in account_class into the payload, even if it is not updating that field.
  • So, if no entities field is passed in, the entities will not change
  • If an entities field is passed in, all entities will be replaced with the newly passed in entities (Note: if an empty array is passed in entities, all entities will be removed from the Bank Account)

    ---

    Parameter	Type	Description	Validation Details
    account_number*	String	Bank account number associated with entity	Allowed: null, ''
    external_account_id*	String	Unique identifier associated with the account	Max Length: 60
    Allowed: null, ''
    account_type	String	One of 'merchant' or 'person'	Allowed: null, ''
    additional_account_owners	JSON	Array of objects wherein each object represents an additional owner of the account
    additional_account_owners[n].name_first	String	PII for additional account owner
    additional_account_owners[n].name_last	String	PII for additional account owner
    additional_account_owners[n].email_address	String	PII for additional account owner
    additional_account_owners[n].phone_number	String	PII for additional account owner
    additional_account_owners[n].primary_address_line1	String	PII for additional account owner
    additional_account_owners[n].primary_address_line2	String	PII for additional account owner
    additional_account_owners[n].primary_address_city	String	PII for additional account owner
    additional_account_owners[n].primary_address_state	String	PII for additional account owner
    additional_account_owners[n].primary_address_postal_code	String	PII for additional account owner
    additional_account_owners[n].primary_address_country_code	String	PII for additional account owner
    product_code	String	Identifier of the product name	Allowed: null, ''
    product_name	String	Name of the product associated with the account	Allowed: null, ''
    is_linked_account	Boolean	Boolean to determine whether the account is a funding source/linked account
    link_timestamp*	ISO timestamp string	Required when is_linked_account is true	Cannot be future dated
    meta	JSON	JSON object with any meta information related to the account
    meta.additional_account_owners*	JSON	Array of objects wherein each object represents an additional owner of the account. Required when additional_account_owners is used at the top level.
    opening_date	Datetime	UTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was opened	Allowed: null
    maturity_date	Datetime	UTC/ISO dates are both accepted. Strings are converted to ISO timestamps. Date on which the final payment is due on a loan or other financial instrument, such as a bond or term deposit, at which point the principal is due to be paid	Allowed: null
    closing_date	Datetime	UTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was closed	Allowed: null
    account_class*	Enum	Either 'deposit' or 'credit'	Required
    routing_number	String	Routing number associated with the account	Allowed: null, ''
    entities	JSON	Array of objects wherein each object represents an entity linked to the account
    entities[n].entity_token*	String	Alloy entity token - links the entity to the account. Either entity token OR external entity ID are required, not both
    entities[n].external_entity_id*	String	Unique identifier associated with the entity. Either entity token OR external entity ID are required, not both
    entities[n].account_holder_type*	String	Either 'primary' or 'secondary'
    cif_number	String		Allowed: null, ''
    product_number	String		Allowed: null, ''
    card_network	String		Max Length 20
    Allowed: null, ''
    expiration_date	ISO Date		Allowed: null
    tokenization_method	String		Max Length: 20 Allowed: null, ''
    merchant_category_code	String		Max Length: 20 Allowed: null, ''
    name_on_card	String		Max Length: 100
    Allowed: null, ''
    account_number_last4	String		Max Length: 4
    Allowed: null, ''
    avs	String		Max Length: 20
    Allowed: null, ''
    country_code	String	2 letter ISO Code (mainly used for merchant accounts)	Max Length: 2
    Allowed: null, ''
    account_snapshot	JSON	Account Snapshot information	See schema below

    (* denotes required fields)
    

Joining Entities

In the payload, you can link entities in the entities section, for example:

"entities": [
    {
        "account_holder_type": "primary",
        "external_entity_id": "rickPerson01"
    },
    {
        "account_holder_type": "secondary",
        "external_entity_id": "2e09e8c4162e301d27a1b95697cf3d36"
    }
]

This bank account will be linked to two entities.