Users

At Zūm, Users represent the payee for accounts payable, or the payer for accounts receivable. There are 2 ways of ingesting users, API and Portal.

Creating a new user#

Use this endpoint if you want to add a new user to your account.

Method: POST

Endpoint: {{env}}/api/user

tip

In sandbox, to add a bank account for a User, use any valid routing-number. The account-number can be any 5-17 digit number.

Some valid routing numbers that will work on the sandbox environment are:

122000661
026009593
063100277

tip

In sandbox, to add a credit card for a User, use any of the following card numbers.

Mastercard

5102610000000077
5102630000000026

Visa

4000130000000106
4000240000044432
4000230000044433
4000230000048889
4000240000044481
4000230000055587
4000240000044663

Amex

379605170000771

Discover

6011208701111117

Diners

36797342194957

JBC

3587306912123367

tip

In sandbox, to add a debit card for a User, use any of the following card numbers.

Mastercard

5204730820000029

Request (ACH)
Request (Debit Card)
Request (Credit Card)
Response

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "johndoe@zumrails.com",
  "CompanyName": null,
  "PhoneNumber": "5141231234",
  "ClientUserId": "*",
  "IDType": "DL",
  "IDNumber": "12-3456789",
  "IDState": "CA",
  "PaymentInstruments": [
    {
      "RoutingNumber": "122000661",
      "AccountNumber": "1234567890",
      "AccountType": "Checking",
      "AddressLine1": "123 street",
      "AddressLine2": "Apartment 123",
      "AddressPostalCode": "11215",
      "AddressCountry": "USA",
      "AddressCity": "Brooklyn",
      "AddressState": "NY",
      "PaymentMethod": "BankAccount"
    }
  ]
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit Card (Mandatory)	Credit Card (Mandatory)	Description
FirstName	string	conditional	conditional	conditional	User's first name, in case User is an individual. Character limit is 100.
LastName	string	conditional	conditional	conditional	User's last name, in case User is an individual. Character limit is 100.
CompanyName	string	conditional	conditional	conditional	Company name, in case User is a company. Character limit is 100.
Email	string	yes	yes	no	User's e-mail
PhoneNumber	string	yes	no	no	Phone number (maximum 10 characters, no special characters accepted)
ClientUserId	string	no	no	no	External identifier for the user
BusinessTaxId	string	conditional	-	-	Business tax ID, required in case User is a company
IdType	string	conditional	-	-	ID type, can be `DL` or `SSN`
IdNumber	string	conditional	-	-	ID number
IdState	string	conditional	-	-	State where ID was issued
PaymentInstruments		yes	yes	yes	List of payment instruments
PaymentMethod	string	yes	yes	yes	Payment method must be `BankAccount`, `DebitCard` or `CreditCard`
RoutingNumber	string	yes	-	-	Routing number, 9 digits, required when payment method is `BankAccount`
AccountNumber	string	yes	-	-	Account number, 5-17 digits, required when payment method is `BankAccount`
AccountType	string	yes	-	-	Account type, can be either `Checking` or `Savings`, required when payment method is `BankAccount`
Number	string	-	yes	yes	Card number, 16 digits
ExpireMonth	string	-	yes	yes	Card expiry month, 2 digits
ExpireYear	string	-	yes	yes	Card expiry year, 4 digits
Cvv	string	-	-	yes	Card verification number, 3-4 digits, required fir `CreditCard`
AddressLine1	string	-	yes	yes	Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2	string	-	no	no	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	-	yes	yes	Card address postal code
AddressCountry	string	-	yes	yes	Card address country
AddressCity	string	-	yes	yes	Card address city (maximum 32 characters)
AddressState	string	-	yes	yes	Card address state

caution

When creating a user, provide FirstName and LastName if the user is an individual, or provide CompanyName if the user is a business.
When an SSN is provided for a User, then IDNumber should be 9 digits.

info

For credit card payment instruments, it is possible to use cards that were issued outside the US. To consult the list of acceptable countries, click here.

Update user#

Use this endpoint to edit the basic information for an existing user. Include the user id as a path parameter in the URL and the new values in the body payload.

Method: PATCH

Endpoint: {{env}}/api/user/UpdateBasicInformation/{user_id}

note

This endpoint does not update payment instrument for the user.

Request
Response

