Save a new counterparty as a draft, to allow for further changes later.

draft` — Create Draft Counterparty

Saves a new counterparty as a draft. Drafts are stored in a not-yet-active state so you can build them up incrementally. Full business validation is not enforced by default — only field-size/format checks are applied so the record can be persisted.

The handler is CreateDraftCounterparty, which sets SaveAction = Draft and routes to the shared save pipeline. For an immediately-submitted counterparty use POST /counterparties/submit instead.

Permissions

Requires the Counterparty_Create permission.

Two-factor challenge may be triggered on submission flows (not on plain drafts).

Query parameters

Parameter	Type	Default	Description
`validate`	`bool`	`false`	When `true`, the draft is run through full submission-level validation instead of minimal storage checks. Use this to "dry-run" a draft before calling `submit`.

API versions

Version	Body type	Response type
`3`	`CounterpartyModelV3`	`CounterpartyModelV3`

Mandatory fields by scenario

Draft save (default, `validate=false`)

Minimal validation only. There are no mandatory business fields — only field-size/length limits are enforced so the record fits the database. This lets you save a partially-completed counterparty.

⚠️ A draft that saves successfully is not guaranteed to be submittable. Run with validate=true (or call submit) to confirm it is actually complete.

Full validation (`validate=true`) or submission

When full validation runs, the following rules apply.

Core counterparty fields

Field (JSON)	Required when	Notes
`primaryType`	Always	Must be `individual` or `corporate`. Any other value is rejected as `UNSUPPORTED_TYPE`.
`subType`	Always	Valid values depend on `primaryType` (see below). Invalid values are rejected as `UNKNOWN_SUBTYPE`.
`name`	Individuals; corporate `subsidiary`/`thirdParty`	Required in these cases.
`paymentReason`	When not `IsSelf`	At least one non-empty reason required. Combined length of all reasons must not exceed 240 characters.
Address fields	Validated separately	See `ValidateAddress`; use the structured `address` object (V3).

Subtype rules:

primaryType = individual → subType must be thirdParty. (The API auto-sets this for you if primaryType is individual.)

primaryType = corporate → subType must be one of internal, subsidiary, or thirdParty.

subsidiary / thirdParty → name is required.

`ValidateAddress` — Counterparty Address Validation

Validates the counterparty's structured address object (V3 format). This runs as part of full counterparty validation (e.g. on submit, or on draft when validate=true). It covers presence, field sizes, and country rules.

The `address` object (`CounterpartyAddressModel`)

JSON field	Required	Notes
`country`	Yes	Must be a known, valid ISO Alpha-2 country code.
`town`	Yes	City/town.
`streetName`, `buildingNumber`, `buildingName`, `floor`, `postBox`, `room`	No	Structured street detail.
`postCode`	No
`townLocation`	No
`district`, `countrySubdivision`	No
`department`, `subDepartment`	No

All supplied address fields are subject to length checks (CheckAddressFieldSizes).

Mandatory-address rules by scenario

Scenario	Is `address` required?	Offence if missing
New counterparty (no existing active/draft)	Yes	`Missing`
Existing counterparty that has no stored address and you omit `address`	Yes	`AddressUpdateRequired`
Existing counterparty that already has a stored address and you omit `address`	No — the stored address is kept unchanged	—

When address is present, the following are always enforced:

country and town must be non-empty (Missing otherwise).

country must match a known country (Invalid otherwise).

country must not be a blocked country if the country code has changed (BlockedCountry otherwise).

Account fields (per entry in `accounts[]`)

Accounts are only required/validated if supplied. For each account:

Field	Required	Notes
`alias`	Yes	Max 256 chars
`country`	Yes	Must be a known, non-blocked country.
`currencies`	Yes (≥1)	Every currency must be a valid, known currency code. Duplicates across `intermediaryBankAccounts` are rejected.
`preferredPaymentNetwork`	—	Only `SWIFT` is currently accepted.
`iban`	Conditional	If supplied, must be 15–32 chars and pass IBAN validation.
`bic_swift`	Conditional	Mandatory when an IBAN is supplied, except for UK/Ireland accounts paying `GBP`.
`accountNumber`	Country-specific	e.g. Spain (`es`) requires a 10-digit account number when no IBAN is given.
`bankName`	Yes
`bankTown`	Account-specific	Not yet released, but will be mandatory for accounts in US and missing BIC, or GB/Ireland country using GBP and missing IBAN or BIC - max 35 chars

Additional Notes

Drafts are permissive by design. With validate=false, almost nothing is mandatory. Do not assume a saved draft is valid for submission — validate explicitly.

Do not send id. If the body contains a populated id, the request is rejected (UnsupportedAction) — you've called the wrong endpoint (use the update endpoint for existing counterparties).

individual forces subType = thirdParty. Any subType you send for an individual is overwritten by the server.

paymentReason 240-char cap is a combined total across all array entries, not per-entry. Entries are trimmed and empties removed before the check.

paymentReason is required for non-self counterparties. A self counterparty skips this.

BIC/SWIFT trap for IBAN accounts: supplying an IBAN makes BIC/SWIFT mandatory — the only exception is UK/Ireland + GBP, where the bank town requirement covers routing instead.

IBAN auto-enrichment: when validated (not static-check-only), missing bankName, bankTown, and bic_swift may be auto-populated from the IBAN lookup. Values you send take precedence.

China (CN/CNY) CNAPS cannot be removed once present on an active account — but it is not mandatory for brand-new accounts.

Currency codes are normalised to upper-case and de-duplicated server-side.

preferredPaymentNetwork must be SWIFT — other networks are rejected as invalid.

Omitting address is "keep current", not "clear". If a counterparty already has an address and you don't send one, the existing one is retained — you cannot blank an address by omission.

Obsolete flat address fields (address1, city, country, etc.) and shortfall* are deprecated — use the V3 structured address object.

countryName is output-only — don't send it; it won't be read.

Response

Returns the created counterparty re-fetched by its `id'

