Skip to main content
POST
/
external-accounts
Create an External Account
curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.10/external-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "owner": {
    "customerId": "<string>",
    "kind": "customer"
  },
  "label": "<string>",
  "metadata": {}
}
'
import requests

url = "https://sandbox-api.polygon.technology/v0.10/external-accounts"

payload = {
"owner": {
"customerId": "<string>",
"kind": "customer"
},
"label": "<string>",
"metadata": {}
}
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({
owner: {customerId: '<string>', kind: 'customer'},
label: '<string>',
metadata: {}
})
};

fetch('https://sandbox-api.polygon.technology/v0.10/external-accounts', 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.10/external-accounts",
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([
'owner' => [
'customerId' => '<string>',
'kind' => 'customer'
],
'label' => '<string>',
'metadata' => [

]
]),
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.10/external-accounts"

payload := strings.NewReader("{\n \"owner\": {\n \"customerId\": \"<string>\",\n \"kind\": \"customer\"\n },\n \"label\": \"<string>\",\n \"metadata\": {}\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.10/external-accounts")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"owner\": {\n \"customerId\": \"<string>\",\n \"kind\": \"customer\"\n },\n \"label\": \"<string>\",\n \"metadata\": {}\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.10/external-accounts")

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 \"owner\": {\n \"customerId\": \"<string>\",\n \"kind\": \"customer\"\n },\n \"label\": \"<string>\",\n \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "bankCanada": {
    "accountNumberLast4": "<string>",
    "institutionNumber": "<string>",
    "transitNumber": "<string>",
    "bankName": "<string>"
  },
  "bankIban": {
    "BIC": "<string>",
    "countryCode": "<string>",
    "ibanLast4": "<string>",
    "bankAddress": "<string>"
  },
  "bankUs": {
    "accountNumberLast4": "<string>",
    "routingNumber": "<string>",
    "bankName": "<string>"
  },
  "card": {
    "cardNumberLast4": "<string>",
    "expiryMonth": 123,
    "expiryYear": 123
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "label": "<string>",
  "metadata": {},
  "object": "externalAccount",
  "owner": {
    "customerId": "<string>",
    "kind": "customer"
  },
  "rejectionReason": "<string>",
  "resolvedTransactions": [
    "<string>"
  ],
  "updatedAt": "2023-11-07T05:31:56Z",
  "walletExternal": {
    "blockchainAddress": "<string>",
    "otherCustodian": "<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

Create an External Account. Exactly one per-type detail object must be supplied, matching type; the service validates the correct subset and rejects mismatches with 422.

owner
object
required

Customer-owned External Account.

type
enum<string>
required

External Account type. Selects which per-type detail object the request must carry.

Available options:
bankUs,
bankIban,
bankCanada,
card,
walletExternal
bankCanada
object

Required when type = bankCanada.

bankIban
object

Required when type = bankIban.

bankUs
object

Required when type = bankUs.

card
object

Required when type = card.

label
string
metadata
object
walletExternal
object

Required when type = walletExternal.

Response

201 - application/json

The request has succeeded and a new resource has been created as a result.

A saved payment destination registered for a customer or one of their counterparties. Exactly one of the per-type response detail objects is populated, selected by type. Write-only secrets (full account number, full IBAN) are never present on reads - only their last-4 renderings.

bankCanada
object

Populated when type = bankCanada.

bankIban
object

Populated when type = bankIban.

bankUs
object

Populated when type = bankUs.

card
object

Populated when type = card.

category
enum<string>

Coarse classification derived from type, stored for query convenience.

Available options:
fiatAccount,
crypto
createdAt
string<date-time>
failureReason
enum<string>

Set when status = failed.

Available options:
ereborRejected,
cardProviderRejected,
providerAccountMissing,
cardLimitReached,
cardInUse,
provisioningTimeout,
systemError
id
string
label
string
metadata
object
object
enum<string>
Available options:
externalAccount
owner
object

Customer-owned External Account.

rejectionReason
string

Set when status = rejected (compliance screening).

resolvedTransactions
string[]

Transaction ids that this registration submitted for sender-attribution release. Returned ONLY on the POST create response, and only when registering this walletExternal matched held inbounds. Attribution is async: each entry is submitted to the provider from awaitingAction.awaitingSenderAttribution and moves to processing.fundsPulled once settlement confirms, so an immediate GET of an id may still show awaitingAction. Omitted on GETs (the create path is the only writer).

status
enum<string>

Lifecycle of an External Account. pending → active on successful provisioning; pending → failed on upstream rejection or provisioning timeout. rejected (create-time country screening) and invalid (derived from payout returns) are reserved enum values with no transition logic in this slice. deleted is the soft-delete terminal.

Available options:
active,
pending,
rejected,
invalid,
deleted,
failed
type
enum<string>

External Account type. Selects which per-type detail object the request must carry.

Available options:
bankUs,
bankIban,
bankCanada,
card,
walletExternal
updatedAt
string<date-time>
walletExternal
object

Populated when type = walletExternal.