{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": null,
  "email": "johndoe@zumrails.com",
  "phoneNumber": "5141231234",
  "clientUserId": "*",
  "IdType": "DL",
  "IdNumber": "12-3456789",
  "IdState": "CA"
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit Card (Mandatory)	Credit Card (Mandatory)	Description
FirstName	string	yes	yes	yes	User first name
LastName	string	yes	yes	yes	User last name
CompanyName	string	no	no	no	Company name, in case it's a company
Email	string	yes	yes	no	User e-mail
PhoneNumber	string	yes	no	no	Phone number (maximum 10 characters, no special characters accepted)
ClientUserId	string	no	no	no	External Client User Identifier
BusinessTaxId	string	yes	-	-	Business tax ID, required in case User is a company
IdType	string	yes	-	-	ID type, can be `DL` or `SSN`
IdNumber	string	yes	-	-	ID number
IdState	string	yes	-	-	State where ID was issued

Response

Parameter	Type	Description
id	guid	User id

Add payment instrument#

Use this endpoint to add a payment instrument's information for an existing user. Include the user id as a path parameter in the URL and the new values in the body payload.

Method: POST

Endpoint: {{env}}/api/user/AddPaymentInstrumentInformation/{user_id}

Request (ACH)
Request (Debit Card)
Request (Credit Card)
Response

{
  "AccountType": "Checking",
  "RoutingNumber": "123456789",
  "AccountNumber": "1234567890",
  "AddressLine1": "123 street",
  "AddressLine2": "Apartment 123",
  "AddressPostalCode": "11215",
  "AddressCountry": "USA",
  "AddressCity": "Brooklyn",
  "AddressState": "NY"
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit Card (Mandatory)	Credit Card (Mandatory)	Description
AccountType	string	yes	-	-	Account Type can be either Checking or Savings
RoutingNumber	string	yes	-	-	Routing Number, 9 digits
AccountNumber	string	yes	-	-	Account Number
Number	string	-	yes	yes	Card number, 16 digits
ExpireMonth	string	-	yes	yes	Card expiry month, 2 digits
ExpireYear	string	-	yes	yes	Card expiry year, 4 digits
Cvv	string	-	-	yes	Credit Card verification number, 3-4 digits
AddressLine1	string	yes	yes	yes	Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2	string	no	no	no	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	yes	yes	yes	Card address postal code
AddressCountry	string	yes	yes	yes	Card address country
AddressCity	string	yes	yes	yes	Card address city (maximum 32 characters)
AddressState	string	yes	yes	yes	Card address state

Response

Parameter	Type	Description
payment_instrument_id	guid	Payment Instrument id

Update payment instrument#

Use this endpoint to edit a payment instrument's information for an existing user. Include the user id as a path parameter in the URL and the new values in the body payload.

Method: PATCH

Endpoint: {{env}}/api/user/UpdatePaymentInstrumentInformation/{user_id}/{payment_instrument_id}

Request (ACH)
Request (Debit Card)
Request (Credit Card)
Response

{
  "AccountType": "Checking",
  "RoutingNumber": "123456789",
  "AccountNumber": "1234567890",
  "AddressLine1": "123 street",
  "AddressLine2": "Apartment 123",
  "AddressPostalCode": "11215",
  "AddressCountry": "USA",
  "AddressCity": "Brooklyn",
  "AddressState": "NY"
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit Card (Mandatory)	Credit Card (Mandatory)	Description
AccountType	string	yes	-	-	Account Type can be either Checking or Savings
RoutingNumber	string	yes	-	-	Routing Number, 9 digits
AccountNumber	string	yes	-	-	Account Number
Number	string	-	yes	yes	Card number, 16 digits
ExpireMonth	string	-	yes	yes	Card expiry month, 2 digits
ExpireYear	string	-	yes	yes	Card expiry year, 4 digits
Cvv	string	-	-	yes	Credit Card verification number, 3-4 digits
AddressLine1	string	yes	yes	yes	Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2	string	no	no	no	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	yes	yes	yes	Card address postal code
AddressCountry	string	yes	yes	yes	Card address country
AddressCity	string	yes	yes	yes	Card address city (maximum 32 characters)
AddressState	string	yes	yes	yes	Card address state

Response

Parameter	Type	Description
user_id	guid	User id
payment_instrument_id	guid	Payment Instrument id

Get a specific user#

Use this endpoint to get all the information about a specific user. Include the user id in the URL.

Method: GET

Endpoint: {{env}}/api/user/{user_id}

Response

  {
      "statusCode": 200,
      "message": "GET Request successful.",
      "isError": false,
      "result": {
        "Id": "0bc9894d-....-f691024aca19",
        "CreatedAt": "2022-01-20T17:16:05.166865Z",
        "AccountType": "Personal",
        "Name": "John Doe",
        "FirstName": "John",
        "LastName": "Doe",
        "PhoneNumber": "",
        "Currency": "USD",
        "AggregationRequestId": "15bb883e-e0bb-4a58-9a2c-f8ff234033b4",
        "Customer":{
          "AchProvider": "Fiserv",
          "CompanyEmail":"main.company@zumrails.com",
          "CompanyName": "Main Company Inc",
          "Id": "12345678-1234-1234-1234-123456789123"
        },
        "Email": "john.doe@zumrails.com",
        "IDType": "SSN",
        "IDNumber": "*****1234",
        "PaymentInstruments": [
          {
            "Id": "92142401-d17e-4906-91e8-389ba0d87e75",
            "RoutingNumber": "021000021",
            "AccountNumber": "1001001235",
            "AddressLine1": "123 street",
            "AddressLine2": "Apartment 123",
            "AddressCity": "Brooklyn",
            "AddressState": "NY",
            "AddressPostalCode": "11215",
            "AddressCountry": "USA",
            "AggregationBalance": 500000,
            "AggregationRequestId": "011e4acb-0b9b-4d30-9dfc-f6793fa97eaf",
            "AggregationStatus": "Connected",
            "AllowRefreshBalance": false,
            "PaymentMethod": "BankAccount",
            "BankAccountInformation": {
              "Id": "caeb3477-03ba-4874-a22e-a8e3b9ffa472",
              "Institution": "Zūm Rails Testing Bank",
              "AccountNumber": "4921710685",
              "AccountType": "Personal",
              "BankAccountType": "Checking",
              "RoutingNumber": "021000021",
              "Name": "John Doe",
              "FirstName": "John",
              "LastName": "Doe",              
              "CreatedAt": "2024-07-30T22:48:15.211332Z",
              "AggregationStatus": "Connected",
              "LastTimeRefreshed": "2024-07-30T23:11:49.323567Z",
              "AggregationBalance": 500000,
              "Country": "USA",              
              "AggregationRequestId": "011e4acb-0b9b-4d30-9dfc-f6793fa97eaf"
            }
          },
          {
            "Id": "0f429457-fec9-4c33-b945-3dae92bb10d3",
            "Number": "************8889",
            "ExpireYear": "26",
            "ExpireMonth": "08",
            "AddressLine1": "123 street",
            "AddressLine2": "Apartment 123",
            "AddressCity": "Brooklyn",
            "AddressState": "NY",
            "AddressPostalCode": "11215",
            "AddressCountry": "USA",
            "PaymentMethod": "DebitCard"
          },
          {
            "Id": "1a2b3c4d-fec9-4c33-b945-3dae92bb10d3",
            "Number": "************8596",
            "ExpireYear": "2026",
            "ExpireMonth": "08",
            "AddressLine1": "123 street",
            "AddressLine2": "Apartment 123",
            "AddressCity": "Brooklyn",
            "AddressState": "NY",
            "AddressPostalCode": "11215",
            "AddressCountry": "USA",
            "PaymentMethod": "CreditCard"
          }
        ],
        "TransactionMethodsAvailable": {
          "Ach": true,
          "DebitCard": true,
          "CreditCard": true,
          "CreditCard": true,
          "MoneyTransfer": false
        },
        "ClientUserId": ""
      }
  }

Response

Parameter	Type	Description
Id	guid	User id
CreatedAt	datetime	When the user was created
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
PhoneNumber	string	Last name
Email	string	Last name
ClientUserId	string	External Client User Identifier
BusinessTaxId	string	Business tax ID, required in case User is a company
IdType	string	ID type, can be `DL` or `SSN`
IdNumber	string	Lst 4 digits of the ID number
IdState	string	State where ID was issued
PaymentInstrumentId	string	Payment instrument id
AggregationRequestId	guid	Unique identifier of the aggregation request
Customer
Id	string	Customer id
CompanyName	string	Customer's company name
CompanyEmail	string	Customer's company email
PaymentInstruments
id	string	Payment instrument id
RoutingNumber	string	Routing Number
AccountNumber	string	Account Number
PaymentMethod	string	Payment Method
Number	string	Masked card number with the last 4 digits
ExpireMonth	string	Card expiry month, 2 digits
ExpireYear	string	Card expiry year, 2 digits for `DebitCard` and 4 digits for `CreditCard`
AddressLine1	string	Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2	string	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	Card address postal code
AddressCountry	string	Card address country
AddressCity	string	Card address city (maximum 32 characters)
AddressState	string	Card address state
AggregationBalance	decimal	ACH account current balance
AggregationRequestId	guid	Unique identifier of the aggregation request
AggregationStatus	string	Indicate if the account is Connected
AllowRefreshBalance	Boolean	Indicate if the balance can be refreshed via Aggregation
BankAccountInformation
Id	guid	BankAccountInformation id
AccountNumber	string	Account Number
AccountType	string	Indicate the type of the account (Personal/Business)
AggregationBalance	decimal	ACH account current balance
AggregationRequestId	guid	Unique identifier of the aggregation request
AggregationStatus	string	Indicate if the account is Connected
BankAccountType	string	Indicate the type of the bank account
Country	string	Bank account country
CreatedAt	datetime	When the bank account information was created
Name	string	Full name
FirstName	string	First name
LastName	string	Last name
Institution	string	Institution name
RoutingNumber	string	Routing Number
LastTimeRefreshed	datetime	When the last refresh happened
AggregationFailedReason	string	If failed, informs the failure reason
TransactionsMethodsAvailable
Ach	Boolean	Indicate if this user can do ACH transactions
DebitCard	Boolean	Indicate if this user can do Debit card transactions
CreditCard	Boolean	Indicate if this user can do Credit card transactions
MoneyTransfer	Boolean	Indicate if this user can do money transfer transactions

AggregationStatus

Status	Description
NotConnected	The account is not linked using Zūm Connect
Connected	Account is fully connected and ready to be used
Connecting	Process underway to link account
Refreshing	The account is linked, but the aggregation service is still refreshing/connecting the account.
RefreshFailed	The account was linked but the aggregation service could not refresh the most updated information

info

When a new user is added using Zūm Connect, with financial data aggregation, it might take a few minutes until the account is completely connected. The Field BankAccountInformation. AggregationStatus will indicate when the account is connected. If the response is: Refreshing, call this endpoint again after 30 seconds.

Delete a user#

Use this endpoint to delete a user. Include the user id in the URL.

Method: DELETE

Endpoint: {{env}}/api/user/{user_id}

info

When deleting a user, all transactions already created for the respective user will remain active, but the user's data will be completely erased.

Response

{
  "statusCode": 200,
  "message": "DELETE Request successful.",
  "isError": false,
  "result": ""
}

Search for a user#

Use this endpoint to search for a specific user. Users are returned with pagination, which means that if you need to retrieve all users you need to call the same endpoint incrementing the CurrentPage. This endpoint will not return all user information, if you need to get a specific user information, then you need to call the user/get endpoint.

Method: POST

Endpoint: {{env}}/api/user/filter

Request
Response

{
  "CreatedAtOperator": "isBetween",
  "CreatedAtFrom": "2020-05-13T04:00:00.000Z",
  "CreatedAtTo": "2020-05-13T04:00:00.000Z",
  "UserName": "John Doe",
  "Email": "johndoe@gmail.com",
  "ClientUserIdOperator": "contains",
  "ClientUserId": "*",
  "Pagination": {
    "PageNumber": 1
  }
}

Request parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter users by user name and user email
UserName	string	no	First and/or Last name
CreatedAt	datetime	no	Create date
CreatedAtFrom	datetime	no	Start date (This field is only used when the operator is `IsBetween`)
CreatedAtTo	datetime	no	End date (This field is only used when the operator is `IsBetween`)
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties
Email	string	no	User email
ClientUserId	string	no	External Client User Identifier
ClientUserIdOperator	string	no	Operator to filter with ClientUserId
Pagination		no
PageNumber	number	no	The respective page, starting at 1

Date operators

Type	Description
IsInTheLast	Filter records on or after
ExactlyMatches	Filter records with exact date
IsBetween	Filters records in range
IsAfter	Filter records after date
IsOnOrAfter	Filter records on or after
IsBefore	Filter records before date
IsBeforeOrOn	Filter records before or on date

Response

Parameter	Type	Description
CurrentPage	number	The current page
PageSize	number	The amount of rows returned in the current page
TotalCount	number	The total rows the filter returns
Items		List of users
Id	guid	User id
CreatedAt	datetime	When the user was created
AccountType	datetime	Type of user account
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
Email	string	Email address
PhoneNumber	string	Phone number
Currency	string	Account currency
TransactionMethodsAvailableDescription	string	Description of available transaction methods
ClientUserId	string	External Client User Identifier
IdType	string	ID type, can be `DL` or `SSN`
IdNumber	string	ID number
IdState	string	State where ID was issued
Customer		Associated Customer
Id	string	Customer Id
CompanyName	string	Customer's company name
CompanyEmail	string	Customer's company email
TransactionMethodsAvailable	string	Available transaction methods for user
Ach	bool	Indicate ACH transaction activation state
DebitCard	bool	Indicate Debit card transaction activation state
CreditCard	bool	Indicate Credit card transaction activation state
PaymentInstruments		List of payment instruments
Id	string	Payment instrument id
RoutingNumber	string	Bank account Routing Number
AccountNumber	string	Bank account Account Number
PaymentMethod	string	Payment Method
Number	string	Masked card number with the last 4 digits
ExpireMonth	string	Card expiry month, 2 digits
ExpireYear	string	Card expiry year, 2 digits
AddressLine1	string	Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2	string	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	Card address postal code
AddressCountry	string	Card address country
AddressCity	string	Card address city (maximum 32 characters)
AddressState	string	Card address state

info

We recommend you search for a user, retrieve the user id and then use the GET specific user endpoint to retrieve the detailed information about the user.