Update a Counterparty

curl --request PATCH \
  --url https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "businessName": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zipCode": "<string>"
  },
  "email": "<string>",
  "phone": "<string>",
  "taxId": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "metadata": {}
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "businessName": "<string>",
    "address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "zipCode": "<string>"
    },
    "email": "<string>",
    "phone": "<string>",
    "taxId": "<string>",
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    businessName: '<string>',
    address: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      country: '<string>',
      zipCode: '<string>'
    },
    email: '<string>',
    phone: '<string>',
    taxId: '<string>',
    dateOfBirth: '2023-12-25',
    nationality: '<string>',
    metadata: {}
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'businessName' => '<string>',
    'address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'country' => '<string>',
        'zipCode' => '<string>'
    ],
    'email' => '<string>',
    'phone' => '<string>',
    'taxId' => '<string>',
    'dateOfBirth' => '2023-12-25',
    'nationality' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "customer": {
    "id": "<string>"
  },
  "id": "<string>",
  "status": "active",
  "failure": {
    "code": "providerError",
    "message": "<string>",
    "retryable": true,
    "bankCode": "<string>"
  },
  "name": "<string>",
  "entityType": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "businessName": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zipCode": "<string>"
  },
  "email": "<string>",
  "phone": "<string>",
  "taxId": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "error": "InvalidMetadata",
  "code": 10133,
  "msg": "invalid metadata",
  "cause": "<string>"
}

{
  "error": "CounterpartyNotFound",
  "code": 10173,
  "msg": "counterparty not found",
  "cause": "<string>"
}

{
  "error": "VersionConflict",
  "code": 10069,
  "msg": "counterparty was modified concurrently",
  "cause": "<string>"
}

{
  "error": "AddressInvalid",
  "code": 10167,
  "msg": "address is invalid",
  "cause": "<string>"
}

PATCH

counterparties

{counterpartyId}

Update a Counterparty

curl --request PATCH \
  --url https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "businessName": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zipCode": "<string>"
  },
  "email": "<string>",
  "phone": "<string>",
  "taxId": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "metadata": {}
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "businessName": "<string>",
    "address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "zipCode": "<string>"
    },
    "email": "<string>",
    "phone": "<string>",
    "taxId": "<string>",
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    businessName: '<string>',
    address: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      country: '<string>',
      zipCode: '<string>'
    },
    email: '<string>',
    phone: '<string>',
    taxId: '<string>',
    dateOfBirth: '2023-12-25',
    nationality: '<string>',
    metadata: {}
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'businessName' => '<string>',
    'address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'country' => '<string>',
        'zipCode' => '<string>'
    ],
    'email' => '<string>',
    'phone' => '<string>',
    'taxId' => '<string>',
    'dateOfBirth' => '2023-12-25',
    'nationality' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/counterparties/{counterpartyId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zipCode\": \"<string>\"\n  },\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "customer": {
    "id": "<string>"
  },
  "id": "<string>",
  "status": "active",
  "failure": {
    "code": "providerError",
    "message": "<string>",
    "retryable": true,
    "bankCode": "<string>"
  },
  "name": "<string>",
  "entityType": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "businessName": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zipCode": "<string>"
  },
  "email": "<string>",
  "phone": "<string>",
  "taxId": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "error": "InvalidMetadata",
  "code": 10133,
  "msg": "invalid metadata",
  "cause": "<string>"
}

{
  "error": "CounterpartyNotFound",
  "code": 10173,
  "msg": "counterparty not found",
  "cause": "<string>"
}

{
  "error": "VersionConflict",
  "code": 10069,
  "msg": "counterparty was modified concurrently",
  "cause": "<string>"
}

{
  "error": "AddressInvalid",
  "code": 10167,
  "msg": "address is invalid",
  "cause": "<string>"
}

Authorizations

Authorization

string

header

required

Token from POST /auth/token

Path Parameters

counterpartyId

string

required

Counterparty ID (ctp_ prefix).

Body

application/json

Partial update — every field optional; omitted fields are unchanged. Unknown fields are rejected with 400 (strict decode) by the handler. entityType cannot be changed (create a new counterparty instead) and name cannot be written (it is server-composed). Send only the name fields matching the counterparty's existing entityType: businessName on an individual, or firstName/lastName on a business, is rejected with 422 Validation.

firstName

string

Given name. Individual counterparties only. Recomposes name.

Required string length: 1 - 140

lastName

string

Family name. Individual counterparties only. Recomposes name.

Required string length: 1 - 140

businessName

string

Registered legal name. Business counterparties only. Recomposes name.

