Create Person Customer

post

https://api.cloud.mbanq.com/v1/clients

Seamlessly initiate the journey for new individual customers with this robust registration endpoint. Designed as the foundational step of the Mbanq onboarding lifecycle, it captures essential personal profiles and securely initializes them in a Pending state. By establishing this record, you unlock a streamlined path toward identity verification, compliance approval, and full banking activation.

The Onboarding Journey:

Registration: Establish the customer's digital record as a precursor to all banking services.
Verification: Following creation, ensure that at least one primary address, an identity document, a mobile number, and an email are added. Then, utilize the Verify Customer API to validate these credentials. A successful verification transitions the record to a Verified state.
Activation: Successful verification transitions the customer to an active state, enabling downstream operations like account opening and fund transfers.

Real-time Lifecycle Visibility

To maintain precise synchronization with the asynchronous onboarding process, we strongly recommend subscribing to our real-time webhooks. These provide immediate notifications for creation events, verification results, and state transitions, serving as the most efficient way to monitor progress.

Function	Webhook Reference
Create Customer	Register Customer Webhook

For a complete overview of the end-to-end integration sequence, please refer to the Customer Onboarding Guide.

Using Template Option IDs

Several fields in this request payload require IDs that are obtained from the Get Person Customer Template API. You must call the Person Customer Template API first to retrieve the valid option IDs for your tenant before creating a customer.

The following fields require template option IDs:

Field in Request Body	Source from Person Customer Template Response
`officeId`	`officeOptions[].id`
`genderId`	`genderOptions[].id`
`clientTypes[]`	`clientTypeOptions[].id`
`clientClassificationId`	`clientClassificationOptions[].id`
`staffId`	`staffOptions[].id`
`occupationId`	`clientOccupationOptions[].id`
`nationalityId`	`nationalityOptions[].id`

Example: If the template returns genderOptions: [{ "id": 634, "name": "Male" }, { "id": 635, "name": "Female" }]. To create a male customer, pass "genderId": 634 in this request body.

Click to View Person Request Payload Fields

Field name	Data type	Mandatory / optional	Length constraints	Validation pattern (regex)
officeId	Integer	Mandatory (Default 1)	-	`^\d+$`
firstname	String	Mandatory	Max 100	`^[a-zA-Z'-\u00C0-\u017F\s]*$`
lastname	String	Mandatory	Max 100	`^[a-zA-Z'-\u00C0-\u017F\s]*$`
mobileCountryCode	String	Mandatory	-	-
mobileNo	String	Mandatory	-	`^\d+$`
emailAddress	String	Mandatory	-	`^\S+@\S+\.\S+$`
dateFormat	String	Mandatory if submittedOnDate is passed	-	-
externalId	String	Optional	-	`^\d+$`
middlename	String	Optional	-	`^[a-zA-Z]+$`
nickname	String	Optional	Max 50	-
dateOfBirth	String	Optional	-	-
genderId	Integer	Optional	-	`^(634\|635\|636)$`
nationalityId	Integer	Optional	-	`^\d+$`
locale	String	Optional	-	-
occupationId	Integer	Optional	-	`^\d+$`
isCurrentlyEmployed	Boolean	Optional	-	-
clientTypes	Array (Integer)	Optional	-	-
clientClassificationId	Integer	Optional	-	`^\d+$`
isStaff	Boolean	Optional	-	-
staffId	Integer	Optional	-	`^\d+$`
isOptedForMLAStatus	Boolean	Optional	-	-
currentMLAStatus	String	Optional	-	`^[YN]$`
address	Array (Object)	Optional	-	-
submittedOnDate	String	Optional	-	-

Click to View Address Fields (nested in address array)

Field name	Data type	Mandatory / optional	Length constraints	Validation pattern (regex)
addressTypeId	Integer	Mandatory	-	`^(31\|32\|33\|34)$`
addressLine1	String	Optional	Max 255	-
addressLine2	String	Optional	Max 255	-
addressLine3	String	Optional	Max 255	-
city	String	Optional	-	`[a-zA-Z- ]+`
stateProvinceId	Integer	Optional	-	`^\d+$`
countryId	Integer	Optional	-	`^\d+$`
postalCode	String	Optional	Max 255	`^\d+$`
isActive	Boolean	Optional	-	-

