Optimization Protection

Update party information

Update related party information or submit changes to the organization after your client is approved and live. This replaces coordinating updates through support channels to update supported fields, add related parties, and deactivate related parties.

Use this feature for clients in the United States and Canada with supported legal entity types.

Before you begin

Confirm the client is in APPROVED status before starting post-onboarding updates.

How the update process works

Follow these steps to process an update.

Start a request: Create an update by sending a PATCH request to /onboarding/v1/parties/{partyId} for an onboarded client, or for a party that belongs to an onboarded client. Send only the fields that have changed.
1. To add a new related party, send a POST request to /onboarding/v1/parties.
2. When the request is in draft (NEW status), the system bundles multiple changes made through multiple patch requests under the same requestId.
Submit for review: Upload and submit the required documents listed in the outstanding block, if applicable. Complete required attestations, then send a POST request to /onboarding/v1/clients/{id}/verifications to submit.
Receive notification upon completion: Notifications return APPROVED or DECLINED outcomes. GET responses show approved data within 24 to 48 hours after the approval. Refer to the next steps section for details.

Each client supports only one open requestId at a time. To start a new request, complete the existing request if it has been submitted. If the request remains in NEW status, cancel it by sending a DELETE request to /onboarding/v1/maintenance-requests/{requestId}.

Understand the updateRequest object

The updateRequest object tracks each change and manages the lifecycle from draft to final outcome. After you submit an update, the response includes the updateRequest object, which has the following attributes:

requestId: Unique identifier for the update request. Only one is active per client.
status: Current lifecycle status. Refer to the request status lifecycle.
action: Update action: ADD, MODIFY, or DELETE.
submittedAt: Timestamp when the system receives the request.

Request status lifecycle

The following table explains the updateRequest.status lifecycle:

`updateRequest.status` lifecycle
Status	Details
`NEW`	The system creates the request in the initial draft state. Changes remain available before submission.
`REVIEW_IN_PROGRESS`	The system moves the request to this status after you call `/verifications`. You cannot make further changes.
`INFORMATION_REQUESTED`	The system requires additional information during processing.
`APPROVED`	The system processed and approved the request. Terminal state.
`DECLINED`	The system processed but declined the request. Terminal state.
`TERMINATED`	The system canceled or auto-closed the request. Terminal state.

A TERMINATED status occurs in any of the following scenarios:

The platform cancels the request before calling /verifications.
The client does not respond to information requests within 30 days.
The updated country is not supported.
The updated country is supported, and the request includes a different tax identification number that requires new onboarding.

Allowed updates

This section includes relevant notes, sample requests, and responses for the following update scenarios.

Allowed updates
Update scenario	Notes
Modify client legal name or doing business as (DBA) name	Send a request with the changed fields. For sole proprietorships, include `firstName`, `middleName`, and `lastName`. Provide documentation for name changes: Send a `GET` request to `/onboarding/v1/clients/{id`}. Check the `outstanding` object in the client response for required documents. Upload the documents. The API leaves the persisted `dbaName` unchanged in the response body. The API shows the pending changes in the `updateRequest` block.
Modify client address	Send a request with the updated address. Send only supported address types. The API moves the request to `TERMINATED` if the updated country is unsupported or sanctioned. Send a `GET` request to `/onboarding/v1/clients/{id}` and check the `outstanding` object in the client response for required documents, then upload the documents. The API leaves the persisted address unchanged in the response body. The API shows the pending changes in the `updateRequest` block.
Add a related party	To add a new related party such as `BENEFICIAL_OWNER` or `CONTROLLER` to an already-onboarded client, send a request with the `parentPartyId` of the client organization. A new party undergoes identity verification and Know Your Customer (KYC) checks. Provide Financial Crimes Enforcement Network (FinCEN) attestation for `BENEFICIAL_OWNER` or `CONTROLLER` updates. Send a `GET` request to `/onboarding/v1/clients/{id}` and check the `outstanding` object in the client response for required documents, then upload the documents. The API leaves the persisted party `roles` unchanged in the response body. The API shows the pending changes in the `updateRequest` block.
Remove a related party	Set `active`: `false`. If removing the only `CONTROLLER`, provide a replacement `CONTROLLER`.
Modify a related party	Update `individualDetails.firstName`, `individualDetails.middleName`, `individualDetails.lastName`, and `individualDetails.birthDate`. Send only the fields that changed. Provide documentary evidence. The API returns the current persisted values in the response, not the submitted changes. The `updateRequest` object reflects the pending changes.

