Customers

A customer is an entity (individual or business) created by an institution. Customers represent the institution's end-users who will transact using the platform. Each customer has a profile containing identification details and can own multiple sub-accounts across currencies.

The Create Customer API allows institutions to create Individuals or Business Customers

Request Parameters

The request must include the following parameters in JSON format:

Parameter	Type	Required	Description
`currency`	string	✅	The currency of the sub-account (e.g., USD, NGN, EUR).
`client_reference`	string	❌	Optional Institution-generated reference
`email`	string	❌	The email address of the customer.
`type`	string	❌	The type of customer (`BUSINESS` or `INDIVIDUAL`).
`individual`	object	❌	Required if type is `INDIVIDUAL`
`business`	object	❌	Required if type is `BUSINESS`
`country_data`	object	❌	Optional object containing country specific data

Country Data

Parameter	Type	Required	Description
`ng.bvn`	string	❌	11 chars Nigerian BVN
`ng.nin`	string	❌	11 chars Nigerian NIN

Individual

Parameter	Type	Required	Description
`first_name`	string	✅	First name of Individual customer
`last_name`	string	✅	Last name of Individual customer
`other_name`	string	❌	Other names
`date_of_birth`	string	❌	Date of birth in ISO 8601 format (YYYY-MM-DD)
`residential_address`	object	❌	See Address below
`phone_number`	string	❌	Phone number in E.164, e.g. (+234XXXXXXXX).

Business

Parameter	Type	Required	Description
`name`	string	✅	The name of the business
`phone_number`	string	❌	Phone number in E.164, e.g. (+234XXXXXXXX).
`incorporation_number`	string	❌	Business registration or incorporation number
`incorporation_date`	string	❌	Date of incorporation in ISO 8601 format (YYYY-MM-DD)
`incorporation_country`	string	❌	Two-letter country code where business is incorporated. This must always exist with `incorporation_number`
`registered_address`	object	❌	See the Address object below
`tax_id`	string	❌	Business tax identification number
`business_type`	string	❌	The legal structure of the business (CORPORATION, LLC, PARTNERSHIP, SOLE_PROPRIETORSHIP)
`website`	string	❌	Business website URL
`contact_person`	object	❌	Details of contact person for the business
`contact_person.first_name`	string	✅	First name of the business contact person
`contact_person.last_name`	string	✅	Last name of the business contact person
`contact_person.email`	string	❌	Last name of the business contact person
`contact_person.phone_number`	string	❌	Phone number of business contact in E.164 format
`contact_person.position`	string	❌	Job title or position of contact within the business

Address

Parameter	Type	Required	Description
`line_1`	string	✅	First line of address (street number and name)
`line_2`	string	❌	Second line of address (apartment, suite, etc.)
`city`	string	❌	City name
`state`	string	❌	State, province, or region
`postal_code`	string	❌	Postal or ZIP code
`country`	string	✅	Two-letter country code

Example Request

curl --location -g '{{LYNC_BASE_URL}}/banking/v2/customers' \
--header 'x-waza-api-key: your_api_key_here' \
--data-raw '{
  "type": "BUSINESS",
  "email": "[email protected]",
  "client_reference": "CUST-BUS-789012",
  "business": {
    "name": "Acme Corporation",
    "phone_number": "+12025550179",
    "incorporation_number": "BUS12345",
    "incorporation_date": "2010-05-20",
    "incorporation_country": "US",
    "tax_id": "12-3456789",
    "business_type": "CORPORATION",
    "website": "https://www.acmecorp.com",
    "registered_address": {
      "line_1": "100 Corporate Way",
      "line_2": "Suite 300",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94107",
      "country": "US"
    },
    "contact_person": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "phone_number": "+12025550180",
      "position": "Chief Financial Officer"
    }
  }
}'

curl --location -g '{{LYNC_BASE_URL}}/banking/v1/customers' \
--header 'x-waza-api-key: your_api_key_here' \
--data-raw '{
    "type": "INDIVIDUAL",
    "client_reference": "individual-cust-3",
    "individual": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "2022-02-28",
        "residential_address": {
            "line_1": "Some address",
            "line_2": "",
            "city": "Lagos",
            "state": "Lagos",
            "postal_code": "333443",
            "country": "NG"
        }
    },
    "country_data": {
        "ng": {
            "bvn": "33332232354",
            "nin": "77467634657"
        }
    }
}'

Example Response: 201 Created

Upon successful creation, the API will respond with details of the created subaccount.

{
  "data": {
    "id": "0195b6f7-2056-8b11-c26d-51ec96c7f413",
    "type": "BUSINESS",
    "email": "[email protected]",
    "client_reference": "CUST-BUS-789012",
    "state": "CREATED",
    "verification_status": "UNVERIFIED",
    "created_date": "2025-03-17T21:20:36.122Z",
    "updated_date": "2025-03-17T21:20:36.122Z",
    "business": {
      "name": "Acme Corporation",
      "phone_number": "+12025550179",
      "incorporation_number": "BUS12345",
      "incorporation_date": "2010-05-20",
      "incorporation_country": "US",
      "tax_id": "12-3456789",
      "business_type": "CORPORATION",
      "website": "https://www.acmecorp.com",
      "registered_address": {
        "line_1": "100 Corporate Way",
        "line_2": "Suite 300",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94107",
        "country": "US"
      },
      "contact_person": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+12025550180",
        "position": "Chief Financial Officer"
      }
    }
  }
}

