Create a Counterparty

curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/counterparties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "entityType": "individual",
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "firstName": "Alice",
  "lastName": "Smith",
  "address": {
    "line1": "500 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zipCode": "94105"
  },
  "email": "alice@example.com",
  "phone": "+14155550100",
  "nationality": "US"
}
'

import requests

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

payload = {
    "entityType": "individual",
    "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
    "firstName": "Alice",
    "lastName": "Smith",
    "address": {
        "line1": "500 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "zipCode": "94105"
    },
    "email": "alice@example.com",
    "phone": "+14155550100",
    "nationality": "US"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entityType: 'individual',
    customerId: 'cst_vfa0nxw6zvyws9g237jrxn4y7k',
    firstName: 'Alice',
    lastName: 'Smith',
    address: {
      line1: '500 Market Street',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      zipCode: '94105'
    },
    email: 'alice@example.com',
    phone: '+14155550100',
    nationality: 'US'
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/counterparties', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => 'individual',
    'customerId' => 'cst_vfa0nxw6zvyws9g237jrxn4y7k',
    'firstName' => 'Alice',
    'lastName' => 'Smith',
    'address' => [
        'line1' => '500 Market Street',
        'city' => 'San Francisco',
        'state' => 'CA',
        'country' => 'US',
        'zipCode' => '94105'
    ],
    'email' => 'alice@example.com',
    'phone' => '+14155550100',
    'nationality' => 'US'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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"

	payload := strings.NewReader("{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://sandbox-api.polygon.technology/v0.13/counterparties")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\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": "AccountHolderUnsupported",
  "code": 10022,
  "msg": "destination.details.accountHolder must be customer",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "ServiceUnavailable",
  "code": 5003,
  "msg": "service unavailable",
  "cause": "<string>"
}

POST

counterparties

Create a Counterparty

curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/counterparties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "entityType": "individual",
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "firstName": "Alice",
  "lastName": "Smith",
  "address": {
    "line1": "500 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zipCode": "94105"
  },
  "email": "alice@example.com",
  "phone": "+14155550100",
  "nationality": "US"
}
'

import requests

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

payload = {
    "entityType": "individual",
    "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
    "firstName": "Alice",
    "lastName": "Smith",
    "address": {
        "line1": "500 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "zipCode": "94105"
    },
    "email": "alice@example.com",
    "phone": "+14155550100",
    "nationality": "US"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entityType: 'individual',
    customerId: 'cst_vfa0nxw6zvyws9g237jrxn4y7k',
    firstName: 'Alice',
    lastName: 'Smith',
    address: {
      line1: '500 Market Street',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      zipCode: '94105'
    },
    email: 'alice@example.com',
    phone: '+14155550100',
    nationality: 'US'
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/counterparties', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => 'individual',
    'customerId' => 'cst_vfa0nxw6zvyws9g237jrxn4y7k',
    'firstName' => 'Alice',
    'lastName' => 'Smith',
    'address' => [
        'line1' => '500 Market Street',
        'city' => 'San Francisco',
        'state' => 'CA',
        'country' => 'US',
        'zipCode' => '94105'
    ],
    'email' => 'alice@example.com',
    'phone' => '+14155550100',
    'nationality' => 'US'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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"

	payload := strings.NewReader("{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://sandbox-api.polygon.technology/v0.13/counterparties")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"individual\",\n  \"customerId\": \"cst_vfa0nxw6zvyws9g237jrxn4y7k\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Smith\",\n  \"address\": {\n    \"line1\": \"500 Market Street\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"country\": \"US\",\n    \"zipCode\": \"94105\"\n  },\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+14155550100\",\n  \"nationality\": \"US\"\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": "AccountHolderUnsupported",
  "code": 10022,
  "msg": "destination.details.accountHolder must be customer",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "ServiceUnavailable",
  "code": 5003,
  "msg": "service unavailable",
  "cause": "<string>"
}

Authorizations

Authorization

string

header

required

Token from POST /auth/token

Headers

Idempotency-Key

string

required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Body

application/json

individual
business

Individual counterparty create arm. The server composes the response name as firstName + " " + lastName.

entityType

enum<string>

required

Entity type discriminator.

Available options:

individual

firstName

string

required

Given name, as it appears on the counterparty's identity document. 1..140 chars.

Required string length: 1 - 140

lastName

string

required

Family name, as it appears on the counterparty's identity document. 1..140 chars.

Required string length: 1 - 140

customerId

string

required

Owning customer ID (cst_ prefix).

dateOfBirth

string<date>

Date of birth (YYYY-MM-DD).

address

object

Registered address. Required unless your project is configured not to require one. When supplied, it is validated in full: non-blank line1, city, zipCode and a two-letter ISO country (state required for US).

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.

nationality

string

ISO 3166-1 alpha-2.

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 and a new resource has been created as a result.

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

Create a Counterparty

Authorizations

Headers

Body

Response