POST/application/submit-individual

Upsert Individual

Creates or updates one individual (officer/UBO) on a Business application. Not applicable to Individual Plus applications.

Create: Omit Id. A new individual record is added to the application.
Update: Include Id (the individual ID from a previous response) and Version. The entire individual record is fully replaced — send the full payload every time.

Field requirements are role-dependent: IsShareHolder and IsAuthorizedUser are asked of everyone. Dob, Nationality, Email, TaxId, and Address are required for shareholders, authorized users, independent directors, and control persons. MotherMaidenName, Role, AccessType, IsAuthorizedContact, and IsAgentWithAttorneyPower are required only when IsAuthorizedUser is true. Ssn is additionally required for US individuals.

Optimistic locking: Send the Version from the last response on update. Stale version → dirty_update.

Headers

Field	Type	Required	Possible values	Description
`session-token`	string	Required	—	SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header.

Request body

Field	Type	Required	Possible values	Description
`ApplicationId`	string	Required	—	The business application ID (returned from `POST /application/submit-form`).
`FirstName`	string	Required	—	First name. Required for shareholders, authorized users, independent directors, and control persons.
`LastName`	string	Required	—	Last name. Required for shareholders, authorized users, independent directors, and control persons.
`Email`	string	Required	—	Email address. Must be globally unique. Required for shareholders, authorized users, independent directors, and control persons.
`IsShareHolder`	boolean	Required	—	Is this individual a shareholder?
`IsAuthorizedUser`	boolean	Required	—	Is this individual an authorized user?
`Address`	object	Required	—	Residential address. Required for shareholders, authorized users, directors, and control persons.
`Address.Street`	string	Required	—	Street name
`Address.BuildingNumber`	string	Required	—	Building or house number
`Address.City`	string	Required	—	City name
`Address.State`	string	Required	—	State or province name
`Address.PinCode`	string	Required	—	Postal or ZIP code
`Address.Country`	string	Required	—	ISO Alpha-2 country code (e.g. US)
`Id`	string \| null	Optional	—	`null` or absent to create a new individual. Set to the individual's `Id` from a previous response to update.
`Version`	integer	Optional	—	Optimistic lock version. Send the `Version` from the last response on update. Stale value → `dirty_update` (400). Omit to skip the check.
`MotherMaidenName`	string	Optional	—	Mother's maiden name. Required when `IsAuthorizedUser` is `true`.
`Dob`	string	Optional	yyyyMMdd	Date of birth. Format: `yyyyMMdd`. Required for shareholders, authorized users, independent directors, and control persons.
`Nationality`	string	Optional	e.g. US	ISO 3166-1 alpha-2 nationality. Required for shareholders, authorized users, independent directors, and control persons.
`MobileCountryCode`	integer	Optional	e.g. 1	International dialing code for `MobilePhone` (e.g. `1` for US). Required for shareholders, authorized users, independent directors, and control persons.
`MobilePhone`	string	Optional	—	Mobile phone number (digits only). Must be globally unique. Required for shareholders, authorized users, independent directors, and control persons.
`TaxId`	string	Optional	—	Tax ID number. Min: 1, Max: 20 characters. Required for shareholders, authorized users, independent directors, and control persons.
`CountryOfIssuance`	string	Optional	e.g. US	Country of issuance for the Tax ID. ISO 3166-1 alpha-2. Required for shareholders, authorized users, independent directors, and control persons.
`Ssn`	string	Optional	—	Social Security Number (9 digits, no hyphens). Additionally required when `Nationality` or `Address.Country` is `US`.
`PercentOwner`	number	Optional	—	Ownership percentage.
`IsControlPerson`	boolean	Optional	—	Is this individual a control person (significant management responsibility)?
`IsDirector`	boolean	Optional	—	Is this individual a director? Required when `IsShareHolder`, `IsAuthorizedUser`, or `IsControlPerson` is `true`.
`IsIndependentDirector`	boolean	Optional	—	Is this individual an independent director? Required when `IsShareHolder`, `IsAuthorizedUser`, and `IsControlPerson` are all `false`.
`IsPrimaryUser`	boolean	Optional	—	Is this individual the primary user? Setting to `true` clears the flag from all other individuals.
`HaveControlOverEntity`	boolean	Optional	—	Does this individual have control over the entity?
`IsAuthorizedContact`	boolean	Optional	—	Is this individual an authorized contact? Required when `IsAuthorizedUser` is `true`.
`IsAgentWithAttorneyPower`	boolean	Optional	—	Is this individual operating under power of attorney? Required when `IsAuthorizedUser` is `true`.
`Role`	string (enum)	Optional	ceo \| cfo \| coo \| president \| vice_president \| partner \| manager \| other	Individual's role. Required when `IsAuthorizedUser` is `true`.
`AccessType`	string (enum)	Optional	StdViewer (Viewer) \| StdBasic (Basic User) \| StdApprover (Approver) \| NoGroup (Power User)	Account access level. Required when `IsAuthorizedUser` is `true`.
`SourceOfWealthList`	array<string> (enum)	Optional	employment_compensation \| retirement_pension \| proceeds_from_sale \| inheritance \| gifts_from_family \| bank_loan \| family_loan \| income_legal_settlements \| casino_lottery_winnings \| investments	Source(s) of wealth (multi-select).
`Card`	number	Optional	e.g. 1	Card preference flag (e.g. `1`). Used with address country for Visa debit card eligibility.
`MailingAddress`	object	Optional	—	Mailing address. Same shape as `Address`.
`MailingAddress.Street`	string	Optional	—	Street name
`MailingAddress.BuildingNumber`	string	Optional	—	Building or house number
`MailingAddress.City`	string	Optional	—	City name
`MailingAddress.State`	string	Optional	—	State or province name
`MailingAddress.PinCode`	string	Optional	—	Postal or ZIP code
`MailingAddress.Country`	string	Optional	—	ISO Alpha-2 country code (e.g. `US`)