{
    "data": {
        "id": "0196251d-6dd8-76bb-bcc4-2e0dd127baea",
        "state": "ACTIVE",
        "created_date": "2025-04-11T13:50:07.838Z",
        "updated_date": "2025-04-11T13:50:07.838Z",
        "version": 0,
        "type": "INDIVIDUAL",
        "client_reference": "individual-cust-3",
        "verification_status": "UNVERIFIED",
        "individual": {
            "first_name": "John",
            "last_name": "Doe",
            "date_of_birth": "2022-02-28",
            "residential_address": {
                "line_1": "Some address",
                "line_2": "",
                "city": "Lagos",
                "state": "Lagos",
                "postal_code": "333443",
                "country": "NG"
            }
        },
        "country_data": {
            "ng": {
                "bvn": "33332232354",
                "nin": "77467634657"
            }
        }
    }
}

Additional Response Fields

Parameter	Type	Required	Description
`verification_status`	string	✅	Indicates KYC/KYB verification state of the customer. Can be `VERIFIED` or `UNVERIFIED`
`state`	string	✅	`ACTIVE`, `INACTIVE`, `BLOCKED`

🚧
Customers must be in ACTIVE state before accounts can be created for them

📘
Some account types may be unavailable to some customers depending on the verification_status

Customer Updates

Updates can be made to customers by calling the appropriate patch endpoint for the field that needs an update. Properties can be removed by setting them explicitly to null as far as they are optional fields.

Update Endpoints

Endpoint	HTTP Method	Description
`/customer/{id}/individual`	PATCH	Update individual customer details
`/customer/{id}/business`	PATCH	Update business customer details
`/customer/{id}/country_data`	PATCH	Update country-specific data

Update Rules

Partial Updates: Only include fields you want to update
Required Fields: Cannot be set to null (e.g., first_name, last_name for individuals; name for businesses)
Optional Fields: Can be set to null to remove the value
At Least One Field: Each update request must include at least one field
Address Updates: Address fields must be updated as a complete object - partial address updates are not supported

Update Individual Customer

Request Parameters

Include any individual customer fields you want to update.

Parameter	Type	Description	Nullable
`first_name`	string	First name of Individual customer	No
`last_name`	string	Last name of Individual customer	No
`other_name`	string	Other names	Yes
`date_of_birth`	string	Date of birth (YYYY-MM-DD)	Yes
`residential_address`	object	Complete address object	Yes
`phone_number`	string	Phone number in E.164 format	Yes

curl --location -g '{{LYNC_BASE_URL}}/banking/v2/customer/0196251d-6dd8-76bb-bcc4-2e0dd127baea/individual' \
--header 'x-waza-api-key: your_api_key_here' \
--data-raw '{
    "first_name": "Johnny",
    "other_name": null,
    "residential_address": {
        "line_1": "123 New Street",
        "line_2": "",
        "city": "New City",
        "state": "Lagos",
        "postal_code": "333443",
        "country": "NG"
    }
}'

This request:

Updates first_name to "Johnny"
Removes other_name by setting it to null
Updates the entire residential_address object (must include all required address fields)

Update Business Customer

Request Parameters

Include any business customer fields you want to update.

Parameter	Type	Description	Nullable
`name`	string	The name of the business	No
`phone_number`	string	Phone number in E.164 format	Yes
`incorporation_number`	string	Business registration number	Yes
`incorporation_date`	string	Date of incorporation (YYYY-MM-DD)	Yes
`incorporation_country`	string	Two-letter country code	Yes
`registered_address`	object	Complete address object	Yes
`tax_id`	string	Business tax identification number	Yes
`business_type`	string	Legal structure of the business	Yes
`website`	string	Business website URL	Yes
`contact_person`	object	Complete contact person object	Yes

⚠️ Note: incorporation_country and incorporation_number must be provided together when updating either one.

curl --location -g '{{LYNC_BASE_URL}}/banking/v2/customer/0195b6f7-2056-8b11-c26d-51ec96c7f413/business' \
--header 'x-waza-api-key: your_api_key_here' \
--data-raw '{
    "name": "Acme Corporation International",
    "website": "https://www.acmecorp-international.com",
    "tax_id": null,
    "registered_address": {
        "line_1": "200 Business Blvd",
        "line_2": "Floor 12",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94107",
        "country": "US"
    },
    "contact_person": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+12025550180", 
        "position": "Chief Executive Officer"
    }
}'

This request:

Updates name to "Acme Corporation International"
Updates website to a new URL
Removes tax_id by setting it to null
Updates the entire registered_address object
Updates the entire contact_person object

Update Country-Specific Data