Required string length: 1 - 140

address

object

The counterparty's postal address.

Hide child attributes

address.line1

string

Street address, line 1.

address.line2

string

Street address, line 2.

address.city

string

City.

address.state

string

State / province / region.

address.country

string

ISO 3166-1 alpha-2

address.zipCode

string

ZIP / postal code.

string

Contact email address.

phone

string

Phone in E.164 format.

taxId

string

Tax ID (CPF, CNPJ, SSN, etc.). Required for some external-account types.

dateOfBirth

string<date>

Date of birth (YYYY-MM-DD).

nationality

string

metadata

object

Free-form key-value pairs stored on the resource and echoed back on reads.

Hide child attributes

metadata.{key}

string

Response

The request has succeeded.

A third party a customer transacts with — an entry in the customer's address book. Counterparties will own External Accounts (registered payment destinations) in a later slice.

customer

object

required

The customer whose address book holds this counterparty.

Hide child attributes

customer.id

string

required

The customer id (cst_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

string

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

status

enum<string>

Lifecycle of a counterparty. rejected is set when compliance screening finds a prohibited country, on create or on a later update. A counterparty rejected only for countryProhibited returns to active when an update moves its address to an allowed country; deleted marks a soft-deleted record that remains readable by id.

Available options:

active,

rejected,

deleted

failure

object

Why the counterparty was rejected. Present only when status is rejected.

Hide child attributes

failure.code

enum<string>

required

What went wrong.

Available options:

providerError,

providerRejected,

providerTimeout,

expired,

systemError,

provisioningTimeout,

insufficientFunds,

providerAmountBelowMinimum,

limitExceeded,

outsideSellBounds,

outsideSellVelocityBounds,

unusableAmount,

unsupportedCorridor,

outgoingRailNotEnabled,

ssnNotVerified,

riskRejected,

cardDeclined,

bankSellDeclined,

payoutFailed,

priceMoved,

returningToSender,

returnedToSender,

returnFailed,

depositFailed,

attributionTimeout,

assetMismatch,

chainMismatch,

misattributedArrival,

depositAddressNotActive,

virtualAccountNotActive,

counterpartyArchived,

destinationUnavailable,

walletClaimed,

walletBoundToCustodialFlow,

projectSuspended,

memoInvalid,

cashDepositFailed,

noMatchingNetwork,

blockchainAddressInUse,

bankAccountInUse,

bankAccountRejected,

deletePendingTimeout,

providerAccountMissing,

cardInUse,

cardLimitReached,

countryProhibited,

countryNotSupported,

cardVerificationDeclined,

bankVerificationDeclined,

accountClosed,

accountFrozenByBank,

routingOrAccountNumberInvalid,

accountHolderDeceased,

accountDoesNotSupportTransfers,

payeeNameMismatch,

walletUnreachableOnNetwork,

billingAddressMismatch,

cardExpired,

cardClosedOrLostStolen,

pushToCardUnsupported,

cardDeclinedByIssuer

failure.message

string

required

A fixed, vendor-neutral sentence for code.

failure.retryable

boolean

required

Whether trying the same thing again can succeed.

failure.bankCode

string

The bank's own return code, only on an external account a bank return made invalid.

name

string

Single-line display name, read-only and server-composed: businessName for a business, or firstName + " " + lastName for an individual. It is the same string an instrument's owner.name carries. Write the structured fields; read this one.

entityType

enum<string>

Determines which structured name fields apply. Can be absent on reads for older counterparties that have not been classified yet.

Available options:

individual,

business

firstName

string

Given name — present when entityType is individual and the row has structured name fields. Echoed back exactly as supplied.

lastName

string

Family name — present when entityType is individual and the row has structured name fields. Echoed back exactly as supplied.

businessName

string

Registered legal name — present when entityType is business and the row has structured name fields. Echoed back exactly as supplied.

address

object

Registered address. Omitted when the counterparty has none, such as one created without an address on a project that does not require it.

Hide child attributes

address.line1

string

Street address, line 1.

address.line2

string

Street address, line 2.

address.city

string

City.

address.state

string

State / province / region.

address.country

string

ISO 3166-1 alpha-2

address.zipCode

string

ZIP / postal code.

string

phone

string

taxId

string

dateOfBirth

string<date>

nationality

string

ISO 3166-1 alpha-2.

metadata

object

Hide child attributes

metadata.{key}

string

createdAt

string<date-time>

updatedAt

string<date-time>

Overview

Move money

Routes

External Payment Methods

Platform

Read onchain data

Update a Counterparty

Authorizations

Path Parameters

Body

Response