Example request

{
  "ApplicationId": "6a585058e557d865e30a8d4f",
  "FirstName": "John",
  "LastName": "Smith",
  "MotherMaidenName": "Doe",
  "Dob": "19800101",
  "Nationality": "US",
  "Email": "john.smith10@example.com",
  "MobileCountryCode": 91,
  "MobilePhone": "9871236540",
  "TaxId": "123456789",
  "Ssn": "123456789",
  "CountryOfIssuance": "US",
  "IsPrimaryUser": true,
  "IsShareHolder": true,
  "PercentOwner": 100,
  "IsAuthorizedUser": true,
  "Role": "ceo",
  "AccessType": "NoGroup",
  "IsAuthorizedContact": true,
  "IsAgentWithAttorneyPower": false,
  "IsDirector": true,
  "IsIndependentDirector": false,
  "IsControlPerson": true,
  "HaveControlOverEntity": true,
  "SourceOfWealthList": [
    "employment_compensation"
  ],
  "Address": {
    "Street": "5th Avenue",
    "BuildingNumber": "100",
    "City": "New York",
    "State": "NY",
    "PinCode": "10001",
    "Country": "US"
  },
  "Card": 1,
  "MailingAddress": {
    "Street": "5th Avenue",
    "BuildingNumber": "100",
    "City": "New York",
    "State": "NY",
    "PinCode": "10001",
    "Country": "US"
  }
}

