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

Request (ACH)
Request (Debit 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",
      "PaymentMethod": "BankAccount"
    }
  ],
  "BillingAddress": {
    "AddressLine1": "123 street",
    "AddressLine2": "Apartment 123",
    "AddressPostalCode": "11215",
    "AddressCountry": "USA",
    "AddressCity": "Brooklyn",
    "AddressState": "NY"
  },
  "ShippingSameAsBilling": false,
  "Addresses": [
    {
      "AddressLine1": "321 street",
      "AddressLine2": "Suite 300",
      "AddressPostalCode": "60504",
      "AddressCountry": "USA",
      "AddressCity": "Aurora",
      "AddressState": "IN",
      "AddressType": "Shipping"
    }
  ]
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit Card (Mandatory)	Description
FirstName	string	yes	yes	User's first name
LastName	string	yes	yes	User's last name
CompanyName	string	no	no	Company name, in case User is a company
Email	string	yes	yes	User's e-mail
PhoneNumber	string	yes	yes	Phone number (maximum 10 characters, no special characters accepted)
ClientUserId	string	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	List of payment instruments
PaymentMethod	string	yes	yes	Payment method must be `BankAccount` or `DebitCard`
RoutingNumber	string	yes	-	Routing number, 9 digits, required when payment method is `BankAccount`
AccountNumber	string	yes	-	Account number, 9-12 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	Card number, 16 digits
ExpireMonth	string	-	yes	Card expiry month, 2 digits
ExpireYear	string	-	yes	Card expiry year, 4 digits
AddressLine1	string	-	yes	Card address line 1 (maximum 30 characters)
AddressLine2	string	-	yes	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	-	yes	Card address postal code
AddressCountry	string	-	yes	Card address country
AddressCity	string	-	yes	Card address city (maximum 32 characters)
AddressState	string	-	yes	Card address state
BillingAddress
AddressLine1	string	yes	-	Billing address line 1 (maximum 30 characters)
AddressLine2	string	yes	-	Billing address line 2 (maximum 30 characters)
AddressPostalCode	string	yes	-	Billing address postal code
AddressCountry	string	yes	-	Billing address country
AddressCity	string	yes	-	Billing address city (maximum 32 characters)
AddressState	string	yes	-	Billing address state
ShippingAddress
AddressLine1	string	no	no	Shipping address line 1 (maximum 30 characters)
AddressLine2	string	no	no	Shipping address line 2 (maximum 30 characters)
AddressPostalCode	string	no	no	Shipping address postal code
AddressCountry	string	no	no	Shipping address country
AddressCity	string	no	no	Shipping address city (maximum 32 characters)
AddressState	string	no	no	Shipping address state

caution

Note that when an SSN is provided for a User, then IDNumber should be 9 digits.

Response

Parameter	Type	Description
Id	guid	User id
FirstName	string	User's first name
LastName	string	User's last name
Email	string	User's e-mail
CompanyName	string	Company name, in case User is a company
PaymentInstruments		List of payment instruments
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
AddressLine1	string	Card address line 1 (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

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)	Description
FirstName	string	yes	yes	User first name
LastName	string	yes	yes	User last name
CompanyName	string	no	no	Company name, in case it's a company
Email	string	yes	yes	User e-mail
PhoneNumber	string	no	no	Phone number (maximum 10 characters, no special characters accepted)
ClientUserId	string	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

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)
Response

{
  "AccountType": "Checking",
  "RoutingNumber": "123456789",
  "AccountNumber": "1234567890"
}

Request parameters

Parameter	Type	ACH (Mandatory)	Debit 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	Card number, 16 digits
ExpireMonth	string	-	yes	Card expiry month, 2 digits
ExpireYear	string	-	yes	Card expiry year, 4 digits
AddressLine1	string	-	yes	Card address line 1 (maximum 30 characters)
AddressLine2	string	-	yes	Card address line 2 (maximum 30 characters)
AddressPostalCode	string	-	yes	Card address postal code
AddressCountry	string	-	yes	Card address country
AddressCity	string	-	yes	Card address city (maximum 32 characters)
AddressState	string	-	yes	Card address state

Response

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

