Create an external entity
curl --request POST \
--url https://api-sandbox.circle.com/v1/externalEntities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "MA",
"city": "Boston",
"postcode": "01234",
"streetName": "Main Street",
"buildingNumber": "100"
}
}
'import requests
url = "https://api-sandbox.circle.com/v1/externalEntities"
payload = {
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "MA",
"city": "Boston",
"postcode": "01234",
"streetName": "Main Street",
"buildingNumber": "100"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
businessName: 'Circle Internet Financial Inc.',
businessUniqueIdentifier: '1234567890',
identifierIssuingCountryCode: 'US',
address: {
country: 'US',
state: 'MA',
city: 'Boston',
postcode: '01234',
streetName: 'Main Street',
buildingNumber: '100'
}
})
};
fetch('https://api-sandbox.circle.com/v1/externalEntities', 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://api-sandbox.circle.com/v1/externalEntities",
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([
'businessName' => 'Circle Internet Financial Inc.',
'businessUniqueIdentifier' => '1234567890',
'identifierIssuingCountryCode' => 'US',
'address' => [
'country' => 'US',
'state' => 'MA',
'city' => 'Boston',
'postcode' => '01234',
'streetName' => 'Main Street',
'buildingNumber' => '100'
]
]),
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://api-sandbox.circle.com/v1/externalEntities"
payload := strings.NewReader("{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api-sandbox.circle.com/v1/externalEntities")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/externalEntities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"complianceState": "PENDING",
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "CA",
"city": "San Francisco",
"streetName": "Market St",
"buildingNumber": "100",
"postcode": "94105"
}
}
}Create an external entity
Creates an external entity for the institutional account.
A new external entity is created with a complianceState of PENDING and has no walletId. Circle assigns the wallet only after compliance screening accepts the entity, so the field is omitted from the response while the entity is pending. Use GET /v1/externalEntities to retrieve the walletId once the entity is ACCEPTED.
This endpoint is idempotent on businessUniqueIdentifier and identifierIssuingCountryCode. Creating an entity that already exists returns that entity in its current state, so a repeat request for an already-accepted entity returns complianceState: ACCEPTED together with its walletId.
To access the Core API for Institutions, contact your Circle account representative.
POST
/
v1
/
externalEntities
Create an external entity
curl --request POST \
--url https://api-sandbox.circle.com/v1/externalEntities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "MA",
"city": "Boston",
"postcode": "01234",
"streetName": "Main Street",
"buildingNumber": "100"
}
}
'import requests
url = "https://api-sandbox.circle.com/v1/externalEntities"
payload = {
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "MA",
"city": "Boston",
"postcode": "01234",
"streetName": "Main Street",
"buildingNumber": "100"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
businessName: 'Circle Internet Financial Inc.',
businessUniqueIdentifier: '1234567890',
identifierIssuingCountryCode: 'US',
address: {
country: 'US',
state: 'MA',
city: 'Boston',
postcode: '01234',
streetName: 'Main Street',
buildingNumber: '100'
}
})
};
fetch('https://api-sandbox.circle.com/v1/externalEntities', 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://api-sandbox.circle.com/v1/externalEntities",
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([
'businessName' => 'Circle Internet Financial Inc.',
'businessUniqueIdentifier' => '1234567890',
'identifierIssuingCountryCode' => 'US',
'address' => [
'country' => 'US',
'state' => 'MA',
'city' => 'Boston',
'postcode' => '01234',
'streetName' => 'Main Street',
'buildingNumber' => '100'
]
]),
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://api-sandbox.circle.com/v1/externalEntities"
payload := strings.NewReader("{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api-sandbox.circle.com/v1/externalEntities")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/externalEntities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"businessName\": \"Circle Internet Financial Inc.\",\n \"businessUniqueIdentifier\": \"1234567890\",\n \"identifierIssuingCountryCode\": \"US\",\n \"address\": {\n \"country\": \"US\",\n \"state\": \"MA\",\n \"city\": \"Boston\",\n \"postcode\": \"01234\",\n \"streetName\": \"Main Street\",\n \"buildingNumber\": \"100\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"complianceState": "PENDING",
"businessName": "Circle Internet Financial Inc.",
"businessUniqueIdentifier": "1234567890",
"identifierIssuingCountryCode": "US",
"address": {
"country": "US",
"state": "CA",
"city": "San Francisco",
"streetName": "Market St",
"buildingNumber": "100",
"postcode": "94105"
}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The name of the business.
Example:
"Circle Internet Financial Inc."
The unique identifier of the business. For example, a company number or tax ID.
Example:
"1234567890"
The country code of the issuing authority. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.
Pattern:
^[A-Z]{2}$Example:
"US"
Show child attributes
Show child attributes
Response
Successfully created an external entity.
A newly created external entity. Compliance screening has not accepted it yet, so no wallet has been assigned and no walletId is returned.
- PendingExternalEntity
- AcceptedExternalEntity
Show child attributes
Show child attributes
Was this page helpful?