{
  "ApplicationId": "6a585058e557d865e30a8d4f",
  "FirstName": "John",
  "LastName": "Smith",
  "MotherMaidenName": "Doe",
  "Dob": "19800101",
  "Nationality": "US",
  "Email": "john.smith10@example.com",
  "MobileCountryCode": 91,
  "MobilePhone": "9871236540",
  "TaxId": "123456789",
  "Ssn": "123456789",
  "CountryOfIssuance": "US",
  "IsPrimaryUser": true,
  "IsShareHolder": true,
  "PercentOwner": 100,
  "IsAuthorizedUser": true,
  "Role": "ceo",
  "AccessType": "NoGroup",
  "IsAuthorizedContact": true,
  "IsAgentWithAttorneyPower": false,
  "IsDirector": true,
  "IsIndependentDirector": false,
  "IsControlPerson": true,
  "HaveControlOverEntity": true,
  "SourceOfWealthList": [
    "employment_compensation"
  ],
  "Address": {
    "Street": "5th Avenue",
    "BuildingNumber": "100",
    "City": "New York",
    "State": "NY",
    "PinCode": "10001",
    "Country": "US"
  },
  "Card": 1,
  "MailingAddress": {
    "Street": "5th Avenue",
    "BuildingNumber": "100",
    "City": "New York",
    "State": "NY",
    "PinCode": "10001",
    "Country": "US"
  }
}

Email and MobilePhone must be unique across the entire platform. Submitting a duplicate email or mobile number returns a 400 error.

A 423 Application Locked response is returned when the application is in a locked or final status.

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 301 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 503	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	The saved individual record. Use `Id` and `Version` on subsequent updates.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "Version": 0,
    "Id": "6a5854ace557d865e30a8d75",
    "ApplicationId": "6a585058e557d865e30a8d4f",
    "FirstName": "John",
    "LastName": "Smith",
    "MotherMaidenName": "Doe",
    "Dob": "19800101",
    "Nationality": "US",
    "Email": "john.smith10@example.com",
    "MobileCountryCode": 91,
    "MobilePhone": "9871236540",
    "TaxId": "123456789",
    "Ssn": "123456789",
    "CountryOfIssuance": "US",
    "IsPrimaryUser": true,
    "IsShareHolder": true,
    "PercentOwner": 100,
    "IsAuthorizedUser": true,
    "Role": "ceo",
    "AccessType": "NoGroup",
    "IsAuthorizedContact": true,
    "IsAgentWithAttorneyPower": false,
    "IsDirector": true,
    "IsIndependentDirector": false,
    "IsControlPerson": true,
    "HaveControlOverEntity": true,
    "SourceOfWealthList": [
      "employment_compensation"
    ],
    "Address": {
      "City": "New York",
      "State": "NY",
      "Country": "US",
      "PinCode": "10001",
      "Street": "5th Avenue",
      "BuildingNumber": "100"
    }
  }
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "Version": 0,
    "Id": "6a5854ace557d865e30a8d75",
    "ApplicationId": "6a585058e557d865e30a8d4f",
    "FirstName": "John",
    "LastName": "Smith",
    "MotherMaidenName": "Doe",
    "Dob": "19800101",
    "Nationality": "US",
    "Email": "john.smith10@example.com",
    "MobileCountryCode": 91,
    "MobilePhone": "9871236540",
    "TaxId": "123456789",
    "Ssn": "123456789",
    "CountryOfIssuance": "US",
    "IsPrimaryUser": true,
    "IsShareHolder": true,
    "PercentOwner": 100,
    "IsAuthorizedUser": true,
    "Role": "ceo",
    "AccessType": "NoGroup",
    "IsAuthorizedContact": true,
    "IsAgentWithAttorneyPower": false,
    "IsDirector": true,
    "IsIndependentDirector": false,
    "IsControlPerson": true,
    "HaveControlOverEntity": true,
    "SourceOfWealthList": [
      "employment_compensation"
    ],
    "Address": {
      "City": "New York",
      "State": "NY",
      "Country": "US",
      "PinCode": "10001",
      "Street": "5th Avenue",
      "BuildingNumber": "100"
    }
  }
}

A 400 with `invalid_param` is returned if the email or mobile phone is already in use. A 400 with `record_not_found` is returned if the `ApplicationId` does not exist.

ℹ Note

A 423 Application Locked response is returned when the application is in a locked or final status. No further modifications are permitted until FV Bank unlocks the application.

ℹ Note

On 400 validation errors, each error in ResponseErrors includes a Field property that identifies the failing PascalCase request body field (e.g. Business.Phone, Email, Address.City). Use this to surface precise field-level error messages in your UI.

Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.