Create Customer

Overview

You can create customers with basic details such as name, contact details, et al., using the POST method and use them for various Passport solution offerings. A customer can be either a business, an individual, or a joint tenancy and is created in ACTIVE status by default.

Resource Access

Production (api.ahrvo.network)

POST https://api.ahrvo.network/banking/us2/v1/customer

Staging (gateway.ahrvo.network)

POST https://gateway.ahrvo.network/banking/us2/v1/customer

Authentication

Header	Description
`Authorization`	`Bearer {JWT token}`
`x-api-key`	Your API key
`Content-Type`	`application/json`

Arguments

Top-Level Fields

Attribute	M / O	Notes
`externalId`	O	Client-defined external reference
`type`	O	`INDIVIDUAL`, `BUSINESS`, or `JOINT_TENANCY`
`individual`	C	Required if type is `INDIVIDUAL`
`business`	C	Required if type is `BUSINESS`
`owners`	C	Required if type is `JOINT_TENANCY`
`isPaperless`	O	Default: `true`. If `true`, email becomes mandatory
`preferredCommunication`	O	Preferred communication method
`programAffiliate.id`	O	Program affiliate identifier
`metaData`	O	Up to 20 custom key–value pairs
`tags`	O	Array of labels
`linkedDocument`	O	Documents to link to the customer

Individual Object

Attribute	M / O	Notes
`firstName`	M	First name
`lastName`	M	Last name
`middleName`	O	Middle name
`maidenName`	O	Maiden name
`ssn`	O	Social Security Number
`dob`	O	Date of birth (`MM/DD/YYYY`)
`mailingAddress`	O	Array of address objects
`homePhone`	O	Home phone number
`mobilePhone`	O	Mobile phone number
`workPhone`	O	Work phone number
`email`	C	Mandatory if `isPaperless` is `true`
`secondaryIdentification.type`	O	`DRIVER_LICENSE`, `PASSPORT`, `STATE_ID`, `MILITARY_ID`
`secondaryIdentification.id`	O	Identification number
`secondaryIdentification.countryOfIssuance`	O	Issuing country
`secondaryIdentification.stateOfIssuance`	O	Issuing state
`taxIdentification.type`	O	`ITIN` or `EIN` — only for customers without SSN
`taxIdentification.id`	O	Tax identification number

Business Object

Attribute	M / O	Notes
`legalName`	M	Legal name of the business
`ein`	O	Employer Identification Number
`doingBusinessAs`	O	DBA / trade name
`dateOfIncorporation`	O	Date of incorporation (`MM/DD/YYYY`)
`stateOfIncorporation`	O	Two-letter state code
`businessCategory`	O	e.g., `LLC`, `CORPORATION`
`phone`	O	Business phone number
`mailingAddress`	O	Array of address objects
`email`	O	Business email address
`website`	O	Business website URL
`beneficialOwner`	O	Array of beneficial owner objects

Beneficial Owner Object (within Business)

Attribute	M / O	Notes
`externalId`	O	External identifier
`firstName`	M	First name
`lastName`	M	Last name
`middleName`	O	Middle name
`ssn`	M	Social Security Number
`taxIdentification.type`	C	Only for owners without SSN
`taxIdentification.id`	C	Tax ID number
`secondaryIdentification.type`	M	`DRIVER_LICENSE`, `PASSPORT`, `STATE_ID`, `MILITARY_ID`
`secondaryIdentification.id`	M	Identification number
`secondaryIdentification.countryOfIssuance`	O	Issuing country
`secondaryIdentification.stateOfIssuance`	O	Issuing state
`dob`	M	Date of birth (`MM/DD/YYYY`)
`mailingAddress`	M	Array of address objects
`homePhone`	O	At least one phone number is mandatory
`mobilePhone`	O	At least one phone number is mandatory
`workPhone`	O	At least one phone number is mandatory
`email`	C	Mandatory if `isPaperless` is `true`
`isUSCitizen`	O	Whether the owner is a US citizen
`pullCreditReport`	O	Whether to pull a credit report
`actAsAuthorizedSignatory`	C	Whether the owner acts as an authorized signatory
`businessDetails.ownershipPercentage`	O	Percentage of ownership
`businessDetails.title`	O	Title or role in the business

Owners Array (Joint Tenancy)

