Updating an Account
Endpoint: POST {{baseUrl}}/account-api/v1/update-account
- The FinX Account API supports both account onboarding and updates to existing accounts through a secure and controlled endpoint.
- The Update Account endpoint enables client data modifications either field-by-field or by entire logical block, while strictly enforcing FinX validation rules and ensuring compliance with internal system checks.
- Immutable identifiers such as registrationType, entityNumber, taxId, and other system-controlled fields cannot be altered, thereby maintaining data integrity.
- Each update request is validated, mapped, and applied atomically, ensuring that any invalid input immediately halts the process.
- This guarantees that account information remains consistent and that the system returns clear, descriptive success or error messages for every operation.
Scope
Two supported update modes:
Field-by-field: Change just a couple of propertiesBlock: Replace an entire logical section
Process A: Update field by field for a registration type
- A
field-levelupdate allows modification of individual subfields within a specific block for a given registration type. - This means only selected fields can be updated without affecting the rest of the data in that block.
{
"accountNumber": "10003382",
"entityNumber": "301",
"main": {
"repCode": "JC01"
},
"primaryOwner": {
"email": "[email protected]"
}
}
Pre-checks:
- Verify accountId exists and is in a mutable status.
- Reject payload if any immutable field is included (e.g., registrationType, entityNumber).
Validate Field:
- Schema/type validation for each field.
- Apply FinX Validations
- Apply Changes (Atomic): Apply all field updates in a single transaction for the specified properties only. If any field fails, rollback all changes.
Process B: Update by block for a registration type
- A
block-levelupdate allows modification of an entire block, which includes all the fields grouped under that block, for a given registration type. - This means the complete set of fields within that block can be updated together in a single operation.
{
"accountNumber": "10003382",
"entityNumber": "301",
"main": {
"repCode": "JC01"
},
"primaryOwner": {
"legalAddress":
{
"street": "62 BLUE SPRUCE LS",
"city": "BALLSTON LAKE",
"stateProvince": "NY",
"country": "US",
"postalCode": "12019"
}
}
}
Pre-checks:
- Verify accountId and mutable status.
- Ensure the block is supported and no immutable fields are nested within the block update.
Validate Block:
- Full block schema validation.
- FinX evaluation, including inter-field dependencies within the block.
info
Upon successful completion, the API responds with a change summary, detailing all updated fields or blocks. To confirm successful onboarding or updates, clients should retrieve and verify the account details using the Get Account endpoint, ensuring that all intended changes are accurately reflected.
Get Endpoint Response
{
"statusCode": 200,
"message": "Request successful.",
"data": {
"message": {
"registrationType": "Individual",
"main": {
"repCode": "JC01",
"proxyDisclosure": "L"
},
"electronicDelivery": {
"email": "[email protected]",
"statements": "False",
"confirms": "False",
"stonexCommunications": "True",
"investorCommunications": "True",
"prospectus": "True",
"taxDocuments": "False"
},
"mailingAddress": {
"street": "390 PARK AVENUE SOUTH",
"city": "NEW YORK",
"stateProvince": "NY",
"country": "US",
"postalCode": "10022"
},
"accountNumber": "10003382",
"primaryOwner": {
"sourceOfFunds": [
"Employment",
"Other"
],
"otherSourceOfFund": "OTHERTESTING",
"firstName": "JOHN",
"middleName": "DAVIDD",
"lastName": "DOE",
"citizenshipCountry": "US",
"birthDate": "1975-05-25",
"email": "[email protected]",
"legalAddress": {
"street": "62 BLUE SPRUCE LS",
"city": "BALLSTON LAKE",
"stateProvince": "NY",
"country": "US",
"postalCode": "12019"
},
"occupation": "AccountingOrAuditing",
"jobTitle": "SOFTWARE DEVELOPER",
"employerName": "ABC ACCOUNTING",
"employerPhoneNumber": "5205123987",
"employerAddress": {
"street": "2 PERIMETER PARK S",
"city": "BIRMINGHAM",
"stateProvince": "AL",
"country": "US",
"postalCode": "35243"
},
"taxIdType": "SSN",
"taxIdNumber": "123456788",
"governmentIdentification": {},
"phoneNumberCell": "2059871212",
"phoneNumberHome": "9992986495",
"phoneNumberBusiness": "1234567890",
"caisInformation": {
"customerType": [
"Advisor"
],
"accountType": [
"Institution",
"Retirement"
],
"role": "AUTH"
},
"trustedContact": {
"name": "JANE SMITH",
"relationship": "SPOUSE",
"phoneNumber": "2056786578",
"email": "[email protected]",
"address": {
"street": "459 SOUTH SEGUNBAGICHA",
"city": "RAMNA",
"stateProvince": "NY",
"country": "US",
"postalCode": "35243"
}
},
"affiliation": {
"political": "True",
"relationship": "CHILD",
"name": "JOHN DOE",
"organization": "EXAMPLE ORGANIZATION",
"address": {
"street": "1234 ELMWOOD CRESCENT AVENUES SPRINGFIEDS IL BOOMER",
"city": "BOSTON",
"stateProvince": "AL",
"country": "US",
"postalCode": "35243"
}
},
"maritalStatus": "Divorced",
"dependents": "3"
},
"associatedParties": [
{
"role": "Secondary",
"financialProfile": {
"investmentExperience": {
"stocks": "Average",
"bonds": "Extensive",
"options": "Limited",
"mutualFunds": "Extensive",
"annuities": "None"
}
},
"firstName": "JOHNNY",
"middleName": "JACK",
"lastName": "TEST1",
"suffix": "MR",
"citizenshipCountry": "US",
"birthDate": "1983-12-13",
"email": "[email protected]",
"legalAddress": {
"street": "193 NOYATOLA MOGHBAZAR",
"city": "RAMNA",
"stateProvince": "AL",
"country": "US",
"postalCode": "22333"
},
"employerName": "STONEX1",
"employerPhoneNumber": "5205123987",
"employerAddress": {
"street": "2 PERIMETER PARK S",
"city": "BOSTON",
"stateProvince": "MA",
"country": "US",
"postalCode": "21345"
},
"taxIdType": "TaxId",
"taxIdNumber": "123456789",
"governmentIdentification": {},
"phoneNumberCell": "2059871212",
"caisInformation": {
"customerType": [
"Advisor"
],
"accountType": [],
"role": "AUTH"
},
"maritalStatus": "Married",
"dependents": "2"
}
],
"financialProfile": {
"annualIncome": "F",
"netWorth": "B",
"liquidNetWorth": "B",
"liquidityNeed": "None",
"liquidityTime": "Medium",
"taxBracket": "TenToFifteen",
"investmentTimeHorizon": "OneToThreeYears",
"investmentProfile": "Moderate",
"investmentExperience": {
"stocks": "Limited",
"bonds": "None",
"options": "None",
"mutualFunds": "Limited",
"annuities": "Limited"
}
},
"beneficiaries": [
{
"primaryContingent": "Primary",
"name": "PRIMARY BENE 1",
"address": {
"street": "123 MAIN ST",
"city": "MOUNTAIN BRK",
"stateProvince": "AL",
"country": "US",
"postalCode": "35216"
},
"birthDate": "2003-07-23",
"taxIdNumber": "123456770",
"relationship": "Spouse",
"percentageAllocation": "10"
},
{
"primaryContingent": "Primary",
"name": "PRIMARY BENE 2",
"address": {
"street": "123 MAIN ST",
"city": "MOUNTAIN BRK",
"stateProvince": "AL",
"country": "US",
"postalCode": "35216"
},
"birthDate": "2006-01-30",
"taxIdNumber": "123456771",
"relationship": "Other",
"percentageAllocation": "10"
}
]
}
},
"errors": [],
"traceId": "00-ac1702cb06e3593828edbff1ae1a2649-70cf1759a54a8a17-01",
"hasErrors": false
}
The Get Account endpoint ({{baseUrl}}/account-api/v1/get-account) is used to retrieve and verify the final account data, ensuring all updates are reflected accurately.