Users API Overview

The Users APIs offers a comprehensive set of endpoints for managing user profiles, validating personal and financial information, handling credit details, and managing identity‑related processes within a program/account context.

Profile Management User Endpoints

Update User – Updates an existing user profile.

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

Updates the user profile for the specified user identifier. Only the fields provided in the request will be updated. Returns the updated user details or validation errors.

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.

Response Codes

Locked Account 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.

Update User Name

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

Updates the legal name of a user due to a legal event such as marriage, divorce, or court order. Requires supporting documentation and may trigger card re-issuance and CRM case creation.

Add Consumer Profile Attachment – Uploads an attachment to a user's consumer profile.

POST /programs/{programCode}/users/{userIdentifier}/uploadAttachment

Uploads an attachment to the specified user's consumer profile. The request must include the attachment data and metadata. Returns the result of the upload operation.

Get Consumer Profile Extension – Retrieves extension attributes for a user's consumer profile.

GET /programs/{programCode}/users/{userIdentifier}/consumerProfileExtension

Retrieves extension attributes for the specified user's consumer profile. Returns the requested attributes or all supported attributes if none are specified.

Identity & SSN User Verification Endpoints

Validate SSN – Validates the Social Security Number (SSN) for a user.

POST /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/ValidateSsn

Validates the Social Security Number (SSN) for the specified user. Returns validation status and any errors encountered during the process.

Get Validate SSN – Retrieves the SSN validation status for a user.

Retrieves the SSN validation status for the specified user and account. Returns the validation status and any related information.

Validate Identity – Validates the identity information for a user.

POST /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/ValidateIdentity

Validates the identity information for the specified user. Returns validation status and any errors encountered during the process.

Get Validate Identity – Retrieves the identity validation status for a user.

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

Retrieves the identity validation status for the specified user and account. Returns the validation status and any related information.

Get Users Requiring ID Verification – Retrieves a list of users who require identity verification (IDV) for a given account.

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

Retrieves a list of users who require identity verification (IDV) for the specified account. Returns the list of users and their verification status.

Credit Information User Endpoints

Get Credit Line Range – Retrieves the eligible credit line range for an account based on income and expense information.

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

Retrieves the eligible credit line range for the specified account based on provided income and expense information. Returns the calculated range or an error if the input is invalid.

Update Credit Line Source – Updates the source information for a credit line on an account.

PUT /programs/{programCode}/accounts/{accountIdentifier}/creditLinesSource

Updates the source information for a credit line on the specified account. Returns the result of the update operation.

Get Credit Scores – Retrieves credit scores for a user associated with an account.

POST /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/getCreditScores

Retrieves credit scores for the specified user and account. Optional date range filters can be provided. Returns the user's credit scores and related information.

Customer Name Change

The Customer Name Change API provides customers with a seamless experience when requesting a name change due to a legal event such as marriage, divorce, court order, etc.

Prior to this feature, name-change requests required customers to provide the following confidential documents to both the Partner and to Green Dot:

• Driver’s License or State ID
• Marriage/Divorce Certificate (if applicable)
• Certified court order for legal name change

With this feature, customers provide the information only once under a secure, controlled process.

By design, the API operates under two Customer ID Program (CIP) processes:

• BaaS Partner Managed CIP
• Green Dot Managed CIP

Following is a description of the BaaS Partner Managed CIP process.

Note: The Green Dot Managed CIP is still under development and will be available in a future release.

BaaS Partner Managed CIP Flow

How It Works

1. The customer sends the Partner a name-change request due to a legal event (marriage, divorce, legal name change, etc.).
2. The Partner requests the supporting legal documents (marriage certificate, divorce certificate, certified court order for name change).
3. The customer provides the requested documents.
4. The Partner validates the documents (CIP + OFAC) and approves the name-change request.
   NOTE: Per the BSA (Bank Secrecy Act 31 CFR 1010.100), customer name-change records should be maintained for at least five years.
5. The Partner sends the Name Change API request to BaaS endpoint.
6. BaaS Core performs the following:
   1. Updates the database with the new name.
   2. Sends a Publish Notification to the Partner confirming a successful name change.
   3. Issues new cards automatically.
   4. Calls CRM to create a case for documenting the name change.

Customer Name Change API Endpoints

Update User Name

Updates the legal name of a user due to a legal event such as marriage, divorce, or court order. Requires supporting documentation and may trigger card re-issuance and CRM case creation.

NOTE: The user's information must be encrypted. This endpoint is intended only to change the user's first, middle, and last names following a legal name change.

API Call Structure

PUT /accounts/{accountIdentifier}/users/{userIdentifier}/name)

Sample Partner User Name Change Request - Decrypted View

{
    "ProfileData": {
	"FirstName": "Happy",
	"LastName": "Lucky",
	"MiddleName": "Go"
    }
}

Sample Partner User Name Change Request - Encrypted View

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

Partner Request Parameters

• firstName -- Required. The customer’s current name as shown on documents provided for the name-change request.
• middleName - Optional. The customer’s middle name as shown on documents provided for the name-change request.
• lastName - Required. The customer’s last name as shown on documents provided for the name-change request.

Response Body

{
    "responseHeader": {
	"responseId": "cfd06987-47cd-4924-b3e6-367cb8cdb6e6",
	"statusCode": 0,
	"subStatusCode": 0,
	"message": "Success"
    }
}