Attribute	M / O	Notes
`externalId`	O	External identifier
`firstName`	M	First name
`lastName`	M	Last name
`middleName`	O	Middle name
`isPrimaryOwner`	M	Whether this is the primary owner
`ssn`	O	Social Security Number
`dob`	O	Date of birth (`MM/DD/YYYY`)
`mailingAddress`	O	Array of address objects
`homePhone`	O	Home phone number
`mobilePhone`	O	Mobile phone number
`workPhone`	O	Work phone number
`email`	C	Mandatory if `isPaperless` is `true`
`secondaryIdentification.type`	O	`DRIVER_LICENSE`, `PASSPORT`, `STATE_ID`, `MILITARY_ID`
`secondaryIdentification.id`	O	Identification number
`secondaryIdentification.countryOfIssuance`	O	Issuing country
`secondaryIdentification.stateOfIssuance`	O	Issuing state
`taxIdentification.type`	O	Only for owners without SSN
`taxIdentification.id`	O	Tax ID number

Linked Document Object

Attribute	M / O	Notes
`purpose`	M	Purpose of the linked document
`document.documentType`	M	MIME or enum document type
`document.name`	M	Document file name
`document.base64EncodedContent`	O	Base64-encoded document content
`document.externalId`	O	External document reference
`document.id`	O	Internal document ID

Example Requests

1. Create Individual Customer

Minimal Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "type": "INDIVIDUAL",
    "individual": {
        "firstName": "John",
        "lastName": "Smith"
    }
}

Full Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "externalId": "TS10567286898",
    "type": "INDIVIDUAL",
    "individual": {
        "firstName": "Mike",
        "lastName": "Simons",
        "middleName": "J",
        "email": "navneet.kaur+128@ahrvo.com",
        "dob": "06/25/1995",
        "homePhone": "573-986-5677",
        "workPhone": "838-786-9290",
        "mobilePhone": "235-333-4107",
        "taxIdentification": {
            "type": "ITIN",
            "id": "999-88-9992"
        },
        "mailingAddress": [
            {
                "addressLine1": "9299",
                "addressLine2": "GT1 KMB",
                "city": "Sa Jose",
                "state": "CA",
                "zip": "95311",
                "externalId": "P945619878",
                "isPrimary": true
            }
        ]
    },
    "isPaperless": false,
    "metaData": {
        "acceptedDraftAmount": "$333.50"
    },
    "tags": [
        "grade A"
    ],
    "linkedDocument": [
        {
            "purpose": "Authorization",
            "document": {
                "base64encodedContent": "Q3Jvc3Nyb2FkcyBGaW5wgVG==",
                "name": "abc.pdf",
                "type": "SPAA"
            }
        }
    ]
}

Example Response

HTTP Status: 201 Created
Content-Type: application/json
Url: v1/customer/id/4015209

2. Create Business Customer

Minimal Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "type": "BUSINESS",
    "business": {
        "legalName": "AMEX"
    }
}

Full Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "externalId": "TSC078783488901",
    "type": "BUSINESS",
    "business": {
        "legalName": "AMEX",
        "email": "businesstest567@gmail.com",
        "businessCategory": "LLC",
        "ein": "22-2015691",
        "doingBusinessAs": "American Express",
        "phone": "213-233-1731",
        "mailingAddress": [
            {
                "addressLine1": "Ap 4891",
                "addressLine2": "Conference Centre Ste 1020",
                "city": "Sugar Notch",
                "state": "PA",
                "zip": "18706",
                "externalId": "PA2309090991",
                "isPrimary": true,
                "usage": {
                    "isPayorAddress": false
                }
            }
        ],
        "website": "www.amex.com",
        "dateOfIncorporation": "12/20/2000",
        "stateOfIncorporation": "CA",
        "beneficialOwner": [
            {
                "firstName": "Amelia",
                "lastName": "Connor",
                "dob": "10/01/2000",
                "homePhone": "530-986-1172",
                "workPhone": "838-900-9090",
                "mobilePhone": "235-237-4107",
                "email": "botest56789@gmail.com",
                "mailingAddress": [
                    {
                        "addressLine1": "Ap 4391",
                        "addressLine2": "Conference Centre Ste 1020",
                        "city": "Sugar Notch",
                        "state": "PA",
                        "zip": "18706",
                        "externalId": "PC3023945678911",
                        "isPrimary": true
                    }
                ],
                "secondaryIdentification": {
                    "type": "DRIVER_LICENSE",
                    "id": "48832905",
                    "stateOfIssuance": "CA"
                },
                "actAsAuthorizedSignatory": true,
                "isUSCitizen": true,
                "pullCreditReport": false,
                "businessDetails": {
                    "title": "Secretary",
                    "ownershipPercentage": 50
                },
                "taxIdentification": {
                    "id": "936-92-2097",
                    "type": "ITIN"
                }
            }
        ]
    },
    "isPaperless": true
}

