Users
Last updated
Last updated
At Zūm, Users represent the payee for accounts payable, or the payer for accounts receivable. There are 3 ways of ingesting users, API, Portal, and Zūm Connect.
Zūm Rails recommends using Zūm Connect for the below reasons:
For EFT, it offers the end user the possibility to link his bank account, ensuring that the bank account information will be verified to avoid transaction failures.
For Credit Card and Visa Direct, it's required that we reduce your PCI scope.
For more information about Zūm Connect, click here.
Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.
Method: POST
Endpoint: {{env}}/api/user
Request parameters
Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.
Method: POST
Endpoint: {{env}}/api/user
Input parameters
FirstName
string
yes
yes
yes
yes
User's first name, in case User is an individual. Character limit is 100.
LastName
string
yes
yes
yes
yes
User's last name, in case User is an individual. Character limit is 100.
CompanyName
string
yes
yes
yes
yes
Company name, in case User is a company. Character limit is 100.
string
yes
yes
yes
yes
User e-mail
PhoneNumber
string
no
no
no
no
Phone number (maximum 10 characters, no special characters accepted)
ClientUserId
string
no
no
no
no
External Client User Identifier
BankAccountInformation
yes
InstitutionNumber
string
yes
no
no
no
Institution Number, 3 digits
TransitNumber
string
yes
no
no
no
Transit Number, 5 digits
AccountNumber
string
yes
no
no
no
Account Number
CreditCardInformation
yes
yes
Number
string
no
no
yes
yes
ExpireMonth
number
no
no
yes
yes
Card expiry month, 2 digits
ExpireYear
number
no
no
yes
yes
Card expiry year, 4 digits
CVV
string
no
no
yes
yes
Security code, 3 or 4 digits
AddressLine1
string
no
no
yes
no
Billing address line 1 (maximum 60 characters)
AddressLine2
string
no
no
yes
no
Billing address line 2 (maximum 60 characters)
AddressPostalCode
string
no
no
yes
no
Billing address postal code
AddressCountry
string
no
no
yes
no
Billing address country
AddressCity
string
no
no
yes
no
Billing address city (maximum 32 characters)
AddressState
string
no
no
yes
no
Billing address state/province
CAUTION
When creating a user, provide FirstName and LastName if the user is an individual, or provide CompanyName if the user is a business.
CVV and Expire Month/Year are mandatory for all transaction types with the Visa Direct/Credit Card payment methods.
When an SSN is provided for a User, then IDNumber should be 9 digits.
Response (Canada)
id
guid
User id
firstName
string
First name
lastName
string
Last name
companyName
string
Company name, in case it's a company
Use this endpoint if you want to add a new user to your account. Only if you are using a third-party aggregator.
Method: POST
Endpoint: {{env}}/api/user
FirstName*
string
First name, if the User is an individual.
LastName*
string
Last name, if User is an individual. Maximum 100 characters.
CompanyName*
string
Company name, if User is a company. Maximum 100 characters.
Email*
string
Email address
PhoneNumber
string
Phone number. Maximum 10 characters (no special characters).
ClientUserId
string
External identifier for the User.
BankAccountInformation
InstitutionNumber
string
Institution Number, 3 digits
TransitNumber
string
Transit Number, 5 digits
AccountNumber
string
Account Number
CreditCardInformation
Number
string
ExpireMonth
string
Card expiry month, 2 digits.
ExpireYear
string
Card expiry year, 4 digits.
CVV
string
Security code, 3 or 4 digits.
AddressLine1
string
Billing address line 1. Maximum 60 characters.
AddressLine2
string
Billing address line 2. Maximum 60 characters.
AddressCity
string
Billing address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Billing address postal code
AddressCountry
string
Billing address country
Addresses
AddressType
string
??
AddressLine1
string
Shipping address line 1. Maximum 60 characters.
AddressLine2
string
Shipping address line 2. Maximum 60 characters.
AddressCity
string
Shipping address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Shipping address postal code
AddressCountry
string
Shipping address country
Input parameters
FirstName
string
yes
User first name
LastName
string
yes
User last name
string
yes
User e-mail
AuthCode
string
yes
Key used to get an access_code
Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.
Method: POST
Endpoint: {{env}}/api/user
Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.
Method: POST
Endpoint: {{env}}/api/user
Request parameters
FirstName*
string
First name, if the User is an individual.
LastName*
string
Last name, if User is an individual. Maximum 100 characters.
CompanyName*
string
Company name, if User is a company. Maximum 100 characters.
Email*
string
Email address
PhoneNumber
string
Phone number. Maximum 10 characters (no special characters).
ClientUserId
string
External identifier for the User.
BankAccountInformation
InstitutionNumber
string
Institution Number, 3 digits
TransitNumber
string
Transit Number, 5 digits
AccountNumber
string
Account Number
CreditCardInformation
Number
string
ExpireMonth
string
Card expiry month, 2 digits.
ExpireYear
string
Card expiry year, 4 digits.
CVV
string
Security code, 3 or 4 digits.
AddressLine1
string
Billing address line 1. Maximum 60 characters.
AddressLine2
string
Billing address line 2. Maximum 60 characters.
AddressCity
string
Billing address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Billing address postal code
AddressCountry
string
Billing address country
Addresses
AddressType
string
??
AddressLine1
string
Shipping address line 1. Maximum 60 characters.
AddressLine2
string
Shipping address line 2. Maximum 60 characters.
AddressCity
string
Shipping address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Shipping address postal code
AddressCountry
string
Shipping address country
FirstName*
string
First name, if the User is an individual. Maximum 100 characters.
LastName*
string
Last name, if User is an individual. Maximum 100 characters.
CompanyName*
string
Company name, if User is a company. Maximum 100 characters.
Email*
string
Email address
PhoneNumber
string
Phone number. Maximum 10 characters (no special characters).
ClientUserId
string
External identifier for the User.
BusinessTaxId
string
Business tax ID, required in case User is a company.
IdType
string
ID type, can be DL or SSN
IdNumber
string
IdState
string
PaymentInstruments
PaymentMethod
string
Payment method must be BankAccount, DebitCard or CreditCard
RoutingNumber
string
Routing number, 9 digits, required when payment method is BankAccount
AccountNumber
string
Account number, 5-17 digits, required when payment method is BankAccount
AccountType
string
Account type, can be either Checking or Savings, required when payment method is BankAccount
Number
string
ExpireMonth
string
Card expiry month, 2 digits
ExpireYear
string
Card expiry year, 4 digits
Cvv
string
Card verification number, 3-4 digits, required for CreditCard
AddressLine1
string
Card address line 1, 3-30 characters.
AddressLine2
string
Card address line 2, maximum 30 characters.
AddressCity
string
Card address city, maximum 32 characters.
AddressState
string
Card address state
AddressPostalCode
string
Card address postal code
AddressCountry
string
CAUTION
When creating a user, provide FirstName and LastName if the user is an individual, or provide CompanyName if the user is a business.
CVV and Expire Month/Year are mandatory for all transaction types with the Visa Direct/Credit Card payment methods.
When an SSN is provided for a User, then IDNumber should be 9 digits.
Use this endpoint if you want to edit the basic information for an existing user. The user id is informed in the url and the body payload contains the user information. This endpoint does not update the bank account information or the credit card information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBasicInformation/{user_id}
Input parameters (Canada)
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
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
-
-
tate where ID was issued
Response
Parameter
Type
Description
id
guid
User id
Use this endpoint if you want to edit the basic information for an existing user. The user id is informed in the url and the body payload contains the user information. This endpoint does not update the bank account information or the credit card information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBasicInformation/{user_id}
Input parameters (Canada)
FirstName
string
yes
yes
yes
yes
User first name. Character limit is 100.
LastName
string
yes
yes
yes
yes
User last name. Character limit is 100.
CompanyName
string
no
yes
yes
yes
Company name, in case it's a company. Character limit is 100.
string
yes
yes
yes
yes
User e-mail
PhoneNumber
string
no
no
no
no
Phone number (maximum 10 characters, no special characters accepted)
ClientUserId
string
no
no
no
no
External Client User Identifier
Response
id
guid
User id
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 parameters
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
payment_instrument_id
guid
Payment Instrument id
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 parameters
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
user_id
guid
User id
payment_instrument_id
guid
Payment Instrument id
Use this endpoint if you want to edit the bank account information from a user. The user id is informed in the url and the body payload contains the user information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBankAccountInformation/{user_id}
Input parameters
InstitutionNumber
string
yes
Institution Number, 3 digits
TransitNumber
string
yes
Transit Number, 5 digits
AccountNumber
string
yes
Account Number
Response
id
guid
User id
Use this endpoint if you want to edit the credit card billing address information from a user. The user id is informed in the url and the body payload contains the address information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBillingAddressInformation/{user_id}
Note that this endpoint is restricted to Canadian customers.
Input parameters
AddressLine1
string
no
yes
Billing address line 1 (maximum 60 characters)
AddressLine2
string
no
yes
Billing address line 2 (maximum 60 characters)
AddressPostalCode
string
no
yes
Billing address postal code
AddressCountry
string
no
yes
Billing address country (Canada)
AddressCity
string
no
yes
Billing address city (maximum 32 characters)
AddressState
string
no
yes
Billing address state/province
Response
id
guid
User id
Use this endpoint if you want to edit the credit card information for a user. The user id is informed in the url and the body payload contains the user information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateCreditCardInformation/{user_id}
Input parameters
Number
string
yes
yes
ExpireMonth
number
yes
yes
Card expiry month, 2 digits
ExpireYear
number
yes
yes
Card expiry year, 4 digits
CVV
string
yes
yes
Security code, 3 or 4 digits
AddressLine1
string
no
yes
Billing address line 1 (maximum 60 characters)
AddressLine2
string
no
yes
Billing address line 2 (maximum 60 characters)
AddressPostalCode
string
no
yes
Billing address postal code
AddressCountry
string
no
yes
Billing address country (Canada)
AddressCity
string
no
yes
Billing address city (maximum 32 characters)
AddressState
string
no
yes
Billing address state/province
Response
id
guid
User id
Use this endpoint if you want to update the shipping address information from a user. The user id is informed in the url and the body payload contains the address information.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateShippingAddressInformation/{user_id}/{sameAsBilling}
Input parameters
AddressLine1
string
no
yes
shipping address line 1 (maximum 60 characters)
AddressLine2
string
no
yes
shipping address line 2 (maximum 60 characters)
AddressPostalCode
string
no
yes
shipping address postal code
AddressCountry
string
no
yes
shipping address country (Canada)
AddressCity
string
no
yes
shipping address city (maximum 32 characters)
AddressState
string
no
yes
shipping address state/province
Response
id
guid
User id
sameAsBilling
boolean
Use the billing address as shipping address if true
Input parameters
AddressLine1
string
no
yes
shipping address line 1 (maximum 60 characters)
AddressLine2
string
no
yes
shipping address line 2 (maximum 60 characters)
AddressPostalCode
string
no
yes
shipping address postal code
AddressCountry
string
no
yes
shipping address country (Canada)
AddressCity
string
no
yes
shipping address city (maximum 32 characters)
AddressState
string
no
yes
shipping address state/province
Response
id
guid
User id
sameAsBilling
boolean
Use the billing address as shipping address if true
Use this endpoint if you want to get all the information for a specific user. The user id is informed in the url.
Method: GET
Endpoint: {{env}}/api/user/{user_id}
Response
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
string
Last name
ClientUserId
string
External Client User Identifier
LastRefresh
datetime
Last name
AggregationRequestId
guid
Unique identifier of the aggregation request
BankAccountInformation
Institution
string
Institution name
InstitutionNumber
string
Institution Number
TransitNumber
string
Transit Number
AccountNumber
string
Account Number
FirstName
string
Last name
LastName
string
Last name
AggregationStatus
string
Indicate if the account is Connected
LastTimeRefreshed
datetime
When the last refresh happened
AggregationFailedReason
string
If failed, informs the failure reason
AggregationBalance
decimal
EFT account current balance
NameMatch.Score
number
A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result
string
A description of the name-match score. It can be “Matched” or “Not Matched”
CreditCardInformation
Number
string
Last for digits only
ExpireMonth
number
Card expiry month, 2 digits
ExpireYear
number
Card expiry year, 4 digits
CVV
string
Security code, 3 or 4 digits
AddressLine1
string
Billing address line 1 (maximum 60 characters)
AddressLine2
string
Billing address line 2 (maximum 60 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/province
BrandName
string
The brand, Visa, Master, etc.
Institution
string
The institution of the card, valid for Visa Direct when using aggregation
VerifyCreditCardStatus
string
If it is credit card and the card is verified
TransactionsMethodsAvailable
Eft
Boolean
Indicate if this user can do EFT transactions
VisaDirectPull
Boolean
Indicate if this user can do Visa Direct PULL transactions
VisaDirectPush
Boolean
Indicate if this user can do Visa Direct PUSH transactions
Interac
Boolean
Indicate if this user can do Interac transactions
CreditCard
Boolean
Indicate if this user can do Credit Card transactions
AggregationStatus
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
Use this endpoint if you want to delete a user. The user id is informed in the url. When deleting a user, all transactions already created for the respective user will remain active, but the user's data will be completely erased.
Method: DELETE
Endpoint: {{env}}/api/user/{user_id}
Response
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
string
Last name
ClientUserId
string
External Client User Identifier
LastRefresh
datetime
Last name
AggregationRequestId
guid
Unique identifier of the aggregation request
BankAccountInformation
Institution
string
Institution name
InstitutionNumber
string
Institution Number
TransitNumber
string
Transit Number
AccountNumber
string
Account Number
FirstName
string
Last name
LastName
string
Last name
AggregationStatus
string
Indicate if the account is Connected
LastTimeRefreshed
datetime
When the last refresh happened
AggregationFailedReason
string
If failed, informs the failure reason
AggregationBalance
decimal
EFT account current balance
NameMatch.Score
number
A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result
string
A description of the name-match score. It can be “Matched” or “Not Matched”
CreditCardInformation
Number
string
Last for digits only
ExpireMonth
number
Card expiry month, 2 digits
ExpireYear
number
Card expiry year, 4 digits
CVV
string
Security code, 3 or 4 digits
AddressLine1
string
Billing address line 1 (maximum 60 characters)
AddressLine2
string
Billing address line 2 (maximum 60 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/province
BrandName
string
The brand, Visa, Master, etc.
Institution
string
The institution of the card, valid for Visa Direct when using aggregation
VerifyCreditCardStatus
string
If it is credit card and the card is verified
TransactionsMethodsAvailable
Eft
Boolean
Indicate if this user can do EFT transactions
VisaDirectPull
Boolean
Indicate if this user can do Visa Direct PULL transactions
VisaDirectPush
Boolean
Indicate if this user can do Visa Direct PUSH transactions
Interac
Boolean
Indicate if this user can do Interac transactions
CreditCard
Boolean
Indicate if this user can do Credit Card transactions
AggregationStatus
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
Use this endpoint if you want 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
Use this endpoint if you want 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
Date operators
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
Input parameters
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 between)
CreatedAtTo
datetime
no
End date (This field is only used when the operator is between)
CreatedAtOperator
string
no
Operator to filter with CreatedAt properties
string
no
User email
ClientUserId
string
no
External Client User Identifier
ClientUserIdOperator
string
Operator to filter with ClientUserId
Pagination
no
PageNumber
number
no
The respective page, starting at 1
Response
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
FirstName
string
First name
LastName
string
Last name
CompanyName
string
Company name
string
Last name
ClientUserId
string
External Client User Identifier
BankAccountInformation
* if available
LastTimeRefreshed
datetime
Last time the account was refreshed
AggregationStatus
string
Indicates if the account is linked with the aggregation service
AggregationBalance
decimal
Account balance
NameMatch.Score
number
A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result
string
A description of the name-match score. It can be “Matched” or “Not Matched”
Date operators
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
Input parameters
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 between)
CreatedAtTo
datetime
no
End date (This field is only used when the operator is between)
CreatedAtOperator
string
no
Operator to filter with CreatedAt properties
string
no
User email
ClientUserId
string
no
External Client User Identifier
ClientUserIdOperator
string
Operator to filter with ClientUserId
Pagination
no
PageNumber
number
no
The respective page, starting at 1
Response
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
FirstName
string
First name
LastName
string
Last name
CompanyName
string
Company name
string
Last name
ClientUserId
string
External Client User Identifier
BankAccountInformation
* if available
LastTimeRefreshed
datetime
Last time the account was refreshed
AggregationStatus
string
Indicates if the account is linked with the aggregation service
AggregationBalance
decimal
Account balance
NameMatch.Score
number
A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result
string
A description of the name-match score. It can be “Matched” or “Not Matched”
Billing address state/province. .
Shipping address state/province. .
State where ID was issued. .
Card address country. .
Billing address state/province. .
Shipping address state/province. .
State where ID was issued. .
Card address country. .
State where ID was issued. .
Card address country. .