Update billing address#

Use this endpoint to edit the billing address information for a user. Include the user id as a path parameter in the URL and the new address in the body payload.

Method: PATCH

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

Request
Response

{
  "AddressLine1": "123 street",
  "AddressLine2": "Apartment 123",
  "AddressPostalCode": "60504",
  "AddressCountry": "USA",
  "AddressCity": "San Francisco",
  "AddressState": "CA"
}

Request parameters

Parameter	Type	ACH (Mandatory)	Description
AddressLine1	string	yes	Billing address line 1 (maximum 30 characters)
AddressLine2	string	no	Billing address line 2 (maximum 30 characters)
AddressPostalCode	string	yes	Billing address postal code
AddressCountry	string	yes	Billing address country (USA)
AddressCity	string	yes	Billing address city (maximum 32 characters)
AddressState	string	yes	Billing address state

Response

Parameter	Type	Description
id	guid	User id

Update shipping address#

Use this endpoint to edit the shipping address information for a user. Include the user id in the URL and the new address in the body payload.

Method: PATCH

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

info

Provide the boolean flag sameAsBilling to use the billing address as shipping address.

Request
Response

{
  "AddressLine1": "123 street",
  "AddressLine2": "Apartment 123",
  "AddressPostalCode": "60504",
  "AddressCountry": "USA",
  "AddressCity": "San Francisco",
  "AddressState": "CA"
}

Request parameters

Parameter	Type	Ach (Mandatory)	Description
AddressLine1	string	yes	Billing address line 1 (maximum 30 characters)
AddressLine2	string	no	Billing address line 2 (maximum 30 characters)
AddressPostalCode	string	yes	Billing address postal code
AddressCountry	string	yes	Billing address country (USA)
AddressCity	string	yes	Billing address city (maximum 32 characters)
AddressState	string	yes	Billing address state

Response

Parameter	Type	Description
id	guid	User id
sameAsBilling	boolean	Use the billing address as shipping address if true

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",
        "Customer":{
          "AchProvider": "Fiserv",
          "CompanyEmail":"main.company@zumrails.com",
          "CompanyName": "Main Company Inc",
          "Id": "12345678-1234-1234-1234-123456789123"
        }
        "ShippingSameAsBilling": true,
        "Email": "john.doe@zumrails.com",
        "IDType": "SSN",
        "IDNumber": "*****1234",
        "PaymentInstruments": [
          {
            "Id": "92142401-d17e-4906-91e8-389ba0d87e75",
            "RoutingNumber": "021000021",
            "AccountNumber": "1001001235",
            "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"
          }
        ],
        "Addresses": [
          {
              "AddressLine1": "123 street",
              "AddressLine2": "Apartment 123",
              "AddressPostalCode": "60504",
              "AddressCountry": "USA",
              "AddressCity": "San Francisco",
              "AddressState": "CA",
              "AddressType": "Billing"
          }
          {
              "AddressLine1": "123 street",
              "AddressLine2": "Apartment 123",
              "AddressPostalCode": "60504",
              "AddressCountry": "USA",
              "AddressCity": "San Francisco",
              "AddressState": "CA",
              "AddressType": "Shipping"
          }
        ],
        "TransactionMethodsAvailable": {
          "Ach": true,
          "DebitCard": true
        },
        "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
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
AddressLine1	string	Card address line 1 (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
Addresses
AddressLine1	string	Billing address line 1 (maximum 30 characters)
AddressLine2	string	Billing address line 2 (maximum 30 characters)
AddressPostalCode	string	Billing address postal code
AddressCountry	string	Billing address country
AddressCity	string	Billing address city (maximum 32 characters)
AddressState	string	Billing address state
TransactionsMethodsAvailable
Ach	Boolean	Indicate if this user can do ACH transactions
DebitCard	Boolean	Indicate if this user can do Debit 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.

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
ShippingSameAsBilling	bool	Indicate if shipping address is same as billing address
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
Addresses		Empty list of user addresses
TransactionMethodsAvailable	string	Available transaction methods for user
Ach	bool	Indicate ACH transaction activation state
DebitCard	bool	Indicate Debit 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 (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.