Account management APIs

Cross River COS provides multiple APIs for managing various types of accounts.

Account management APIs are found in the core module of our COS sandbox, in the DDA section.

Note

Get started with Cross River APIs.

General account management APIs

This table presents general account management APIs that we describe in detail.

Action

API Call

Description
Open a deposit account POST /core/v1/dda/accounts

Creates a DDA account based on the product ID for that type of account. This includes DDA and CD (time deposit) accounts.

Associated webhook events

Webhook reference

Get a list of tax documents

GET /core/v1/dda/accounts/{accountNumber}/tax-documents/

Gets a list of tax documents for a given account, including IDs for each

Get a specific tax document

GET /core/v1/dda/accounts/{accountNumber}/tax-documents/{id}

Retrieves a PDF of a specific tax document
Note

Closed accounts can only be re-opened by the CR Ops teams. To re-open an account please open a support ticket.

Time deposit (CD) APIs

This table presents time deposit (CD) APIs that we describe in detail.

Action

API Call

Description

Request early withdrawal of time deposit

POST /core/v1/dda/accounts/{accountNumber}/time-deposit/early-withdraw

Requests to withdraw the funds from a time deposit account before the account reaches maturity

Request bump up of CD to higher interest rate

 POST /core/v1/dda/accounts/{accountNumber}/time-deposit/bump-up

NOT CURRENTLY OFFERED

Get time deposit (CD) account activity on a specific account

GET /core/v1/dda/accounts/{accountNumber}/time-deposit

Returns information about the account activity of a specific time deposit account

Get the time deposit penalty fee value

GET /core/v1/dda/accounts/{accountNumber}/time-deposit/penalty-fee

Returns the projected penalty fee if you make an early withdrawal to an active time deposit account

Open a deposit account

 /core/v1/dda/accounts

Creates a deposit account based on the product ID for that type of account.

Request attributes

customerId

string

Required  

The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.

The ID is in GUID format.

productId

string

Required  

ID in GUID format of your specific product type on which the account is based. Provided by CR.

title

string

Required  

The name on the account. Usually this is the account holder name, but not always.

255 characters maximum.

statementAddress

object

Required  

Mailing address for paper statement delivery

street1

string

Required  

Primary location details of account holder, for instance, street name, house/building number, PO box.

255 character maximum.

street2

string

Optional 

Additional address information.

255 characters maximum.

street3

string

Optional 

Additional address information.

255 characters maximum.

city

string

Required  

City full name.

255 characters maximum.

state

string

Optional 

State name. We recommend you enter the 2-character state code.

255 characters maximum.

postalCode

string

Required  

Postal code, also known as ZIP code

50 characters maximum.

countryCode

string

Required  

2-letter ISO country code

clientIdentifier

string

Optional 

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

rateCard

string

Optional 

ID of the account's assigned, pre-configured interest rate profile, in GUID format

Response attributes

accountNumber

string

Deposit account number

status

string

Account status:

  • Inactive

  • Active

  • Dormant

  • Escheat

  • Closed

  • ChargeOff

accountType

string

Deposit account type:

  • Checking

  • Savings

  • GeneralLedger

  • Loan

ledgerType

string

Ledger type:

  • Passthrough

  • Direct

classification

string

Deposit account classification:

  • Personal

  • Business

productType

string

Product type associated with the deposit account:

  • GeneralLedger

  • Checking

  • Savings

  • TimeDeposit

  • MoneyMarket

  • CreditCard

  • StoredValue

  • Wallet

  • Unknown

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR.

title

string

The name on the account. Usually this is the account holder name, but not always.

currentBalance

integer

Current balance. A negative amount means a debit and a positive amount means a credit.

holdAmount

integer

Amount of the hold (if any) placed on the deposit account

transactionCount

integer

Total number of transactions posted to the account

availableBalance

integer

Available amount of the balance. A negative amount means a debit and a positive amount means a credit.

creditLimit

integer

Credit limit of the account customer

customerId

string

The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.

The ID is in GUID format.

statementAddress

object

Mailing address for paper statement delivery

street1

string

Primary location details of account holder, for instance, street name, house/building number, PO box.

street2

string

Additional address information.

street3

string

Additional address information.

city

string

City full name.

state

string

State name. We recommend you enter the 2-character state code.

postalCode

string

Postal code, also known as ZIP code

countryCode

string

2-letter ISO country code

openedAt

string

Date and time the deposit account was opened. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

lastMaintenanceAt

string

Date and time the deposit account last had maintenance performed on it. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

lastContactAt

string

Date and time CR last made contact with the deposit account holder. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

lastTransactedAt

string

The date and time a transaction last took place on the deposit account. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