Modify client legal name or DBA name

The following is an example of modifying a client legal name or DBA name.

Method: PATCH

Endpoint: /onboarding/v1/parties/{partyId}

Request:

Json

{
  "organizationDetails": {
    "dbaName": "DBA NAME UPDATED"
  }
}

Response:

Json

{
  "id": "2000000035",
  "partyType": "ORGANIZATION",
  "roles": ["CLIENT"],
  "organizationDetails": {
    "organizationName": "Original Legal Name LLC",
    "dbaName": "RAINBOW",
    "addresses": [
      {
        "addressType": "BUSINESS_ADDRESS",
        "addressLines": ["8934 Geary Blvd."],
        "city": "San Francisco",
        "postalCode": "94105",
        "country": "US"
      }
    ],
    "countryOfFormation": "US",
    "website": "www.yahoo.com"
  },
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "MODIFY",
    "submittedAt": "2026-03-13T14:35:00Z"
  }
}

Modify client address

The following is an example of modifying a client address.

Method: PATCH

Endpoint: /onboarding/v1/parties/{partyId}

Request for single address:

Json

{
  "organizationDetails": {
    "addresses": [
      {
        "addressType": "BUSINESS_ADDRESS",
        "addressLines": [
          "300 Candy St.",
          "Suite 500"
        ],
        "city": "Redwood City",
        "state": "CA",
        "postalCode": "94603",
        "country": "US"
      }
    ]
  }
}

Request for multiple addresses:

Json

{
  "organizationDetails": {
    "addresses": [
      {
        "addressType": "BUSINESS_ADDRESS",
        "addressLines": ["100 Main Street"],
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      },
      {
        "addressType": "MAILING_ADDRESS",
        "addressLines": ["PO Box 12345"],
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      }
    ]
  }
}

Response:

Json

{
  "id": "2000000035",
  "partyType": "ORGANIZATION",
  "roles": ["CLIENT"],
  "organizationDetails": {
    "organizationName": "Original Legal Name LLC",
    "dbaName": "RAINBOW",
    "addresses": [
      {
        "addressType": "BUSINESS_ADDRESS",
        "addressLines": ["8934 Geary Blvd."],
        "city": "San Francisco",
        "postalCode": "94105",
        "country": "US"
      }
    ],
    "countryOfFormation": "US",
    "industryCategory": "Agriculture, Forestry, Fishing and Hunting",
    "industryType": "Soybean Farming",
    "website": "www.yahoo.com"
  },
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "MODIFY",
    "submittedAt": "2026-03-13T14:30:00Z"
  }
}

The following is an example of adding a related party.

Method: POST

Endpoint: /onboarding/v1/parties

Request:

Json

{
  "parentPartyId": "2000000035",
  "partyType": "INDIVIDUAL",
  "roles": ["BENEFICIAL_OWNER"],
  "individualDetails": {
    "firstName": "David",
    "lastName": "Smith",
    "birthDate": "1990-01-01",
    "addresses": [
      {
        "addressType": "RESIDENTIAL_ADDRESS",
        "addressLines": [
          "300 Candy St.",
          "Suite 500"
        ],
        "city": "Redwood City",
        "state": "CA",
        "postalCode": "94603",
        "country": "US"
      }
    ],
    "natureOfOwnership": "Direct",
    "countryOfResidence": "US",
    "individualIds": [
      {
        "idType": "SSN",
        "value": "444331111",
        "issuer": "US"
      }
    ],
    "jobTitle": "CEO"
  }
}

Response:

Json

{
  "id": "2000000040",
  "partyType": "INDIVIDUAL",
  "roles": ["BENEFICIAL_OWNER"],
  "active": true,
  "profileStatus": "NEW",
  "individualDetails": {
    "firstName": "David",
    "lastName": "Smith",
    "birthDate": "1990-01-01",
    "addresses": [
      {
        "addressType": "RESIDENTIAL_ADDRESS",
        "addressLines": ["300 Candy St.", "Suite 500"],
        "city": "Redwood City",
        "state": "CA",
        "postalCode": "94603",
        "country": "US"
      }
    ],
    "natureOfOwnership": "Direct",
    "countryOfResidence": "US",
    "individualIds": [
      {
        "idType": "SSN",
        "value": "444331111",
        "issuer": "US"
      }
    ],
    "jobTitle": "CEO"
  },
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "ADD",
    "submittedAt": "2026-03-13T14:30:00Z"
  }
}