Body Params

firstname

string

required

length ≤ 100

Defaults to John

The first name of the customer. Example: 'John'

lastname

string

required

length ≤ 100

Defaults to Doe

The last name of the customer. Example: 'Doe'

dateOfBirth

string

The date of birth. The date format should be as per the format mentioned in the dateFormat parameter. Example: '20 February 1999'

mobileCountryCode

string

required

Defaults to +1

The mobile country code. Validation is enforced. Example: '+1'

mobileNo

string

required

Defaults to 5550198221

The mobile number of the customer. Validation is enforced. Example: '5550198221'

emailAddress

string

required

Defaults to [email protected]

The email address of the customer. Email Format Validation is enforced. Example: '[email protected]'

officeId

integer

required

Defaults to 1

The associated office Id. '1' will be passed as default. Example: 1

middlename

string

The middle name of the customer. Example: 'Edward'

occupationId

integer

Identifier for the customer's occupation.The occupation represents the account holder's profession, job title, or primary field of work, offering insights into their employment status and industry. To get the list of available occupations, please use the API Get Code Value with code name Occupation Example: 10013

nickname

string

length ≤ 50

The preferred or informal name of the customer. This can be used for display purposes or casual correspondence. Example: 'Johnny'

nationalityId

integer

Identifier for the customer's nationality.
To get the list of available nationalities, use the API Get Code Value with code name COUNTRY. Example: 284

genderId

integer

The gender identifier of the customer. To retrieve the complete and valid list of gender code values, please use the API Get Code Value with code name Gender, which returns all gender options with their corresponding IDs. Example values:

634 - Male
635 - Female
636 - Diverse

Example: 634

isCurrentlyEmployed

boolean

Indicates whether the customer is currently employed. Example: true

externalId

string

A unique identifier that links the customer created by the third-party system to the customer generated within our system. Example: 'EXT-PER-48392'

clientTypes

array of integers

A list of customer type identifiers associated with the customer.
Each ID represents a specific customer classification.
The value is fetched from the API Get Code Value with code name ClientType.

clientTypes

isOptedForMLAStatus

boolean

Indicates whether the customer is opted for Military Lending Act (MLA) status. Example: false

currentMLAStatus

string

The current Military Lending Act (MLA) status.

Y - Yes, On active duty as of the search date or is a dependent of a servicemember on active duty as of the search date.
N - No, Not on active duty as of the search date or is a dependent of a servicemember on active duty as of the search date. Example: 'Y: Yes, on active duty as of the search date or is a dependent of a servicemember on active duty as of the search date.'

isStaff

boolean

Indicates whether the created customer is a staff member of the office Example: false

staffId

integer

If the 'isStaff' parameter value is 'true' then map the staffId. Example: 12345

clientClassificationId

integer

The customer classification Id. If the customer needs to be associated to any existing classification, then the classification id needs to be passed. To get the list of classification Id, use the API Get Code Value with code name ClientClassification-PERSON. Example: 12345

address

array of objects

A list of addresses associated with the customer. This array can be empty if no address details are provided during customer creation.

address

locale

string

The locale of the customer. 'en' will be passed as default. Example: 'en'

dateFormat

string

If the fields 'submittedOnDate' or 'activationDate' is passed, then this parameter is mandatory. It specifies the dataformat, that's being used. Example: 'dd MMMM yyyy'

submittedOnDate

string

The submitted on date. The date format should be as per the format mentioned in the dateFormat parameter. Example: '14 February 2024'

Headers

tenantId

string

required

Defaults to z01j3e71zd6zkq908vyf5861a8

The ID of your banking instance visible in the MBANQ Console.

Responses

200Person customer created successfully.

400The request failed validation. This typically happens when required fields are missing, field values are invalid, or unsupported parameters are included.

401Authentication credentials were missing or incorrect.

403Business errors and constraints. The system encountered an invalid business flow condition.

404A referenced resource (such as an office or savings product) was not found.

409Data integrity issue. A record with the provided unique information already exists.