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)
      ParameterTypeDescriptionValidation Details
      account_number*StringBank account number associated with entityAllowed: null, ''
      external_account_id*StringUnique identifier associated with the accountMax Length: 60
      Allowed: null, ''
      account_typeStringOne of 'merchant' or 'person'Allowed: null, ''
      additional_account_ownersJSONArray of objects wherein each object represents an additional owner of the account
      additional_account_owners[n].name_firstStringPII for additional account owner
      additional_account_owners[n].name_lastStringPII for additional account owner
      additional_account_owners[n].email_addressStringPII for additional account owner
      additional_account_owners[n].phone_numberStringPII for additional account owner
      additional_account_owners[n].primary_address_line1StringPII for additional account owner
      additional_account_owners[n].primary_address_line2StringPII for additional account owner
      additional_account_owners[n].primary_address_cityStringPII for additional account owner
      additional_account_owners[n].primary_address_stateStringPII for additional account owner
      additional_account_owners[n].primary_address_postal_codeStringPII for additional account owner
      additional_account_owners[n].primary_address_country_codeStringPII for additional account owner
      product_codeStringIdentifier of the product nameAllowed: null, ''
      product_nameStringName of the product associated with the accountAllowed: null, ''
      is_linked_accountBooleanBoolean to determine whether the account is a funding source/linked account
      link_timestamp*ISO timestamp stringRequired when is_linked_account is trueCannot be future dated
      metaJSONJSON object with any meta information related to the account
      meta.additional_account_owners*JSONArray of objects wherein each object represents an additional owner of the account. Required when additional_account_owners is used at the top level.
      opening_dateDatetimeUTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was openedAllowed: null
      maturity_dateDatetimeUTC/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 paidAllowed: null
      closing_dateDatetimeUTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was closedAllowed: null
      account_class*EnumEither 'deposit' or 'credit'Required
      routing_numberStringRouting number associated with the accountAllowed: null, ''
      entitiesJSONArray of objects wherein each object represents an entity linked to the account
      entities[n].entity_token*StringAlloy entity token - links the entity to the account. Either entity token OR external entity ID are required, not both
      entities[n].external_entity_id*StringUnique identifier associated with the entity. Either entity token OR external entity ID are required, not both
      entities[n].account_holder_type*StringEither 'primary' or 'secondary'
      cif_numberStringAllowed: null, ''
      product_numberStringAllowed: null, ''
      card_networkStringMax Length 20
      Allowed: null, ''
      expiration_dateISO DateAllowed: null
      tokenization_methodStringMax Length: 20 Allowed: null, ''
      merchant_category_codeStringMax Length: 20 Allowed: null, ''
      name_on_cardStringMax Length: 100
      Allowed: null, ''
      account_number_last4StringMax Length: 4
      Allowed: null, ''
      avsStringMax Length: 20
      Allowed: null, ''
      country_codeString2 letter ISO Code (mainly used for merchant accounts)Max Length: 2
      Allowed: null, ''
      account_snapshotJSONAccount Snapshot informationSee 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.