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 9-12 digit number.

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

  • 122000661
  • 026009593
  • 063100277
tip

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

Mastercard

  • 5102610000000077
  • 5102630000000026

Visa

  • 4000130000000106
  • 4000240000044432
  • 4000230000044433
  • 4000230000048889
  • 4000240000044481
  • 4000230000055587
  • 4000240000044663
{
"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

ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
FirstNamestringyesyesyesUser's first name
LastNamestringyesyesyesUser's last name
CompanyNamestringnononoCompany name, in case User is a company
EmailstringyesyesnoUser's e-mail
PhoneNumberstringyesnonoPhone number (maximum 10 characters, no special characters accepted)
ClientUserIdstringnononoExternal identifier for the user
BusinessTaxIdstringconditional--Business tax ID, required in case User is a company
IdTypestringconditional--ID type, can be DL or SSN
IdNumberstringconditional--ID number
IdStatestringconditional--State where ID was issued
PaymentInstrumentsyesyesyesList of payment instruments
PaymentMethodstringyesyesyesPayment method must be BankAccount, DebitCard or CreditCard
RoutingNumberstringyes--Routing number, 9 digits, required when payment method is BankAccount
AccountNumberstringyes--Account number, 9-12 digits, required when payment method is BankAccount
AccountTypestringyes--Account type, can be either Checking or Savings, required when payment method is BankAccount
Numberstring-yesyesCard number, 16 digits
ExpireMonthstring-yesyesCard expiry month, 2 digits
ExpireYearstring-yesyesCard expiry year, 4 digits
Cvvstring--yesCard verification number, 3-4 digits, required fir CreditCard
AddressLine1string-yesyesCard address line 1 (maximum 30 characters)
AddressLine2string-nonoCard address line 2 (maximum 30 characters)
AddressPostalCodestring-yesyesCard address postal code
AddressCountrystring-yesyesCard address country
AddressCitystring-yesyesCard address city (maximum 32 characters)
AddressStatestring-yesyesCard address state
caution

Note that 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.

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

Request parameters

ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
FirstNamestringyesyesyesUser first name
LastNamestringyesyesyesUser last name
CompanyNamestringnononoCompany name, in case it's a company
EmailstringyesyesnoUser e-mail
PhoneNumberstringyesnonoPhone number (maximum 10 characters, no special characters accepted)
ClientUserIdstringnononoExternal Client User Identifier
BusinessTaxIdstringyes--Business tax ID, required in case User is a company
IdTypestringyes--ID type, can be DL or SSN
IdNumberstringyes--ID number
IdStatestringyes--State where ID was issued

Response

ParameterTypeDescription
idguidUser 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}

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

Request parameters

ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
AccountTypestringyes--Account Type can be either Checking or Savings
RoutingNumberstringyes--Routing Number, 9 digits
AccountNumberstringyes--Account Number
Numberstring-yesyesCard number, 16 digits
ExpireMonthstring-yesyesCard expiry month, 2 digits
ExpireYearstring-yesyesCard expiry year, 4 digits
Cvvstring--yesCredit Card verification number, 3-4 digits
AddressLine1stringyesyesyesCard address line 1 (maximum 30 characters)
AddressLine2stringnononoCard address line 2 (maximum 30 characters)
AddressPostalCodestringyesyesyesCard address postal code
AddressCountrystringyesyesyesCard address country
AddressCitystringyesyesyesCard address city (maximum 32 characters)
AddressStatestringyesyesyesCard address state

Response

ParameterTypeDescription
user_idguidUser id
payment_instrument_idguidPayment 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}

{
"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",
"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",
"PaymentMethod": "BankAccount",
},
{
"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
},
"ClientUserId": ""
}
}

Response

ParameterTypeDescription
IdguidUser id
CreatedAtdatetimeWhen the user was created
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
PhoneNumberstringLast name
EmailstringLast name
ClientUserIdstringExternal Client User Identifier
BusinessTaxIdstringBusiness tax ID, required in case User is a company
IdTypestringID type, can be DL or SSN
IdNumberstringLst 4 digits of the ID number
IdStatestringState where ID was issued
PaymentInstrumentIdstringPayment instrument id
Customer
IdstringCustomer id
CompanyNamestringCustomer's company name
CompanyEmailstringCustomer's company email
PaymentInstruments
idstringPayment instrument id
RoutingNumberstringRouting Number
AccountNumberstringAccount Number
PaymentMethodstringPayment Method
NumberstringMasked card number with the last 4 digits
ExpireMonthstringCard expiry month, 2 digits
ExpireYearstringCard expiry year, 2 digits for DebitCard and 4 digits for CreditCard
AddressLine1stringCard address line 1 (maximum 30 characters)
AddressLine2stringCard address line 2 (maximum 30 characters)
AddressPostalCodestringCard address postal code
AddressCountrystringCard address country
AddressCitystringCard address city (maximum 32 characters)
AddressStatestringCard address state
TransactionsMethodsAvailable
AchBooleanIndicate if this user can do ACH transactions
DebitCardBooleanIndicate if this user can do Debit card transactions
CreditCardBooleanIndicate if this user can do Credit card transactions

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.

{
"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

{
"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

ParameterTypeMandatoryDescription
GenericSearchstringnoFilter users by user name and user email
UserNamestringnoFirst and/or Last name
CreatedAtdatetimenoCreate date
CreatedAtFromdatetimenoStart date (This field is only used when the operator is IsBetween)
CreatedAtTodatetimenoEnd date (This field is only used when the operator is IsBetween)
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
EmailstringnoUser email
ClientUserIdstringnoExternal Client User Identifier
ClientUserIdOperatorstringnoOperator to filter with ClientUserId
Paginationno
PageNumbernumbernoThe respective page, starting at 1

Date operators

TypeDescription
IsInTheLastFilter records on or after
ExactlyMatchesFilter records with exact date
IsBetweenFilters records in range
IsAfterFilter records after date
IsOnOrAfterFilter records on or after
IsBeforeFilter records before date
IsBeforeOrOnFilter records before or on date

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of users
IdguidUser id
CreatedAtdatetimeWhen the user was created
AccountTypedatetimeType of user account
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
EmailstringEmail address
PhoneNumberstringPhone number
CurrencystringAccount currency
TransactionMethodsAvailableDescriptionstringDescription of available transaction methods
ClientUserIdstringExternal Client User Identifier
IdTypestringID type, can be DL or SSN
IdNumberstringID number
IdStatestringState where ID was issued
CustomerAssociated Customer
IdstringCustomer Id
CompanyNamestringCustomer's company name
CompanyEmailstringCustomer's company email
TransactionMethodsAvailablestringAvailable transaction methods for user
AchboolIndicate ACH transaction activation state
DebitCardboolIndicate Debit card transaction activation state
CreditCardboolIndicate Credit card transaction activation state
PaymentInstrumentsList of payment instruments
IdstringPayment instrument id
RoutingNumberstringBank account Routing Number
AccountNumberstringBank account Account Number
PaymentMethodstringPayment Method
NumberstringMasked card number with the last 4 digits
ExpireMonthstringCard expiry month, 2 digits
ExpireYearstringCard expiry year, 2 digits
AddressLine1stringCard address line 1 (maximum 30 characters)
AddressLine2stringCard address line 2 (maximum 30 characters)
AddressPostalCodestringCard address postal code
AddressCountrystringCard address country
AddressCitystringCard address city (maximum 32 characters)
AddressStatestringCard 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.