Create Counterparty

Request

This endpoint is used to create a new counterparty for a customer. You can create different types of counterparties, including ach, on-us, wire, and international_wire, by providing the relevant details in the request body.

Note: The account_number field for creating an on-us counterparty represents the Jiko network address of the pocket.

Note: The optional display_name field lets you assign a custom, human-friendly name to a counterparty — useful for distinguishing multiple counterparties that belong to the same legal entity. When set, it is returned on the counterparty and can be shown in place of the counterparty's default name.

Note: The optional id field lets you choose the counterparty's UUID instead of having Jiko generate one. Supplying it means you know the counterparty's ID before the call completes, which is useful when the create is subject to an approval workflow — the Location header of the 202 response points at that same ID, so you can correlate the approval with the counterparty it produces. It also makes a retry safe: re-sending an id that already exists is rejected with 409 (CounterpartyAlreadyExistsError) rather than creating a duplicate. Omit the field and Jiko assigns the ID.

The request body must conform to one of the request schemas. On success, it returns the newly created counterparty object.

Security

CodeBearer(Required scopes: customer.write)

Bodyapplication/jsonrequired

Any of:

routing_numberstring(Routing Number)required

identifierstring(Identifier)required

Bank Account Number or IBAN Number

identifier_codestring or null(Identifier Code)

Any of:

[DEPRECATED] This field is ignored. The identifier code is always set to WireCounterpartyIdentifierCode_DDA_D (Demand Deposit Account).

string

Enum:"SWIFT_BIC""CHIPS_PARTICIPANT""DIRECT_DEPOSIT_ACCOUNT""FED_ROUTING_NUMBER""SWIFT_ID_AND_ACCOUNT_NUMBER""CHIPS_IDENTIFIER""PASSPORT_NUMBER""TAX_IDENTIFICATION_NUMBER""DRIVERS_LICENSE_NUMBER""ALIEN_REGISTRATION_NUMBER"

addressobject(CounterpartyAddress)required

wire_instructionsstring or null(Wire Instructions)

Any of:

Any additional wire instructions required for the wire to be processed correctly.

<= 140 characters

string

counterparty_nameany(Counterparty name)required

verificationany(Verification)required

typestring(Type)required

Value:"wire"

ownership_typestring or null(Ownership Type)

Any of:

Relationship of the counterparty to the account holder. FIRST_PARTY means the counterparty is owned by the account holder, THIRD_PARTY means it is owned by a different entity.

string

Enum:"FIRST_PARTY""THIRD_PARTY"

display_namestring or null(Display Name)

Any of:

An optional custom display name for the counterparty, useful for distinguishing multiple counterparties that share the same legal name.

[ 1 .. 200 ] characters

string

idstring or null(Id)

Any of:

An optional client-chosen UUID to assign as the counterparty's id. Supply one to know the counterparty's ID before it is created — useful for correlating a create that goes through an approval flow, or for making a retry safe. Omit it and Jiko generates the ID. Reusing an ID that already exists is rejected with 409.

string (uuid)

curl -i -X POST \
  https://api.business.jiko.io/api/v2/counterparties/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "routing_number": "987654321",
    "identifier": "1234567890",
    "address": {
      "street_address": "2000 Allston Way",
      "street_address2": "",
      "city": "Berkeley",
      "postal_code": "94701",
      "state": "CA",
      "country": "US"
    },
    "wire_instructions": "Example wire instructions",
    "counterparty_name": {
      "first_name": "External",
      "last_name": "Accountholder",
      "type": "individual"
    },
    "verification": {
      "type": "incoming_wire",
      "wire_id": "e5449f18-2383-4772-8fec-9d90a8cb2542"
    },
    "type": "wire"
  }'

Responses

Successful Response

Bodyapplication/json

any

Response

// No response example