Example Response

HTTP Status: 201 Created
Content-Type: application/json
Url: v1/customer/id/4015210

3. Create Joint Tenancy Customer

Minimal Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "type": "JOINT_TENANCY",
    "owners": [
        {
            "externalId": "ET2383",
            "firstName": "John",
            "lastName": "Max",
            "isPrimaryOwner": true
        }
    ]
}

Full Request

POST /banking/us2/v1/customer HTTP/1.1
Host: api.ahrvo.network
Authorization: Bearer {placeholder("JWT token")}
x-api-key: {placeholder("your-api-key")}
Content-Type: application/json

{
    "type": "JOINT_TENANCY",
    "externalId": "192098992938",
    "isPaperless": true,
    "owners": [
        {
            "mailingAddress": [
                {
                    "state": "AL",
                    "zip": "13333",
                    "city": "NewYork",
                    "addressLine1": "park",
                    "addressLine2": "street",
                    "isPrimary": true
                }
            ],
            "externalId": "ET2383",
            "firstName": "Max",
            "middleName": "Henry",
            "lastName": "J",
            "email": "navneet.kaur+8336@ahrvo.com",
            "mobilePhone": "923-620-0742",
            "dob": "05/23/1990",
            "isPrimaryOwner": true,
            "isUSCitizen": true,
            "portalAccess": {
                "grantAccess": true
            },
            "taxIdentification": {
                "type": "ITIN",
                "id": "909-92-0936"
            }
        },
        {
            "mailingAddress": [
                {
                    "state": "AL",
                    "zip": "85002",
                    "city": "NewYork",
                    "addressLine1": "park",
                    "addressLine2": "street",
                    "isPrimary": true
                }
            ],
            "firstName": "Jack",
            "middleName": "Henry",
            "lastName": "Tom",
            "isPrimaryOwner": false,
            "email": "navneet.kaur+9843@ahrvo.com",
            "mobilePhone": "542-670-4233",
            "isUSCitizen": true,
            "portalAccess": {
                "grantAccess": true
            },
            "taxIdentification": {
                "type": "ITIN",
                "id": "909-92-0935"
            }
        }
    ],
    "linkedDocument": [
        {
            "purpose": "Authorization",
            "document": {
                "base64encodedContent": "Q3Jvc3Nyb2FkcyBGaW5wgVG==",
                "name": "abc.pdf",
                "type": "SPAA"
            }
        }
    ]
}

Example Response

HTTP Status: 201 Created
Content-Type: application/json
Url: v1/customer/id/4015209

Customer Types Summary

Type	Required Object	Key Required Fields
`INDIVIDUAL`	`individual`	`firstName`, `lastName`
`BUSINESS`	`business`	`legalName`
`JOINT_TENANCY`	`owners` (array)	`firstName`, `lastName`, `isPrimaryOwner` per owner

Important Notes

Default Status

All customers are created in ACTIVE status by default.

Paperless Communication

When isPaperless is set to true (the default), the email field becomes mandatory for individual customers, joint tenancy owners, and business beneficial owners.

Tax Identification

The taxIdentification object should only be provided for customers or beneficial owners who do not have an SSN.

Beneficial Owner Phone Requirement

At least one phone number (homePhone, workPhone, or mobilePhone) is mandatory for each beneficial owner in a business customer.

Overview​

Resource Access​

Authentication​

Arguments​

Top-Level Fields​

Individual Object​

Business Object​

Beneficial Owner Object (within Business)​

Owners Array (Joint Tenancy)​

Linked Document Object​

Example Requests​

1. Create Individual Customer​

Minimal Request​

Full Request​

2. Create Business Customer​

Minimal Request​

Full Request​

3. Create Joint Tenancy Customer​

Minimal Request​

Full Request​

Customer Types Summary​

Important Notes​

Interactive API Explorer​

Overview

Resource Access

Authentication

Arguments

Top-Level Fields

Individual Object

Business Object

Beneficial Owner Object (within Business)

Owners Array (Joint Tenancy)

Linked Document Object

Example Requests

1. Create Individual Customer

Minimal Request

Full Request

2. Create Business Customer

Minimal Request

Full Request

3. Create Joint Tenancy Customer

Minimal Request

Full Request

Customer Types Summary

Important Notes

Interactive API Explorer