Create an Individual Customer

Add a new Customer Account for an individual. The Customer Account contains the Customer’s profile (name and contact information).

Note You can also add a Customer Account for a business.

Endpoint

POST /v1/customers

Authorization Header

Authorization: Bearer <access_token>

Request Body

externalId

string

Applies to Customer Accounts that are linked to an Earned Wage Access (EWA) Customer Profile.

Your organization’s EWA reference number for the employee. This should be a string that is used to identify the employee in your internal systems, such as your payroll software. The EWA reference number is added to the employee’s Customer Account, allowing you to easily locate the employee in RocketKOR.

EWA reference numbers must be unique within the Business Account.

addresses

array

Customer addresses.

The Customer can have multiple addresses for each address type (MAILING, PHYSICAL, and SHIPPING).
A primary address must be specified for each address type added to the Customer Account.
- Only one primary address can be specified for each address type.
- If a primary address is not specified for an address type, the first address of this type will be set as the primary address.
- If multiple addresses exist for an address type and the primary address is removed (and another address is not explicitly set as primary), another address of the same type will be set as the primary address.

type REQUIRED

string enum, values: MAILING, PHYSICAL, SHIPPING

Type of address. The following values are supported:

MAILING Address used for mail.
PHYSICAL Physical location where the Customer resides. Cannot be a post office (PO) box.
SHIPPING Address used for packages or shipments.

name CONDITIONAL

object

Name of the contact person for shipments. Required if type is SHIPPING. Ignored for other address types.

firstName REQUIRED

string, min length: 1, max length: 40

Contact person’s first name.

middleName

string, min length: 1, max length: 40

Contact person’s middle name.

lastName REQUIRED

string, min length: 1, max length: 40

Contact person’s last name.

streetLine1 REQUIRED

string, min length: 1, max length: 50

First line of the street address.

streetLine2

string, min length: 1, max length: 50

Second line of the street address.

streetLine3

string, min length: 1, max length: 50

Third line of the street address.

streetLine4

string, min length: 1, max length: 50

Fourth line of the street address. Only used for issued cards.

streetLine5

string, min length: 1, max length: 50

Fifth line of the street address. Only used for issued cards.

cityName

string, min length: 1, max length: 25

City.

stateCode CONDITIONAL

string, min length: 2, max length: 3

State, province, or territory. Required if countryCode is USA or CAN. Must be an ISO 3166-2 uppercase alpha 2-character or 3-character country subdivision code (for example, Missouri is MO).

countryCode

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

zipCode CONDITIONAL

string, min length: 1, max length: 10

Zip code or postal code. Required if countryCode is USA or CAN. For US addresses, must be a valid value of 5 digits (example: 63368) or 5 digits-4 digits (example: 63368-5555). Can be alphanumeric for other countries.

primary CONDITIONAL

boolean

Whether this is the primary address for this address type. A primary address must be specified for each address type added to the Customer Account.

metadata

string, max items: 5, value max length: 1024

Use a maximum of 5 key/value pairs to store additional information about the Customer.

type REQUIRED

string enum, value: INDIVIDUAL

Type of Customer. Value must be INDIVIDUAL.

firstName REQUIRED

string, min length: 1, max length: 40

Customer’s first name.

middleName

string, min length: 1, max length: 40

Customer’s middle name.

lastName REQUIRED

string, min length: 1, max length: 40

Customer’s last name.

prefix

string, min length: 1, max length: 40

Title before the Customer’s name (example: Dr).

suffix

string, min length: 1, max length: 40

Title following the Customer’s name (example: PhD).

sex

string enum, values: MALE, FEMALE, NONBINARY

Customer’s sex.

gender

string

Customer’s gender.

securityQuestion

string

Customer’s security question.

securityAnswer

string

Customer’s security answer.

pronoun

string

Customer’s pronouns (example: He/His).

primaryPhoneNumber REQUIRED

object

Customer’s primary phone number.

number REQUIRED

string

Customer’s phone number. The phone number can be entered in any of the following formats:

[+][country code][phone number including area code] (example: +14151234)
[country code][phone number including area code] (example: 14151234)
[phone number including area code] (example: 4151234)

RocketKOR will convert the phone number to E.164 format (example: +14151234).

type REQUIRED

string enum, values: WORK, HOME, MOBILE

Type of phone number.

provider

string, min length: 1, max length: 40

Phone provider.

extension

string, min length: 1, max length: 10

Phone extension.

verified

boolean

Whether the phone number has been verified.

primaryEmail REQUIRED

object

Customer’s primary email address.

value REQUIRED

string (email), max length: 320

Customer’s email address.

verified

boolean

Whether the email address has been verified.

dateOfBirth