closedAt

string

Date and time the deposit account was closed. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

partnerId

string

Your ID in the CR system. This ID is in GUID format.

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

rateCard

string

ID of the account's assigned, pre-configured interest rate profile, in GUID format

Back to top

Copy

Sample request

curl -X POST 
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
  "customerId": "59e3bc15-bbec-4990-88e9-a9a600d3296c",
  "productId": "44015e68-1afb-40fc-9497-abc1014f52da",
  "title": "Bob Smith",
  "statementAddress": {
    "street1": "123 Any Street",
    "city": "Anywhere",
    "state": "NY",
    "postalCode": "12345",
    "countryCode": "US"
  }
}' 'https://sandbox.crbcos.com/Core/v1/dda/accounts'
Copy

Sample response

{
  "accountNumber": "2348751955",
  "status": "Active",
  "accountType": "Deposit",
  "ledgerType": "Passthrough",
  "classification": "Personal",
  "productType": "Checking",
  "productId": "44015e68-1afb-40fc-9497-abc1014f52da",
  "title": "Bob Smith",
  "currentBalance": 0,
  "holdAmount": 0,
  "transactionCount": 0,
  "availableBalance": 0,
  "creditLimit": 0,
  "customerId": "59e3bc15-bbec-4990-88e9-a9a600d3296c",
  "statementAddress": {
    "street1": "123 Any Street",
    "city": "Anywhere",
    "state": "NY",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "openedAt": "2021-01-26T09:46:10.0931461-05:00",
  "lastMaintenanceAt": "2021-01-26T09:46:10.0931461-05:00",
  "partnerId": "e6c3824a-377f-44d5-a2f6-a9a600c9b37e",
  "lastModifiedAt": "2021-01-26T09:46:10.1011462-05:00"
}

Get tax documents

/core/v1/dda/accounts/{accountNumber}/tax-documents/

Returns a list of the tax documents associated with a specified account based on query criteria. The list includes each document's unique ID, which you need to pull a specific document. The response values below are repeated for each document in the list.

Once you have the document ID use GET /core/v1/dda/accounts/{accountNumber}/tax-documents/{id} to pull an individual document.

Important

Only pull documents as needed. If you want to pull a large number of documents, speak to your Relationship Manager.

Note

The IRS requires Cross River to provide account holders with an IRS Form 1099 for earnings equal to or greater than $10.00, per taxpayer identification number (TIN). Should the customer have more than one account, the system generates a 1099 for each account if the earnings of all accounts total $10.00 or more.

Best practice

Add query parameters to filter the response the API returns to all GET calls.

Use pagination to control presentation of your results.

Query parameters

accountNumber

string

Required  

Number of the customer's account that earns tax-reportable income

Status

string

Optional 

Status of the document in the CR system:

  • Importing

  • Active

  • Recalled

documentType

string

Optional 

Document type the query returns information about:

  • Form1099Int

  • Unknown

year

integer

Optional 

Year the document covers, in the format YYYY

Response attributes

For each document meeting the query criteria, the call returns the following:

id

string

CR system ID of the specific document, in GUID format. Use this ID to get the document in PDF format.

accountNumber

string

The account number used in your request

customerId

string

The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.

The ID is in GUID format.

status

string

Document status in the system:

  • Importing

  • Active

  • Recalled

documentType

string

Document type the query returns information about:

  • Form1099Int

  • Unknown

year

integer

Year the document covers, in the format YYYY

isCorrection

boolean

True if the document is a correction to a previously generated document. Otherwise, false.

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR.

partnerId

string

Your ID in the CR system. This ID is in GUID format.

createdAt

string

When the document was created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm].

recalledAt

string

When the document was recalled, for example for a correction. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm].

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

Back to top

Copy

Request sample

curl -X GET
--header 'Accept: application/json' 
--header 'Authorization: Bearer '<token>'
https://sandbox.crbcos.com/Core/v1/dda/accounts/2000246146/tax-documents
Copy

Response sample

{   "results":
    [



     ],
     "pageNumber": 1,
     "pageSize": 0,
     "hasPreviousPage": false,
     "hasNextPage": false
}

Get a specific tax document

/core/v1/dda/accounts/{accountNumber}/tax-documents/{id}

Gets a specific tax document associated with the account.

Use the Get tax documents endpoint to find out the document IDs.

This call returns a PDF of the specified tax document.

Important

Only pull documents as needed. If you want to pull a large number of documents, speak to your Relationship Manager.

Note

The IRS requires Cross River to provide account holders with an IRS Form 1099 for earnings equal to or greater than $10.00, per taxpayer identification number (TIN). Should the customer have more than one account, the system generates a 1099 for each account if the earnings of all accounts total $10.00 or more.

