POST
/counterparty/{userId}/counterparties/{counterpartyId}/required-fieldsGet Required Fields for Instruments
Returns the dynamic field schema required to create a payment instrument for a counterparty. Accepts CounterpartyType for counterparty fields, or Currency + TransferType for instrument fields. Call this before creating an instrument.
Path variables
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
userId | string | Required | — | Unique user ID. |
counterpartyId | string | Required | — | Unique counterparty ID. |
Headers
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
session-token | string | Required | — | SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header. |
Request body
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
CounterpartyType | string | Required | Individual | Business | Counterparty type for counterparty field lookup. |
Currency | string | Required | USD | GBP | EUR | SGD | AED | ARS | BRL | CAD | JPY | MXN | HKD | ZAR | USDC | PYUSD | Currency for instrument fields lookup. |
TransferType | string | Required | ACH | WIRE | INTERNATIONAL_WIRE | STABLECOIN_WITHDRAW | CROSS_BORDER_AED_DOMESTIC | CROSS_BORDER_AED_WIRE | CROSS_BORDER_ARS_DOMESTIC | CROSS_BORDER_BRL_DOMESTIC | CROSS_BORDER_CAD_DOMESTIC | CROSS_BORDER_CAD_WIRE | CROSS_BORDER_SEPA | CROSS_BORDER_EUR_WIRE | CROSS_BORDER_FASTER_PAYMENTS | CROSS_BORDER_GBP_WIRE | CROSS_BORDER_HKD_DOMESTIC | CROSS_BORDER_HKD_WIREY | CROSS_BORDER_JPY_DOMESTIC | CROSS_BORDER_JPY_WIRE | CROSS_BORDER_CLABE | CROSS_BORDER_MXN_WIRE | CROSS_BORDER_SGD_DOMESTIC | CROSS_BORDER_SGD_WIRE | CROSS_BORDER_ZAR_DOMESTIC | CROSS_BORDER_ZAR_WIRE | Transfer type to get instrument-specific required fields. |
Example request
{
"CounterpartyType": "Business",
"Currency": "USD",
"TransferType": "ACH"
}Response
| Field | Type | Possible values | Description |
|---|---|---|---|
ResponseCode | integer | 200 | 201 | 204 | 301 | 400 | 401 | 403 | 404 | 410 | 422 | 500 | 503 | API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized). |
ResponseMessage | string | Success | Created | NoContent | BadRequest | Unauthorized | Forbidden | NotFound | Gone | UnprocessableContent | ServerError | ResourceMoved | ServiceUnAvailable | UnProcessableEntity | Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome. |
ResponseData | object | Please refer to below example for response body | Dynamic field definitions required for creating the counterparty or instrument. |
Example response
{
"ResponseCode": 200,
"ResponseMessage": "Success",
"ResponseData": {
"Fields": [
{
"Name": "Nickname",
"Required": true,
"Type": "Text",
"DisplayName": "Nickname"
},
{
"Name": "AccountType",
"DisplayName": "Account Type",
"Required": true,
"Type": "SingleSelection",
"PossibleValues": [
{
"label": "Saving",
"value": "Saving"
},
{
"label": "Checking",
"value": "Checking"
}
]
},
{
"Name": "AccountNumber",
"DisplayName": "Account Number",
"Required": true,
"Type": "Text"
},
{
"Name": "RoutingNumber",
"DisplayName": "Routing Number",
"Required": true,
"Type": "Text"
},
{
"Name": "BankName",
"DisplayName": "Bank Name",
"Required": true,
"Type": "Text"
},
{
"Name": "BankAddress",
"DisplayName": "Bank Address",
"Required": true,
"Type": "Text"
},
{
"Name": "BankCity",
"DisplayName": "Bank City",
"Required": true,
"Type": "Text"
},
{
"Name": "BankState",
"DisplayName": "Bank State",
"Required": true,
"Type": "Text"
},
{
"Name": "BankPostalCode",
"DisplayName": "Bank Postal Code",
"Required": true,
"Type": "Text"
},
{
"Name": "BankCountry",
"DisplayName": "Bank Country",
"Required": true,
"Type": "SingleSelection",
"PossibleValues": [
{
"label": "Albania",
"value": "AL"
},
{
"label": "Algeria",
"value": "DZ"
},
{
"label": "Andorra",
"value": "AD"
},
{
"label": "Angola",
"value": "AO"
},
{
"label": "Antigua and Barbuda",
"value": "AG"
},
{
"label": "Argentina",
"value": "AR"
},
{
"label": "Armenia",
"value": "AM"
},
{
"label": "Australia",
"value": "AU"
},
{
"label": "Austria",
"value": "AT"
},
{
"label": "Azerbaijan",
"value": "AZ"
},
{
"label": "Bahamas",
"value": "BS"
},
{
"label": "Bahrain",
"value": "BH"
},
{
"label": "Bangladesh",
"value": "BD"
},
{
"label": "Barbados",
"value": "BB"
},
{
"label": "Belgium",
"value": "BE"
},
{
"label": "Belize",
"value": "BZ"
},
{
"label": "Benin",
"value": "BJ"
},
{
"label": "Bhutan",
"value": "BT"
},
{
"label": "Bolivia",
"value": "BO"
},
{
"label": "Botswana",
"value": "BW"
},
{
"label": "Brazil",
"value": "BR"
},
{
"label": "Brunei Darussalam",
"value": "BN"
},
{
"label": "Bulgaria",
"value": "BG"
},
{
"label": "Burkina Faso",
"value": "BF"
},
{
"label": "Burundi",
"value": "BI"
},
{
"label": "Cabo Verde",
"value": "CV"
},
{
"label": "Cambodia",
"value": "KH"
},
{
"label": "Cameroon",
"value": "CM"
},
{
"label": "Canada",
"value": "CA"
},
{
"label": "Chad",
"value": "TD"
},
{
"label": "Chile",
"value": "CL"
},
{
"label": "China",
"value": "CN"
},
{
"label": "Colombia",
"value": "CO"
},
{
"label": "Comoros",
"value": "KM"
},
{
"label": "Costa Rica",
"value": "CR"
},
{
"label": "Cyprus",
"value": "CY"
},
{
"label": "Czech Republic",
"value": "CZ"
},
{
"label": "Denmark",
"value": "DK"
},
{
"label": "Djibouti",
"value": "DJ"
},
{
"label": "Dominica",
"value": "DM"
},
{
"label": "Dominican Republic",
"value": "DO"
},
{
"label": "Ecuador",
"value": "EC"
},
{
"label": "Egypt",
"value": "EG"
},
{
"label": "El Salvador",
"value": "SV"
},
{
"label": "Equatorial Guinea",
"value": "GQ"
},
{
"label": "Eritrea",
"value": "ER"
},
{
"label": "Estonia",
"value": "EE"
},
{
"label": "Fiji",
"value": "FJ"
},
{
"label": "Finland",
"value": "FI"
},
{
"label": "France",
"value": "FR"
},
{
"label": "Gabon",
"value": "GA"
},
{
"label": "Gambia",
"value": "GM"
},
{
"label": "Georgia",
"value": "GE"
},
{
"label": "Germany",
"value": "DE"
},
{
"label": "Ghana",
"value": "GH"
},
{
"label": "Greece",
"value": "GR"
},
{
"label": "Grenada",
"value": "GD"
},
{
"label": "Guatemala",
"value": "GT"
},
{
"label": "Guinea",
"value": "GN"
},
{
"label": "Guinea-Bissau",
"value": "GW"
},
{
"label": "Guyana",
"value": "GY"
},
{
"label": "Haiti",
"value": "HT"
},
{
"label": "Honduras",
"value": "HN"
},
{
"label": "Hungary",
"value": "HU"
},
{
"label": "Iceland",
"value": "IS"
},
{
"label": "India",
"value": "IN"
},
{
"label": "Indonesia",
"value": "ID"
},
{
"label": "Ireland",
"value": "IE"
},
{
"label": "Israel",
"value": "IL"
},
{
"label": "Italy",
"value": "IT"
},
{
"label": "Jamaica",
"value": "JM"
},
{
"label": "Japan",
"value": "JP"
},
{
"label": "Jordan",
"value": "JO"
},
{
"label": "Kazakhstan",
"value": "KZ"
},
{
"label": "Kenya",
"value": "KE"
},
{
"label": "Kiribati",
"value": "KI"
},
{
"label": "Kuwait",
"value": "KW"
},
{
"label": "Kyrgyzstan",
"value": "KG"
},
{
"label": "Laos",
"value": "LA"
},
{
"label": "Latvia",
"value": "LV"
},
{
"label": "Lesotho",
"value": "LS"
},
{
"label": "Liberia",
"value": "LR"
},
{
"label": "Liechtenstein",
"value": "LI"
},
{
"label": "Lithuania",
"value": "LT"
},
{
"label": "Luxembourg",
"value": "LU"
},
{
"label": "Madagascar",
"value": "MG"
},
{
"label": "Malawi",
"value": "MW"
},
{
"label": "Malaysia",
"value": "MY"
},
{
"label": "Maldives",
"value": "MV"
},
{
"label": "Malta",
"value": "MT"
},
{
"label": "Marshall Islands",
"value": "MH"
},
{
"label": "Mauritania",
"value": "MR"
},
{
"label": "Mauritius",
"value": "MU"
},
{
"label": "Mexico",
"value": "MX"
},
{
"label": "Micronesia",
"value": "FM"
},
{
"label": "Moldova",
"value": "MD"
},
{
"label": "Monaco",
"value": "MC"
},
{
"label": "Mongolia",
"value": "MN"
},
{
"label": "Morocco",
"value": "MA"
},
{
"label": "Mozambique",
"value": "MZ"
},
{
"label": "Namibia",
"value": "NA"
},
{
"label": "Nauru",
"value": "NR"
},
{
"label": "Nepal",
"value": "NP"
},
{
"label": "Netherlands",
"value": "NL"
},
{
"label": "New Zealand",
"value": "NZ"
},
{
"label": "Niger",
"value": "NE"
},
{
"label": "Nigeria",
"value": "NG"
},
{
"label": "Norway",
"value": "NO"
},
{
"label": "Oman",
"value": "OM"
},
{
"label": "Pakistan",
"value": "PK"
},
{
"label": "Palau",
"value": "PW"
},
{
"label": "Palestine",
"value": "PS"
},
{
"label": "Panama",
"value": "PA"
},
{
"label": "Papua New Guinea",
"value": "PG"
},
{
"label": "Paraguay",
"value": "PY"
},
{
"label": "Peru",
"value": "PE"
},
{
"label": "Philippines",
"value": "PH"
},
{
"label": "Poland",
"value": "PL"
},
{
"label": "Portugal",
"value": "PT"
},
{
"label": "Qatar",
"value": "QA"
},
{
"label": "Romania",
"value": "RO"
},
{
"label": "Rwanda",
"value": "RW"
},
{
"label": "Saint Kitts and Nevis",
"value": "KN"
},
{
"label": "Saint Lucia",
"value": "LC"
},
{
"label": "Saint Vincent and the Grenadines",
"value": "VC"
},
{
"label": "Samoa",
"value": "WS"
},
{
"label": "San Marino",
"value": "SM"
},
{
"label": "Sao Tome and Principe",
"value": "ST"
},
{
"label": "Saudi Arabia",
"value": "SA"
},
{
"label": "Senegal",
"value": "SN"
},
{
"label": "Seychelles",
"value": "SC"
},
{
"label": "Sierra Leone",
"value": "SL"
},
{
"label": "Singapore",
"value": "SG"
},
{
"label": "Slovakia",
"value": "SK"
},
{
"label": "Solomon Islands",
"value": "SB"
},
{
"label": "South Africa",
"value": "ZA"
},
{
"label": "South Korea",
"value": "KR"
},
{
"label": "Spain",
"value": "ES"
},
{
"label": "Sri Lanka",
"value": "LK"
},
{
"label": "Suriname",
"value": "SR"
},
{
"label": "Sweden",
"value": "SE"
},
{
"label": "Switzerland",
"value": "CH"
},
{
"label": "Tajikistan",
"value": "TJ"
},
{
"label": "Tanzania",
"value": "TZ"
},
{
"label": "Thailand",
"value": "TH"
},
{
"label": "Timor-Leste",
"value": "TL"
},
{
"label": "Togo",
"value": "TG"
},
{
"label": "Tonga",
"value": "TO"
},
{
"label": "Trinidad and Tobago",
"value": "TT"
},
{
"label": "Tunisia",
"value": "TN"
},
{
"label": "Turkey",
"value": "TR"
},
{
"label": "Turkmenistan",
"value": "TM"
},
{
"label": "Tuvalu",
"value": "TV"
},
{
"label": "Uganda",
"value": "UG"
},
{
"label": "United Arab Emirates",
"value": "AE"
},
{
"label": "United Kingdom",
"value": "GB"
},
{
"label": "United States of America",
"value": "US"
},
{
"label": "Uruguay",
"value": "UY"
},
{
"label": "Uzbekistan",
"value": "UZ"
},
{
"label": "Vanuatu",
"value": "VU"
},
{
"label": "Vietnam",
"value": "VN"
},
{
"label": "Zambia",
"value": "ZM"
},
{
"label": "Bermuda",
"value": "BM"
},
{
"label": "Cayman Islands",
"value": "KY"
},
{
"label": "Gibraltar",
"value": "GI"
},
{
"label": "Hong Kong",
"value": "HK"
},
{
"label": "Taiwan",
"value": "TW"
},
{
"label": "Virgin Islands (British)",
"value": "VG"
},
{
"label": "Virgin Islands (U.S.)",
"value": "VI"
},
{
"label": "Isle Of Man",
"value": "IM"
},
{
"label": "Cook Islands",
"value": "CK"
}
]
},
{
"Name": "BankPhone",
"DisplayName": "Bank Phone",
"Required": false,
"Type": "Text"
}
]
}
}Pass either CounterpartyType for counterparty fields, or Currency + TransferType for instrument-specific fields.
Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.