Request Parameters

Include any country-specific data fields you want to update.

Parameter	Type	Description	Nullable
`ng`	object	Nigeria-specific data	Yes

curl --location -g '{{LYNC_BASE_URL}}/banking/v2/customer/0196251d-6dd8-76bb-bcc4-2e0dd127baea/country_data' \
--header 'x-waza-api-key: your_api_key_here' \
--data-raw '{
    "ng": {
        "bvn": "22233344455",
        "nin": null
    }
}'

This request:

Updates the entire ng object
Sets ng.bvn to a new value
Removes ng.nin by setting it to null

Address Object

When updating address fields, you must provide a complete address object with all required fields. Partial address updates are not supported.

Parameter	Type	Required	Description
`line_1`	string	✓	First line of address
`line_2`	string		Second line of address
`city`	string		City name
`state`	string		State, province, or region
`postal_code`	string		Postal or ZIP code
`country`	string	✓	Two-letter country code

Contact Person Object

When updating the contact person, you must provide a complete contact person object with all required fields. Partial contact person updates are not supported.

Parameter	Type	Required	Description
`first_name`	string	✓	First name of contact person
`last_name`	string	✓	Last name of contact person
`email`	string		Email address of contact person
`phone_number`	string		Phone number in E.164 format
`position`	string		Job title or position

Customer Response Schema Definitions

Common Fields (Always Present)

Field	Data Type	Description
`data.type`	`string`	Type of customer ("INDIVIDUAL" or "BUSINESS")
`data.client_reference`	`string`	Client's custom identifier
`data.email`	`string`	Customer's email address
`data.id`	`string`	Unique identifier for the customer (UUID format)
`data.created_date`	`string`	ISO timestamp of when the customer record was created
`data.updated_date`	`string`	ISO timestamp of when the customer record was last updated
`data.state`	`string`	Current state of the customer record (e.g., "CREATED")
`data.verification_status`	`string`	Status of customer verification (e.g., "VERIFIED")
`data.country_data`	`object`	Country-specific identification information

Conditional Fields

When data.type = "INDIVIDUAL"

Field	Data Type	Description
`data.individual`	`object`	Information for individual customer
`data.individual.first_name`	`string`	Individual's first name
`data.individual.last_name`	`string`	Individual's last name
`data.individual.other_name`	`string`	Individual's middle or other names
`data.individual.date_of_birth`	`string`	Date of birth in YYYY-MM-DD format
`data.individual.phone_number`	`string`	Phone number with country code
`data.individual.residential_address`	`object`	Individual's residential address details
`data.individual.residential_address.line_1`	`string`	First line of residential address
`data.individual.residential_address.line_2`	`string`	Second line of residential address
`data.individual.residential_address.city`	`string`	City of residence
`data.individual.residential_address.state`	`string`	State or province of residence
`data.individual.residential_address.postal_code`	`string`	Postal or ZIP code
`data.individual.residential_address.country`	`string`	Country code for the address

When data.type = "BUSINESS"

Field	Data Type	Description
`data.business`	`object`	Information for business customer
`data.business.name`	`string`	Business name
`data.business.phone_number`	`string`	Business Phone number with country code
`data.business.incorporation_number`	`string`	Business registration/incorporation number
`data.business.incorporation_date`	`string`	Date of incorporation in YYYY-MM-DD format
`data.business.incorporation_country`	`string`	Country code where business is incorporated
`data.business.registered_address`	`object`	Business's registered address details
`data.business.registered_address.line_1`	`string`	First line of registered address
`data.business.registered_address.line_2`	`string`	Second line of registered address
`data.business.registered_address.city`	`string`	City of registered address
`data.business.registered_address.state`	`string`	State or province of registered address
`data.business.registered_address.postal_code`	`string`	Postal or ZIP code
`data.business.registered_address.country`	`string`	Country code for the registered address
`data.business.tax_id`	`string`	Business tax identification number
`data.business.business_type`	`string`	Type of business entity (e.g., "CORPORATION")
`data.business.website`	`string`	Business website URL
`data.business.contact_person`	`object`	Primary contact person details
`data.business.contact_person.first_name`	`string`	Contact person's first name
`data.business.contact_person.last_name`	`string`	Contact person's last name
`data.business.contact_person.email`	`string`	Contact person's email address
`data.business.contact_person.phone_number`	`string`	Contact person's phone number
`data.business.contact_person.position`	`string`	Contact person's position in the business

Customers

Request Parameters

Country Data

Individual

Business

Address

Example Request

Example Response: 201 Created

Additional Response Fields

Customers must be in ACTIVE state before accounts can be created for them

Some account types may be unavailable to some customers depending on the verification_status

Customer Updates

Update Endpoints

Update Rules

Update Individual Customer

Request Parameters

Update Business Customer

Request Parameters

Update Country-Specific Data

Request Parameters

Address Object

Contact Person Object

Customer Response Schema Definitions

Common Fields (Always Present)

Conditional Fields

When data.type = "INDIVIDUAL"

When data.type = "BUSINESS"

What’s Next