Product Guides
Accounts

17min
Introduction
Accounts are entities that are involved in transaction in the system. They could be a sender of the money or a destination that receives money. 
Accounts in Nuflow are Entities / counter parties that send money or recieve money (Please do not confuse them with  Bank accounts)
Account category
Customer (usually who send money)
Supplier / Provider or Partner (usually who receive money 
Account Identifiers
Every account should have a unique identifier in the database. Nuflow provides the ability to associate two identfiers with an account:
a) Client Identifier (required)
This is a required identifier which must be provided while creating an account, its usually the same as the identifier in your database.
It's recommended to keep this same or similar to the unique identifier for the entity in your database for easy identification.
Example: 
Customer with database Id 1001 should be created with the same client_identifier (1001) for easy identification.
b) Nuflow Identifier (optional)
This is another identifier which Nuflow associates with an account. This is automatically created by nuflow and used internally within the nuflow platform.  Nuflow recommends that each account identifier have a namespace with a unique UUID/ integer or a string like this: namespace:<unique-id> for readability.
This identifier is optional and is automatically generatedwith the following format category:client_identifierwhere cateogry is the category of the account defined by the user and client_identifieris the unique client identifier defined above.
For example: Customer with client identifier 1001 is created with nuflow_identifier as: "customer:1001"
Nuflow identifiers must respect the following regex pattern ^[a-zA-Z_]+[a-zA-Z0-9_:]*$which means the identifier can:
Include lowercase letters a-z and upper case letters A-Z
Include digits 0-9 but cannot begin with them
Only include _ and : as special characters
Can be extended with all tokens following the same format
Client identifiers can:
Include lowercase and uppercase letters
Include and begin with digits
Only include _ and : as special characters
Examples:
Riders:  Each unique rider could have an identifier like rider:<id> :
rider:001
rider:002
Suppliers with database id's
supplier:55
supplier:56
Merchants with hierarchy
kfc:sg:22
kfc:sg:23
kfc:sg:24
mcd:sg:25
Contractors with UUID's where - are replaced with _
contractor:28a2d474_1fcd_11ee_be56_0242ac120002
Employees:
employee:emp_code_8800
Flexibility and Power
Smart usage of Account identifier can denote a hierarchy as well. Using hierarchy can help you get transactional analytics.
Example: Let's define a hierarchy for a merchant kfc with multiple stores in asia/singapore
kfc:asia
kfc:asia:sg
kfc:asia:sg:store_001
kfc:asia:sg:store_002
kfc:asia:sg:store_003
Note: The account identifier is separated by colon : for a meaningful hierarchy
We highly recommend that you utilise smart account identifiers for a meaningful namespace and a hierarchy.
API's
Base URL
The base URL for all accounts API requests is /api/v1/ops/accounts/
All requests must be authenticated using an API key.
﻿
Get all accounts of the organization.
GET
Params
Query Parameters
limit
optional
Integer
The maximum number of items that may be returned for a single request. It can be thought of as the page size. The default value is 100.
offset
optional
Integer
Specifies the starting point within the collection of resource results. It can be thought of as the page number. The default value is 0.
﻿
﻿
Get an account by its ID. Accounts can be queried by either the client identifier or the nuflow identifier. One of them must be provided.
GET
Params
Query Parameters
client_identifier
optional
String
The client identifier for the account.
nuflow_identifier
optional
String
The nuflow identifier for the account.
﻿
﻿
Create a new account for the organization.
POST
Params
Body Parameters
client_identifier
required
String
Client identifier for the account.
nuflow_identifier
optional
String
Nuflow identifier for the account.
category
required
String
The category of the account. Category can be either one of the following options: Provider, Supplier, Partner, Customer and Others.
account_type
optional
String
The type of the account. This can be either one of the following values: Individual, Business and Others. If not provided then Others is selected as the default option.
kyc_status
optional
String
KYC status of the account. This can be either one of the following values: KYC-Registered, KYC-On-Hold, KYC-Rejected, Not-Available. This is mandaory if category is not Customer.
phone_number
optional
String
Phone number for the account. 
description
optional
String
Description for the account.
billing_emails
optional
Array
Billing emails for the account. Multiple emails can be provided as json list of strings.
bank_details
optional
Array
The bank account details for the account. Values must be provided as objects containing mandatory keys: bank_name, account_name, account_number, swift_code, bank_address, city, state, postal_code and country_iso3 which is the country code as per the ISO3 standard. 
﻿
﻿
Update an existing account. Note that all values except the client identifier and the nuflow identifier will be overridden exactly as provided in the payload. If no values are provided for the optional parameters then existing values will be deleted.
PATCH
Params
Body Parameters
client_identifier
optional
String
Client identifier for the account. Either the client identifier or the nuflow identifier must be provided.
nuflow_identifier
optional
String
Nuflow identifier for the account.
category
required
String
The category of the account. Category can be either one of the following options: Provider, Supplier, Partner, Customer and Others.
account_type
optional
String
The type of the account. This can be either one of the following values: Individual, Business and Others. If not provided then Others is selected as the default option.
kyc_status
optional
String
KYC status of the account. This can be either one of the following values: KYC-Registered, KYC-On-Hold, KYC-Rejected, Not-Available. This is mandaory if category is not Customer.
phone_number
optional
String
Phone number for the account. 
description
optional
String
Description for the account.
billing_emails
optional
Array
Billing emails for the account. Multiple emails can be provided as a comma separated list.
bank_details
optional
Array
The bank account details for the account. Values must be provided as objects containing mandatory keys: bank_name, account_name, account_number, swift_code, bank_address, city, state, postal_code and country_iso3 which is the country code as per the ISO3 standard. 
﻿
﻿
Bulk APIs
Accounts can be created and updated in bulk using the bulk API endpoints. The error respone for the bulk apis also provides the index of the object which led to the error through the index key in the detaillist.
Currently, only commit all or none strategy is supported by the bulk APIs which means either all the accounts will be created/updated or none of them will in case of an error.
﻿
Create accounts in bulk. If any object in the payload has identifiers associated with an already exisiting account then that account will get updated with the details provided in the new object.
POST
Params
Body Parameters
strategy
optional
String
Commit strategy for the bulk api. Default value is "commit_all_or_none". Support for commit few will be added in the future.
data
required
Array
List of objects with account details. Each object follows the create account schema.
﻿
﻿
Update accounts in bulk.
PATCH
Params
Body Parameters
strategy
optional
String
Commit strategy for the bulk api. Default value is "commit_all_or_none". Support for commit few will be added in the future.
data
required
Array
List of objects with account details. Each object follows the update account schema.
﻿
﻿