# Customer Records
source: https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md
This section covers the customer and consumer records that are required to use Open Finance services.
* [Customers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) - Create and manage customer records to access data from financial institutions
* [Businesses](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) - Create a business record for a customer
* [Consumers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) - Create consumer records associated with a customer to generate and view loan reports
## Customers {#customers}
In order to use most Open Finance APIs, you'll need to create a customer record. This record allows you to view a customer's account information and other types of data from the financial institutions (FIs) that they connect. When a customer logs into their bank and permissions their accounts, the financial data is associated with their `customerId`. If you delete the `customerId` field, the link to their account gets deleted as well.
### Customer Account Types {#customer-account-types}
###### For Testing {#for-testing}
To begin testing Open Finance services using our mocked bank provider you need to create a test customer.
[Create a test customer →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers)
###### For Upgraded Accounts {#for-upgraded-accounts}
Upgraded paid accounts must add an *active* customer record in order to access data from live financial institutions.
[Create an active customer →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers)
###### Business Customers {#business-customers}
Partners must register their customers as businesses if their customer is a business entity.
[Create a business record →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses)
### Test Customers {#test-customers}
Create a customer record to use with our mocked financial institution, FinBank. You might have already completed this step if you followed the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md).
Note: You can create up to 500 testing customers per Partner ID. If you reach this limit, you will receive a 42000 error. Delete unused testing customers from your environment.
API Reference: `POST /aggregation/v2/customers/testing`
You can omit the `applicationId` from the request when generating testing customers.
* Command:
```sh
curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/testing' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"username": "customerusername1"
}'
```
* Expected response:
```json
{
"id": "1005061234",
"username": "customerusername1",
"createdDate": 1607450357
}
```
### Active Customers {#active-customers}
Upgraded paid accounts can also add active customers to use at live financial institutions. You can use either active or testing customers with the Finbank [test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md).
###### Creating an Active Customer {#creating-an-active-customer}
API Reference: `POST /aggregation/v2/customers/active`
* Command:
```sh
curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/active' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"username": "{{username}}",
"firstName": "{{firstname}}",
"lastName": "{{lastname}}"
}'
```
* Expected
```response: json
{
"id": "1035061235",
"username": "{{username}}",
"createdDate": 1607450357
}
```
Tip: The `username` parameter used when creating a customer record must be unique, and consist of between 6 and 255 characters in any combination of:
* Upper case, lower case, or numeric characters
* The following non-alphanumeric special characters: `! @ . # $ % & * _ - +`
Use of other special characters (such as `í` or `ü`) may result in an error.
We recommend avoiding the use of email addresses for usernames.
###### Operations for Retrieving and Managing Active Customers {#operations-for-retrieving-and-managing-active-customers}
Get Customer by ID:
API Reference: `GET /aggregation/v1/customers/{customerId}`
Modify Customer by ID (you must specify either the first name, the last name, or both in the request):
API Reference: `PUT /aggregation/v1/customers/{customerId}`
Delete Access to Customer by ID:
API Reference: `DELETE /aggregation/v1/customers/{customerId}`
Get (all) Customers:
API Reference: `GET /aggregation/v1/customers`
Use the `userName` query parameter to obtain a specific customer, or use the `search` parameter to search for all customer records with the specified text in the customer name (anywhere in either of their `firstName` or `lastName` fields).
For example, the following will return the first 25 customers with the text `John` in either of the `firstName` or `lastName` fields:
GET 'https://api.finicity.com/aggregation/v1/customers?search=John&start=1&limit=25'
If the response includes true for the `moreAvailable` value then you can get the next page of results by calling the same query again with an appropriate value for the `start` query parameter.
### Retrieve Customer Authorization Period {#retrieve-customer-authorization-period}
The duration for which you can access a customer's data using Mastercard's Open Finance services will vary depending on the financial institution. You can call the `GET /customers/institution-logins/{institution_login_id}/authorization-details` endpoint with the specific `InstitutionLoginID` to determine the customer's authorization period for a specific financial institution. The response includes the customer's authorization start and end date, helping you prompt the customer to reauthenticate before their authorization expires, avoiding any disruptions in service or data access.
API Reference: `GET /customers/institution-logins/{institution_login_id}/authorization-details`
#### Using the institutionLoginId {#using-the-institutionloginid}
When a customer links their account via [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) and authorizes Mastercard Open Finance to access their financial data, an `institutionLoginId` is generated. The `institutionLoginId` is created during the [Add Accounts event](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md#addaccounts). If [webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#added) are configured, you will receive a notification with a response including the `institutionLoginId`.
#### Steps to Check a Customer's Authorization Period for a Financial Institution: {#steps-to-check-a-customers-authorization-period-for-a-financial-institution}
1. Create a [customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and link them to at least one account via [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md).
2. The `institutionLoginId` is generated during the Data Connect flow when the user [adds an account](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md#addaccounts). If [webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#added) are configured, you will receive a notification with the response including the `institutionLoginId`. Alternatively, you can use the [Refresh Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#RefreshCustomerAccounts) endpoint to fetch the latest account data, including the `institutionLoginId`.
3. Call the [Get Customer Authorization Details](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) endpoint with the `InstitutionLoginID`.
4. Look for the `authorizationEndDate` in the response, which tells you the exact date and time when the consent will expire. You can prompt the customer to re-authenticate to renew their consent before it expires, ensuring uninterrupted access to their data.
#### Testing {#testing}
To test the `GET /customers/institution-logins/{institution_login_id}/authorization-details` endpoint, use the [OAuth Connection Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles).
## Businesses {#businesses}
A Business record must be created for any customer that is a business. The business record is used to store information related to the business, while the customer record stores information related to the individual owner.
The Business must have a `customerId` associated with it, as this is a required field when creating a business record.
A `consumerId` must be associated with the business if the owner is personally liable for any business loans. For more information see [creating a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#creating-a-consumer). A consumer record must be created before creating a business if `personallyLiable: true` - otherwise the service will return an error 409. This allows for the retention of data for the required period of time under the Fair Credit Reporting Act (FCRA).
### Creating a Business Record for a Customer {#creating-a-business-record-for-a-customer}
API Reference: `POST /business-services/customers/{customer_id}/businesses`
* Command:
```sh
curl --location --request POST 'https://api.finicity.com/business-services/customers/{customer_id}/businesses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"name": "ABC Tires Inc",
"personallyLiable": true,
"address": {
"addressLine1": "434 W Ascension Way",
"addressLine2": "Suite #200",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123"
},
"phoneNumber": {
"countryCode": "141",
"phoneNo": "7992222"
},
"url": "https://www.finicity.com/",
"email": "myname@example.com",
"type": "Nonprofit",
"taxId": "A1234561Z"
}'
```
* Expected
```response: json
{
"name": "ABC Tires Inc",
"personallyLiable": true,
"address": {
"addressLine1": "434 W Ascension Way",
"addressLine2": "Suite #200",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123"
},
"phoneNumber": {
"countryCode": "141",
"phoneNo": "7992222"
},
"url": "https://www.finicity.com/",
"email": "myname@example.com",
"type": "Nonprofit",
"taxId": "A1234561Z",
"businessId": "1112",
"createdDate": "2022-04-12T11:51:23",
"modifiedDate": "2022-04-12T11:51:23"
}
```
### Operations for Retrieving and Managing Active Business Customers {#operations-for-retrieving-and-managing-active-business-customers}
A `customerId` is required to get business information for a specific customer. A `businessId` is required to update and get business records.
API Reference: `GET /business-services/customers/{customer_id}/businesses`
API Reference: `PUT /business-services/businesses/{business_id}`
API Reference: `GET /business-services/businesses/{business_id}`
## Consumers {#consumers}
In order to be able to generate and view [Lend reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) for CRA use cases, you will need to create a consumer record. For more information on permitted use cases, see [Permissible Purpose Codes](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md).
Unlike a customer record, a consumer record cannot be deleted. Reports created for the consumer are retained for six years.
Note: Consumer IDs have a one-to-one relationship with a customer ID. Alert: If you are using consumer lending products for small business purposes (for example, if a Transaction Credit Reporting Agency (TACRA) report is used as part of the decisioning process), you must ensure that a consumer record exists, even if the "consumer" in this case is a business. See the [Consumer Records and Small Business Lending](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumer-records-and-small-business-lending) section below.
### Creating a Consumer {#creating-a-consumer}
Warning: **Reseller Partners**
When creating a consumer record, end user information must be provided by Partners that are resellers. This is due to FCRA regulatory requirements. The create consumer call will fail with error code 1201 when end user information has not been sent in the request parameters.
Please contact your Customer Success Manager with any questions.
Use the [Create Consumer for the Customer](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#CreateConsumer) endpoint to create a consumer record associated with a given customer record. If a consumer already exists for the customer, an HTTP 409 (Conflict) response is generated.
API Reference: `POST /decisioning/v1/customers/{customerId}/consumer`
Required fields for a consumer record are described in this table. All other fields are optional.
| Requirement | Fields |
|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Required fields | `firstName` `lastName` `state` |
| Conditionally required fields | At least one of `ssn` or `birthday` (`year`, `month`, and `dayOfMonth`). Send both if available, as this improves matching accuracy when handling consumer disclosure, dispute, and freeze requests. At least one of `phone` or `email`. |
| Mortgage use cases | `ssn` is required for [GSE data submission](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md#sending-reports-to-government-sponsored-enterprises). |
* Command:
```sh
curl --location --request POST 'https://api.finicity.com/decisioning/v1/{{customerid}}/1005061234/consumer' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"firstName": "{{firstname}}",
"lastName": "{{lastname}}",
"address": "{{address}}",
"city": "{{city}}",
"state": "{{state}}",
"zip": "{{zip}}",
"phone": "{{phone}}",
"ssn": "{{ssn}}",
"birthday": {
"year": {{year}},
"month": {{month}},
"dayOfMonth": {{dayOfMonth}}
},
"email": "{{email}}",
"suffix": "{{suffix}}",
"endUser": {
"name": "{{name}}",
"address": "{{address}}",
"city": "{{city}}",
"state": "{{state}}",
"zip": "{{zip}}",
"phone": "{{phone}}",
"email": "{{email}}",
"url": "{{url}}"
}
}'
```
* Expected
```response: json
{
"id": "0bf46322c167b562e6cbed9d40e19a4c",
"createdDate": 1607450357,
"customerId": 1005061234
}
```
### Consumer Records and Small Business Lending {#consumer-records-and-small-business-lending}
Whenever consumer lending products such as Verification of Income (VOI) or Transaction Credit Reporting Agency (TACRA) are used for small business lending decisions, it is necessary to create a consumer record. You can still create a consumer record using appropriate business details in place of the personal details normally used when creating a consumer. This applies even if there is no personal liability. Where a business owner is personally liable, the consumer record should include details of that person.
We recommend using the following business details to create a suitable consumer record for small business lending purposes:
1. Use the business's 9 digit Employer Identification Number (EIN) in place of the social security number (SSN) usually passed as the `ssn` parameter. Do not include any formatting such as hyphens when passing an EIN here.
2. Use the business name as the `firstName` parameter.
3. Use the business type (`LLC`, `LLP`) as the `lastName` parameter.
4. Use the date that the report is ordered for the required `birthday` parameter.
For example:
```JSON
{
"firstName": "ABC Plumbing",
"lastName": "LLC",
"address": "434 W Ascension Way",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "1-801-984-4200",
"ssn": "123456789",
"birthday": {
"year": 2023,
"month": 7,
"dayOfMonth": 25
},
"email": "admin@example.com"
}
```
### Operations for Retrieving and Managing Consumers {#operations-for-retrieving-and-managing-consumers}
API Reference: `GET /decisioning/v1/customers/{customerId}/consumer`
API Reference: `GET /decisioning/v1/consumers/{consumerId}`
## Next Steps {#next-steps}
* To learn more about the Data Connect user experience, which allows your customers to consent access to their accounts, read about [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md).
* For the full list of testing profiles available, refer to [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md).