string (date), format: yyyy-MM-dd

Customer’s date of birth.

placeOfBirth

object

Customer’s place of birth.

city

string, max length: 60

City.

countryCode

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

socialId

string, max length: 50

Customer’s unique national identifier, such as a Social Security Number (SSN). Responses include a truncated value only.

socialIdCountryCode

string, min length: 3, max length: 3

Country where the social ID was granted. Required if socialId is provided. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

citizenshipCountryCode

string, min length: 3, max length: 3

Country where the Customer holds citizenship. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

Returns

Returns the Individual Customer object. This object contains the Customer Account details, including a unique ID for the account.

SAMPLE REQUEST

				
					{
  "externalId": "abcdefg",
  "id": "0e01f271-80b1-4724-b5dc-6959c7cd88dc",
  "status": "ACTIVE",
  "addresses": [
    {
      "type": "MAILING",
      "streetLine1": "400 Richmond St",
      "streetLine2": "Suite 500",
      "streetLine3": "",
      "streetLine4": "",
      "streetLine5": "",
      "cityName": "New York",
      "stateCode": "NY",
      "countryCode": "USA",
      "zipCode": "10001",
      "primary": true
    },
    {
      "type": "SHIPPING",
      "name": {
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Green"
      },
      "streetLine1": "200 Queen St",
      "streetLine2": "Suite 230",
      "streetLine3": "",
      "streetLine4": "",
      "streetLine5": "",
      "cityName": "New York",
      "stateCode": "NY",
      "countryCode": "USA",
      "zipCode": "10001",
      "primary": true
    }
  ],
  "metadata": {
    "customerRefId": "200000777"
  },
  "type": "INDIVIDUAL",
  "firstName": "Sarah",
  "middleName": "Jane",
  "lastName": "Green",
  "prefix": "Ms",
  "suffix": "",
  "sex": "FEMALE",
  "gender": "",
  "securityQuestion": "Who is your favorite author?",
  "securityAnswer": "Barbara Gowdy",
  "pronoun": "She/Her",
  "primaryPhoneNumber": {
    "number": "+15556589",
    "type": "WORK",
    "provider": "ABC",
    "extension": "31",
    "verified": false
  },
  "primaryEmail": {
    "value": "sgreen@abc.com",
    "verified": false
  },
  "dateOfBirth": "1991-06-21",
  "placeOfBirth": {
    "city": "Houston",
    "countryCode": "USA"
  },
  "socialId": "123-45-6789",
  "socialIdCountryCode": "USA",
  "citizenshipCountryCode": "CAN"
}

SAMPLE RESPONSE

				
					{
  "id": "0e01f271-80b1-4724-b5dc-6959c7cd88dc",
  "status": "ACTIVE",
  "externalId": "abcdefg",
  "addresses": [
    {
      "type": "MAILING",
      "streetLine1": "400 Richmond St",
      "streetLine2": "Suite 500",
      "streetLine3": "",
      "streetLine4": "",
      "streetLine5": "",
      "cityName": "New York",
      "stateCode": "NY",
      "countryCode": "USA",
      "zipCode": "10001",
      "primary": true
    },
    {
      "type": "SHIPPING",
      "name": {
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Green"
      },
      "streetLine1": "200 Queen St",
      "streetLine2": "Suite 230",
      "streetLine3": "",
      "streetLine4": "",
      "streetLine5": "",
      "cityName": "New York",
      "stateCode": "NY",
      "countryCode": "USA",
      "zipCode": "10001",
      "primary": true
    }
  ],
  "metadata": {
    "customerRefId": "200000777"
  },
  "createdBy": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "EMPLOYEE"
  },
  "createdAt": "2022-11-23T00:42:50.311Z",
  "updatedBy": {
    "id": "",
    "type": ""
  },
  "updatedAt": "",
  "type": "INDIVIDUAL",
  "firstName": "Sarah",
  "middleName": "Jane",
  "lastName": "Green",
  "prefix": "Ms",
  "suffix": "",
  "sex": "FEMALE",
  "gender": "",
  "securityQuestion": "Who is your favorite author?",
  "securityAnswer": "Barbara Gowdy",
  "pronoun": "She/Her",
  "primaryPhoneNumber": {
    "number": "+15556589",
    "type": "WORK",
    "provider": "ABC",
    "extension": "31",
    "verified": false
  },
  "primaryEmail": {
    "value": "sgreen@abc.com",
    "verified": false
  },
  "dateOfBirth": "1991-06-21",
  "placeOfBirth": {
    "city": "Houston",
    "countryCode": "USA"
  },
  "socialId": "123-45-6789",
  "socialIdCountryCode": "USA",
  "citizenshipCountryCode": "CAN"
}