curl --location 'https://api.demo.getneo.com/v3/counterparties/draft?validate=undefined' \ --header 'Content-Type: application/json' \ --data '{ "accounts": [ { "accountNumber": "string", "actions": [ "string" ], "additionalCountryAccountInfo": "string", "alias": "string", "bank": "string", "bankAccountId": "string", "bankTown": "string", "bankCode": "string", "bic_swift": "string", "cnaps": "string", "controls": { "corpRelationship": "sameEntity", "immediateIntraCorp": true }, "country": "string", "currencies": [ "string" ], "iban": "string", "intermediaryBank": "string", "intermediaryBankAccounts": [ { "bicSwift": "string", "currency": "string" } ], "isBeneficiary": true, "isPayer": true, "networks": { "neo": { "enabled": true, "reason": "string" }, "sepa": { "enabled": true, "reason": "string" }, "swift": { "enabled": true, "reason": "string" } }, "operatorInfo": "string", "parentId": "string", "recurringReference": "string", "routingNumber": "string", "sortCodeUK": "string", "verificationResponses": [ { "expireTime": "2019-08-24T14:15:22.123Z", "purpose": "sepaPayee", "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6", "responseState": "match", "suggestedName": "string", "timestamp": "2019-08-24T14:15:22.123Z" } ] } ], "actions": [ "string" ], "address": { "buildingName": "string", "buildingNumber": "string", "country": "string", "countrySubdivision": "string", "department": "string", "district": "string", "floor": "string", "postBox": "string", "postCode": "string", "room": "string", "streetName": "string", "subDepartment": "string", "town": "string", "townLocation": "string" }, "address1": "string", "address2": "string", "alias": "string", "city": "string", "country": "string", "county": "string", "currencies": [ "string" ], "draft": {}, "email": "string", "firstName": "string", "id": "string", "isBeneficiary": true, "isPayer": true, "isSelf": true, "lastName": "string", "linkedDocuments": { "count": 0, "uri": "string" }, "name": "string", "parent": { "alias": "string", "displayName": "string", "id": "string", "isSelf": true, "name": "string", "state": "incomplete", "vanityId": "string" }, "payable": { "enabled": true, "reason": "string" }, "paymentReason": [ "string" ], "postCode": "string", "primaryType": "string", "shortfall": 0, "shortfallCurrencyCode": "string", "state": "draft", "status": "draft", "subsidiary": "string", "subType": "string", "thirdPartyType": "string", "thirdPartyTypeOther": "string", "vanityId": "string" }'

