New service | **Last updated**: 14 May 2025

Important
This documentation is for preview purposes only.

# Manage a party

There are two ways to create a party:

* orchestrated -  add all details in one call
* modular - create a basic party and add details like payout instruments, balance accounts or beneficial owners later


Additionally, at any point when creating a party, you can request an identity verification check to be performed.

## Create a party

`POST` `https://access.worldpay-bsh.securedataplatform.com/parties`



Orchestrated
#### Orchestrated party creation

Add all the details of a party in one API call. Add personal or company details, [payout instruments](/products/parties/payout-instruments), [balance accounts](/products/parties/balance-accounts), and [beneficial owners](/products/parties/beneficial-owners) (companies only).

Request an [identity verification](/products/parties/verify-parties) check, to be performed on that party, in the same call.

#### Request/response example

You can see the full schema in our [API reference](/products/parties/openapi/parties).

Modular
#### Modular party creation

Create a party with basic details only and add more details, like [payout instruments](/products/parties/payout-instruments), [balance accounts](/products/parties/balance-accounts), and [beneficial owners](/products/parties/beneficial-owners) (companies only), later.

Request an [identity verification](/products/parties/verify-parties) check, to be performed on that party, in the same call.

#### Request example

#### Response example

{
  "identityVerificationState": "verified",
  "identityVerificationMethod": "identityVerificationService",
  "identityVerificationDate": "2024-12-19",
{
  "merchant": {
    "entity": "Zaibatsu Holding"
  },
  "partyReference": "Hosaka27384910",
  "partyType": "beneficiary",
  "typeCode": "person",
  "partyId": "parTH82wexHglhnBbzd6iJ7P0",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "residentialStatus": "resident",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "1847 Chiba City Complex",
      "address2": "Unit 42",
      "addressType": "home",
      "city": "Chiba",
      "state": "Tokyo Prefecture",
      "countryCode": "JP",
      "postalCode": "260-0013"
    }
  },
  "email": "case.mitchell@zaibatsu.jp"
  }
}
You can see the full schema in our [API reference](/products/parties/openapi/parties).

## Browse parties

Retrieve and explore information about all parties (persons, sole traders or companies) that you have previously created. This endpoint is essential for viewing all existing parties and their status and filtering parties based on their type and status. Results are paginated.

Browse previously created parties by sending a request to:

`GET` `https://access.worldpay-bsh.securedataplatform.com/parties`

optionally add filtering parameters:

* `active`  - return parties that are active (true or false)
* `type` -  type of parties to return (`person`, `soleTrader` or `company`)


or pagination options:

* `page` - positive whole number indicating which page of the selected parties to return. Greater than 0
* `size` - number of items listed per page


You can see the full schema in our [API reference](/products/parties/openapi/parties).

## View a party

View information of a party, previously created, using the `partyId` received in your party creation response.

`GET` `https://access.worldpay-bsh.securedataplatform.com/parties/{partyId}`

#### Request/response example

You can see the full schema in our [API reference](/products/parties/openapi/parties).

## Modify a party

You can modify certain party information.

`PUT` `https://access.worldpay-bsh.securedataplatform.com/parties/{partyId}`

Recommendation
We suggest fetching party information with a `GET` request and providing all the fields to our `PUT` endpoint, including changes for fields that need updating.

#### Request/response example

You can view the full schema in our [API reference](/products/parties/openapi/parties/updateparty).

## Deactivate a party

Parties are created as active by default. You can deactivate an active party by using the `partyId` on our dedicated endpoint:

`POST` `https://access.worldpay-bsh.securedataplatform.com/parties/{partyId}/deactivation`

You must provide the `deactivationReason` (possible values: `"partyDormant"`, `"partyClosed"`, `"partySanctioned"`) and optionally `dispositionOfFunds` (default: `"payoutToParty"`).

#### Request/response example

In the response, you receive a `dateTimeDeactivated` field with the date and time when party was deactivated.

You can see the full schema in our [API reference](/products/parties/openapi/parties).

## Reactivate a party

Parties are created as active by default. You can reactivate a previously deactivated party by using the `partyId` on our dedicated endpoint:

`POST` `https://access.worldpay-bsh.securedataplatform.com/parties/{partyId}/activation`

And setting the `active` flag to `"true"`.

#### Request/response example

In the response, you receive a `dateTimeActivated` field with the date and time when party was activated.

You can see the full schema in our [API reference](/products/parties/openapi/parties).

## Delete a party

**Coming soon**

In this current version you will only be able to mark a party as inactive.

#### Next steps

[Add a payout instrument](/products/parties/payout-instruments)
[Manage beneficial owners](/products/parties/beneficial-owners)
[Add balance accounts](/products/parties/balance-accounts) or 
[Verify a party](/products/parties/verify-parties)