The following is an example of removing a related party.

Method: PATCH

Endpoint: /onboarding/v1/parties/{partyId}

Request:

Json

{
  "active": false
}

Response:

Json

{
  "id": "2000000036",
  "partyType": "INDIVIDUAL",
  "roles": ["CONTROLLER"],
  "active": false,
  "individualDetails": {
    "firstName": "Original First",
    "lastName": "Original Last",
    "birthDate": "1990-01-01",
    "countryOfResidence": "US",
    "addresses": [
      {
        "addressType": "RESIDENTIAL_ADDRESS",
        "addressLines": ["300 Candy St.", "Suite 500"],
        "city": "Redwood City",
        "state": "CA",
        "postalCode": "94603",
        "country": "US"
      }
    ]
  },
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "MODIFY",
    "submittedAt": "2026-03-13T14:30:00Z"
  }
}

The following is an example of modifying a related party.

Method: PATCH

Endpoint: /onboarding/v1/parties/{partyId}

Request:

Json

{
  "individualDetails": {
    "firstName": "Updated First",
    "middleName": "Updated Middle",
    "lastName": "Updated Last"
  }
}

Response:

Json

{
  "id": "2000000035",
  "partyType": "INDIVIDUAL",
  "email": "super.user@testcompany.com",
  "roles": ["CONTROLLER"],
  "individualDetails": {
    "firstName": "Original First",
    "middleName": "Original Middle",
    "lastName": "Original Last",
    "birthDate": "1998-02-23",
    "countryOfResidence": "US",
    "addresses": [
      {
        "addressType": "BUSINESS_ADDRESS",
        "addressLines": ["8934 Geary Blvd."],
        "city": "San Francisco",
        "postalCode": "94105",
        "country": "US"
      }
    ],
    "individualIds": [
      {
        "idType": "SSN",
        "value": "100-01-0001",
        "issuer": "US"
      }
    ],
    "phone": {
      "countryCode": "+1",
      "phoneType": "BUSINESS_PHONE",
      "phoneNumber": "4153333343"
    }
  },
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "MODIFY",
    "submittedAt": "2026-03-13T14:30:00Z"
  }
}

Retrieve update requests

Check the status of update requests as follows:

Send a GET request to /onboarding/v1/maintenance-requests?clientId={clientId} to retrieve all update requests for a given clientId.
Send a GET request to /onboarding/v1/maintenance-requests?partyId={partyId} to retrieve all update requests for a given partyId.
Send a GET request to /onboarding/v1/maintenance-requests/{requestId} to retrieve update requests for a requestId.

Note

Only one update requestId is active at a time for a given clientId.

Sample partial response:

The following shows the relevant portion of a sample response:

Json

{
  "active": false,
  "updateRequest": {
    "requestId": "123456789",
    "status": "NEW",
    "action": "MODIFY"
  }
}

Cancel an update request

To cancel an update request before submission when the request is in NEW status, send a DELETE request to /onboarding/v1/maintenance-requests/{requestId}?partyId={partyId} to cancel the update for a specific party.

Canceling the request changes the updateRequest.status to TERMINATED.

Submit the update for review

When all changes, documents, and attestations are complete, submit by sending a POST request to /onboarding/v1/clients/{id}/verifications. This moves the updateRequest.status from NEW to REVIEW_IN_PROGRESS. All changes are final after submission.

Next steps

After submitting, monitor the request status by subscribing to the notification events webhook channel or by polling with a GET request to /onboarding/v1/maintenance-requests/{requestId}. If the status returns INFORMATION_REQUESTED, provide the additional information within 30 days to avoid automatic termination.

Notification events webhook channel

Upload documents

Update party information

Before you begin

How the update process works

Understand the updateRequest object

Request status lifecycle

Allowed updates

Modify client legal name or DBA name

Modify client address

Add a related party

Remove a related party

Modify a related party

Retrieve update requests

Cancel an update request

Submit the update for review

Next steps

Related