{ "accounts": [ { "accountNumber": "string", "actions": [ "string" ], "additionalCountryAccountInfo": "string", "alias": "string", "bank": "string", "bankAccountId": "string", "bankTown": "string", "bankCode": "string", "bic_swift": "string", "cnaps": "string", "controls": { "corpRelationship": "sameEntity", "immediateIntraCorp": true }, "country": "string", "currencies": [ "string" ], "iban": "string", "intermediaryBank": "string", "intermediaryBankAccounts": [ { "bicSwift": "string", "currency": "string" } ], "isBeneficiary": true, "isPayer": true, "networks": { "neo": { "enabled": true, "reason": "string" }, "sepa": { "enabled": true, "reason": "string" }, "swift": { "enabled": true, "reason": "string" } }, "operatorInfo": "string", "parentId": "string", "recurringReference": "string", "routingNumber": "string", "sortCodeUK": "string", "verificationResponses": [ { "expireTime": "2019-08-24T14:15:22.123Z", "purpose": "sepaPayee", "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6", "responseState": "match", "suggestedName": "string", "timestamp": "2019-08-24T14:15:22.123Z" } ] } ], "actions": [ "string" ], "address": { "buildingName": "string", "buildingNumber": "string", "country": "string", "countrySubdivision": "string", "department": "string", "district": "string", "floor": "string", "postBox": "string", "postCode": "string", "room": "string", "streetName": "string", "subDepartment": "string", "town": "string", "townLocation": "string" }, "address1": "string", "address2": "string", "alias": "string", "city": "string", "country": "string", "county": "string", "currencies": [ "string" ], "draft": {}, "email": "string", "firstName": "string", "id": "string", "isBeneficiary": true, "isPayer": true, "isSelf": true, "lastName": "string", "linkedDocuments": { "count": 0, "uri": "string" }, "name": "string", "parent": { "alias": "string", "displayName": "string", "id": "string", "isSelf": true, "name": "string", "state": "incomplete", "vanityId": "string" }, "payable": { "enabled": true, "reason": "string" }, "paymentReason": [ "string" ], "postCode": "string", "primaryType": "string", "shortfall": 0, "shortfallCurrencyCode": "string", "state": "draft", "status": "draft", "subsidiary": "string", "subType": "string", "thirdPartyType": "string", "thirdPartyTypeOther": "string", "vanityId": "string" }

Create counterparty draft

`POST /counterparties/draft` — Create Draft Counterparty

Permissions

Query parameters

API versions

Mandatory fields by scenario

Draft save (default, `validate=false`)

Full validation (`validate=true`) or submission

Core counterparty fields

`ValidateAddress` — Counterparty Address Validation

The `address` object (`CounterpartyAddressModel`)

Mandatory-address rules by scenario

Account fields (per entry in `accounts[]`)

Additional Notes

Response

Request

Responses

Create counterparty draft

POST /counterparties/draft — Create Draft Counterparty#

Permissions#

Query parameters#

API versions#

Mandatory fields by scenario#

Draft save (default, validate=false)#

Full validation (validate=true) or submission#

Core counterparty fields#

ValidateAddress — Counterparty Address Validation#

The address object (CounterpartyAddressModel)#

Mandatory-address rules by scenario#

Account fields (per entry in accounts[])#

Additional Notes#

Response#

Request

Responses

`POST /counterparties/draft` — Create Draft Counterparty

Permissions

Query parameters

API versions

Mandatory fields by scenario

Draft save (default, `validate=false`)

Full validation (`validate=true`) or submission

Core counterparty fields

`ValidateAddress` — Counterparty Address Validation

The `address` object (`CounterpartyAddressModel`)

Mandatory-address rules by scenario

Account fields (per entry in `accounts[]`)

Additional Notes

Response