Users API Endpoints

Update User

This endpoint is used to update an existing user’s information.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}

Request Body

{
	"peerTransferAcceptPreference": "string",
	"encryptedUserData": {
		"version": "string",
		"ephemeralPublicKey": "string",
		"publicKeyHash": "string",
		"data": "string"
	},
	"termsAcceptances": [
		{
			"termsIdentifier": "string",
			"termsAcceptanceDateTime": "string",
			"termsAcceptanceFlag": true
		}
	],
	"contactVerificationIdentifiers": [
		"3fa85f64-5717-4562-b3fc-2c963f66afa6"
	],
	"userIdCreateDate": "string",
	"passwordChangeDate": "string"
}

Request Parameters

• peerTransferAcceptPreference - This value can be manual or automatic. This property is optional and only applies to Partners using the P2P capabilities of the platform. The default value is manual and has no impact to any service other than P2P.
  Note: If this value is not provided then it will remain manual.
• encryptedUserData - Container for encrypted details about the user.
• Version - pattern: EC_v [1|2]. Version of encryption algorithm used.
• ephemeralPublicKey - Base64 encoded ephemeral public key. Needed for key agreement.
• publicKeyHash - Base64 encoded SHA-256 hash of the X509 encoded public key bytes used during encryption.
• Data - Base64 encrypted data of an object or property.

Unencrypted User Data Parameters

• profileData - Value contains the name and addresses of a user.
• firstName - Required. Must be 1-35 characters. Refer to the Valid Characters for Names, Cities, and Addresses table for details.
• middleName - Optional. Max 100 characters
• lastName - Required. Must be 2-35 characters. Refer to the Valid Characters for Names, Cities, and Addresses table for details.
• addresses - Contains the full address for the user, along with the type.
  • A home address must be provided, and it must be the default address.
  • If KYC is requested and the home address does not contain addressLine1 and either (city and state) or zipCode, then the following description will be returned:

Note: KYC requires a home address that contains addressLine1 and either (city and state) or zipCode.

• Address types include:
  • home
  • work
  • billing (case insensitive)

Currently, work and billing do not have any specific use cases for the debit account products. They will only be stored and retrieved.

• addressLine1 - Required value containing the home address of the user.
• addressLine2 - Home address continued
• city - Required value containing the city where user lives.
• State - Required value containing the state where user lives. Must be a two-character state code.
• zipCode - Required value containing the user’s zipCode.
  Note: Must be only 5 digits. No extended zip codes allowed. If an extended zip code is provided, the extended digits will be stripped off by the system.
• countryCode - Value containing the user’s countryCode. Default is USA
• type - Value containing the type of address provided, which is required to be the “home” address.
• isDefault - This field determines if a default value is used for email, phone, address.
  • true = Use default.
  • false = Do not use default. For an address, false indicates to use a business address.
• identifyingData - Field containing restricted personal identifying data. If included in payload, dateOfBirth and ssn or ssnSuffix is required. Becomes immutable once KYC is completed.
• ssnSuffix - The last 4 digits of the user’s ssn. Products will require full ssn or the ssnSuffix only. Both ssn & ssnSuffix are mutually exclusive.
• Ssn - Must be exactly 9 digits, the full ssn of the user. Products will require full ssn or the ssnSuffix only. Both ssn & ssnSuffix are mutually exclusive. A non-US ssn will fail KYC2.
• dateOfBirth - Must be between 1901 and current date and provided in the form YYYY-MM-DD
• email - Field contains the email address of the user, along with its verification and data entered. Since only one user profile email address is allowed, the isDefault flag is ignored and the provided email address will always be the default.
• emailAddress - String value with a max length of 255 characters.
  Note: In the Partner Integration Environment (PIE), we allow enrollment requests which include an e-mail address containing a “+” character in the username portion. This is to facilitate easier QA by our BaaS partners. In production environments this is not allowed. If the username portion of an e-mail address being attempted for enrollment contains a “+” character, then that request will fail. In production, the partner’s front-end application should use a mechanism that looks for that character and returns guidance to the customer to change the requested e-mail address and remove any disallowed characters.
• phoneNumbers - The user’s phone number. One default phone number (valid with 10 digits) must be provided or the first phone number in the list of phone numbers will be set to the default. If more than one default phone number is provided, the following response will be returned:

HTTP Status: 400
Code: 1040
subCode: 0
Description:  There can only be one default phone.

Note: International codes are not supported at this time.

• Number - Optional
• Type - Value that returns the type of phoneNumber provided by the user. Valid phone types are:
  • mobile
  • home
  • work

Business Rules