Path parameters

accountNumber

string

Required  

Number of the customer's account that earns tax-reportable income

id

string

Required  

The document id returned in a GET tax documents query for the specific desired document.

Response attributes

The system responds with a PDF of the specific tax document for display in your app.

Back to top

Copy

Request sample

curl -X GET
--header 'Accept: application/json' 
--header 'Authorization: Bearer '<token>'
https://sandbox.crbcos.com/Core/v1/dda/accounts/2000246146/tax-documents/030f5ebf-316f-41a3-962e-2e9f77e06ca6

Request early withdrawal of time deposit (CD)

/core/v1/dda/accounts/{accountNumber}/time-deposit/early-withdraw

Requests to withdraw the funds from a time deposit (CD) account before the account reaches maturity. Depending on the setting of the waivePenaltyFee attribute, the penalty fee is either waived or not. If the penalty fee for early withdrawal is waived, it is as if the account owner performs a partial withdrawal of funds.

Actual withdrawal of the funds requires a transaction call.

Request attributes

accountNumber

string

Required  

Account number of the time deposit account

waivePenaltyFee

boolean

Required  

If true, a request for early withdrawal will be processed without a penalty fee. Otherwise, false.

Response attributes

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

masterAccountNumber

string

The account number of the time deposit account

status

string

Status of the account:

  • Funding

  • Active

  • Matured

  • EarlyWithdrawal

  • Inactive

minFundingAmount

integer

Minimum dollar amount allowed for the time deposit. If the deposit amount is less than this value the deposit will be rejected.

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

maxFundingAmount

integer

Maximum dollar amount allowed for the time deposit. If the deposit amount is more than this value the deposit will be rejected.

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

autoClose

boolean

True if the time deposit account automatically closes if not sufficiently funded by the funding expiration date. Otherwise, false.

allowBumpUp

boolean

True if the Interest Rates Period tier(s) are enabled, where applicable. Otherwise, false.

waivePenaltyFee

boolean

True if you decide to waive the penalty for early withdrawal. Otherwise, false.

fundingDays

integer

Number of days the time deposit will remain active once opened but not yet funded.

gracePeriodDays

integer

Number of days the customer has to withdraw the time deposit once it reaches maturity. If no action is taken during this time then the time deposit will automatically renew for the same term at the rate currently being offered for the term.

currentRate

number

The current rate of interest being earned by the account

maturityMonths

integer

Number of months until the time deposit reaches maturity

rates

object

Interest rate details

months

integer

Defines the number of months the given rate is valid.

rate

number

Interest rate of the CD

penalties

object

Details of the penalty your customer pays for early withdrawal

months

integer

Early withdrawal within this number of months results in a penalty. CR works with you to configure this number for the CD product.

feeDays

integer

How many days of simple interest to assess

fundingExpDate

string

Based on the product configuration, the date by which the account must be funded. if it isn't funded, it's deactivated. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

fundingDate

string

Date account is funded. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

startDate

string

Date the account starts accruing interest. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

depositAmount

integer

Amount deposited to fund the account

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

depositCurrency

string

Currency the deposit is made using

maturityDate

string

Calendar date when the account can be withdrawn. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

earlyWithdrawnAt

string

Date of early withdrawal. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

rolloverDate

string

Date the time deposit account rolls over (and withdrawal without penalty no longer possible). In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

createdAt

string

Account created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR.

In this case, your configured time deposit product.

partnerId

string

Your ID in the CR system. This ID is in GUID format.

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

Back to top

Copy

Sample request

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
https://sandbox.crbcos.com/Core/v1/dda/accounts/2346008432/time-deposit/early-withdraw'
Copy
Sample response
{
  "masterAccountNumber": "2346008432",
  "status": "EarlyWithdrawal",
  "minFundingAmount": 100000,
  "maxFundingAmount": 20000000,
  "autoClose": true,
  "allowBumpUp": false,
  "waivePenaltyFee": false,
  "fundingDays": 2,
  "gracePeriodDays": 1,
  "currentRate": 2,
  "maturityMonths": 12,
  "rates": [
    {
      "months": 12,
      "rate": 15
    }
 ],
  "penalties": [
    {
      "months": 2,
      "feeDays": 60
    }
],
  "fundingExpDate": "2023-03-25T15:25:01.867-04:00",
  "fundingDate": "2023-03-14T08:46:03.733-04:00",
  "startDate": "2023-06-15T00:00:00-04:00",
  "depositAmount": 20000000,
  "depositCurrency": "usd",
  "maturityDate": "2024-03-15T15:25:01.867-04:00",
  "earlyWithdrawnAt": "2023-06-15T15:30:08.297-04:00",
  "rolloverDate": "2024-03-16T15:25:01.867-04:00",
  "createdAt": "2023-03-14T08:44:14.077-04:00",
  "productId": "23f825d1-fee3-4f93-9254-af38017170e8",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "lastModifiedAt": "2023-06-15T15:30:08.2975921-04:00"
}