• Address, email and phone are all optional.
• If an address, email, or phone property is excluded, then that object is not updated or created.
• If there is only one existing phone number, then it is updated in place with the provided phoneType and number, even if the phoneType was changed.
• When there is more than one phoneNumber record then phones of the same type are updated. If the type is new, then a new record is created. For example, if there is an existing mobile phone entry and the mobile phone is provided, then it is updated. If a home phone did not previously exist and a home phone is provided, then it is created.
• Deletions of addresses and phoneNumbers are not currently supported.

User Data Response Codes & Sub-Codes

Note: All resulting errors will return an http status 400 along with the following Response Details for address, city length and invalid characters.

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"operation is successful",
         "url":"http://tbd"
      }
   ]
}

Update User Name

This endpoint updates a specific user's name.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/name

API Call Structure Parameters

Request Body

{
	"encryptedUserData": {
		"version": "string",
		"ephemeralPublicKey": "string",
		"publicKeyHash": "string",
		"data": "string"
	}
}

Sample Response Body

{
	"responseDetails": [
		{
			"code": 0,
			"subCode": 0,
			"description": "string",
			"url": "string"
		}
	]
}

Retrieve User Profile Information

This endpoint retrieves the user profile information associated with a specific account.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/users

Sample Response Body

{
   "users":[
      {
         "accountIdentifier":"3d0d1c9b-156b-402a-8153-fc7c226d8162",
         "userIdentifier":"c806b3d3-3502-44c8-8d33-ed31a2221229",
         "peerTransferAcceptPreference":"manual",
         "profileData":{
            "firstName":"John",
            "lastName":"Doe",
            "addresses":[
               {
                  "addressLine1":"*****E Foothill Blvd",
                  "addressLine2":"Ste 000",
                  "city":"Pasadena",
                  "state":"CA",
                  "zipCode":"91107",
                  "countryCode":"USA",
                  "type":"Home",
                  "isDefault":true,
                  "isVerified":false,
                  "isReturned":false,
                  "lastUpdatedDateTime":"2019/10/30 04:19:13"
               }
            ],
            "lastUpdatedDateTime":"\"2019-10-31T16:49:04.483Z”
	}",
        "email":{
           "emailAddress":"[email protected]",
           "isVerified":true,
           "isDefault":true,
           "lastUpdatedDateTime":"2020-02-06T16:49:04.483Z"
        },
        "phoneNumbers":[
           {
              "number":"22******51",
              "type":"home",
              "isDefault":false,
              "isVerified":false,
              "lastUpdatedDateTime":"2019-10-30T16:49:04.483Z"
           },
           {
              "number":"22******07",
              "type":"mobile",
              "isDefault":true,
              "isVerified":true,
              "lastUpdatedDateTime":"2020-04-21T16:49:04.483Z"
           },
           {
              "number":"22******51",
              "type":"work",
              "isDefault":false,
              "isVerified":false,
              "lastUpdatedDateTime":"2019-10-30T16:49:04.483Z"
           }
	],
      "identities":[
         {
            "identityType":"ssn",
            "last4Identity":“3675”
         }
	],
      "termsAcceptances":[
         {
            "termsIdentifier":"daa",
            "termsAcceptanceDateTime":"2018-09-15T13:34:22.113Z",
            "termsAcceptanceFlag":"true"
         },
         {
            "termsIdentifier":"privPlcy",
            "termsAcceptanceDateTime":"2018-09-15T13:34:22.113Z",
            "termsAcceptanceFlag":"true"
         }
	],
      "responseDetails":[
         {
            "code":0,
            "subCode":0,
            "description":"Success",
            "url":"http://tbd"
         }
	]
}

Sample Response Parameters

• code - Required. Type = Integer, Format = Header.
• subCode - Required. Type = Integer, Format = Path.
• description - Required. Type = String, Format = Path.
• url - Required. Type = String, Format = Path.

User Updates

• If an account is in a pending state, the user profile can be updated via the API.
• If an account is in a locked state, the user profile cannot be updated via the API.
• If a profile update is attempted for a locked account, the following response will be returned:

HTTP Status: 200
Code: 5
subCode: 362
Description: A user profile cannot be updated for a locked account

Active Consumer Account Limits

Social Security Number (SSN) Limits

• Up to 1 active account with the same SSN per program is allowed
• Up to 3 lifetime accounts with the same SSN per program are allowed

Phone Limits

• Up to 2 active accounts with the same phone number per program are allowed
• Up to 10 lifetime accounts with the same phone number per program are allowed

Note: Updates requested for phone numbers that exceed the current phone limits will be declined.

Refer to Active Small Business Account Limits for details about small business account limit thresholds.