Get time deposit (CD) account activity on a specific account

/core/v1/dda/accounts/{accountNumber}/time-deposit

Returns information about the account activity of a specific time deposit account.

Path parameters

accountNumber

string

Required  

The number of the time deposit account

Response attributes

The response attributes for this call are the same as for Request early withdrawal of time deposit.

Back to top

Copy
Sample request
curl -X GET
--header 'Accept: application/json'
--header 'Authorization: Bearer '<token>'
'https://sandbox.crbcos.com/Core/v1/dda/accounts/2991047669/time-deposit'
Copy

Sample response

{
  "masterAccountNumber": "2991047669",
  "status": "Active",
  "minFundingAmount": 100000000,
  "maxFundingAmount": 500000000,
  "autoClose": true,
  "allowBumpUp": true,
  "waivePenaltyFee": false,
  "fundingDays": 7,
  "gracePeriodDays": 7,
  "currentRate": 5,
  "maturityMonths": 12,
  "rates": [
    {
      "months": 2,
      "rate": 5
    },
  ],
  "penalties": [
    {
      "months": 4,
      "feeDays": 30
    },
  ],
  "fundingExpDate": "2023-01-15T08:07:04.233-05:00",
  "depositAmount": 0,
  "depositCurrency": "usd",
  "maturityDate": "2024-01-15T08:07:04.233-05:00",
  "rolloverDate": "2024-01-16T08:07:04.233-05:00",
  "createdAt": "2023-05-15T09:20:03.16-04:00",
  "productId": "0967676f-4d05-4187-9e66-af3801663c6a",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "lastModifiedAt": "2023-05-15T09:21:39.4826016-04:00"
}

Get the time deposit penalty fee value

/core/v1/dda/accounts/{accountNumber}/time-deposit/penalty-fee

Returns the penalty fee if you make an early withdrawal to an active time deposit account. The response will define the number of months during which a penalty will usually be applied on early withdrawal (months), and the number of days of interest to be paid in penalty (feeDays).

Path parameter

accountNumber

string

Required  

Account number of the time deposit account

Response attributes

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

months

integer

Minimum number of months that the time deposit account is closed. A withdrawal before that time results in a penalty fee.

feeDays

integer

Number of days of interest to be paid in penalty for early withdrawal

amount

integer

Penalty amount

currency

string

Currency of the penalty fee

Back to top

Copy

Sample request

curl -X GET
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
https://sandbox.crbcos.com/Core/v1/dda/accounts/2150302897/time-deposit/penalty-fee
Copy

Sample response

{
  "months": 12,
  "feeDays": 45,
  "amount": 1685375,
  "currency": "usd"
}

Associated webhook events

Event Name

Description

Core.Account.Opened

A new account was opened

Core.Account.Status.Changed

Status of an account changed

Core.Account.Closed

Account was closed

Core.Account.Title.Changed

Account title changed

Core.Account.Settled

Account settled

Core.Account.Balance.Changed

Indicates account balance fluctuations

Core.Relationship.Added

Relationship was added to the account

Core.Relationship.Removed

Relationship was removed from the account

Core.Restriction.Placed

Restriction was placed on the account

Core.Restriction.Removed

Restriction was removed for the account

Core.Fee.Assessed

Account fee is under consideration

Core.Fee.Waived

Account fee was waived

Core.Interest.Accrued

Account interest accrued

Core.Interest.Paid

Account interest paid

Core.StopPayment.Placed

Stop payment placed on the account

Core.StopPayment.Removed

Stop payment removed from the account

Core.RegDPolicy.Violated

Reg D was violated on a savings account

Core.Transaction.Completed

Transaction completed successfully

Core.Transaction.Rejected

Transaction was rejected on account

Core.Activity.Posted

Activity was posted to the account

Core.MemoPost.Created

Memo post was created on the account

Core.MemoPost.Changed

Memo post was changed

Core.MemoPost.Removed

Memo post was removed

Core.Hold.Placed

Hold placed on the account

Core.Hold.Changed

Hold status has changed

Core.Hold.Removed

Hold was removed from the account

Back to top

Related topics

Account management overview

Interest rate cards

COS error codes

Tutorials

How to open a deposit account

How to withdraw funds early from a time deposit account (CD)

 

Back to top