Create an account

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "description": "My account",
  "type": "first_party",
  "purpose": "custody",
  "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/accounts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "description": "My account",
    "type": "first_party",
    "purpose": "custody",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    description: 'My account',
    type: 'first_party',
    purpose: 'custody',
    clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  })
};

fetch('https://api-sandbox.circle.com/v1/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://api-sandbox.circle.com/v1/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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'description' => 'My account',
    'type' => 'first_party',
    'purpose' => 'custody',
    'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  ]),
  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/accounts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\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/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/accounts")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}"

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

{
  "data": {
    "accountId": "1000662322",
    "entityId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
    "type": "first_party",
    "purpose": "custody",
    "status": "active",
    "description": "My account",
    "balances": [
      {
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "businessPii": {
      "businessName": "Acme Corporation",
      "businessUniqueIdentifier": "12-3456789",
      "identifierIssuingCountryCode": "US",
      "address": {
        "line1": "100 Pine Street",
        "city": "San Francisco",
        "postalCode": "94111",
        "country": "US",
        "line2": "Suite 2500",
        "district": "CA"
      }
    },
    "groupId": "9c0f1c0d-6c61-4f3d-9b8a-1a3a4b3c5d6e"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 409,
  "message": "Conflict."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

Create an account

Creates a new account. This account can be used to create accounts for Mint, or intermediary accounts for a Managed Payments customer. For Managed Payments, the account created represents the end customer that will settle stablecoin payments by the customer. That end customer can be either a business or an individual (retail) end customer.

Routing for this endpoint is body based. Requests that include businessPii, individualPii, or endCustomerType are routed to the Managed Payments intermediary account creation flow, while requests that include none of those fields are routed to the standard account creation flow.

For Managed Payments, endCustomerType selects which PII block is required:

business, or omitted, requires businessPii and rejects individualPii.
individual requires individualPii and rejects businessPii.

Both flows require an explicit type and purpose in the request body:

Standard (digital asset / Mint) accounts use purpose custody and type first_party or third_party. When clientEntityId is omitted the account is owned by the caller and type must be first_party; when clientEntityId is provided the account is owned by a sub-entity and type must be third_party.
Managed Payments intermediary accounts use type first_party and purpose payments.

POST

accounts

Create an account

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "description": "My account",
  "type": "first_party",
  "purpose": "custody",
  "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/accounts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "description": "My account",
    "type": "first_party",
    "purpose": "custody",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    description: 'My account',
    type: 'first_party',
    purpose: 'custody',
    clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  })
};

fetch('https://api-sandbox.circle.com/v1/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://api-sandbox.circle.com/v1/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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'description' => 'My account',
    'type' => 'first_party',
    'purpose' => 'custody',
    'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  ]),
  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/accounts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\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/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/accounts")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}"

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

{
  "data": {
    "accountId": "1000662322",
    "entityId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
    "type": "first_party",
    "purpose": "custody",
    "status": "active",
    "description": "My account",
    "balances": [
      {
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "businessPii": {
      "businessName": "Acme Corporation",
      "businessUniqueIdentifier": "12-3456789",
      "identifierIssuingCountryCode": "US",
      "address": {
        "line1": "100 Pine Street",
        "city": "San Francisco",
        "postalCode": "94111",
        "country": "US",
        "line2": "Suite 2500",
        "district": "CA"
      }
    },
    "groupId": "9c0f1c0d-6c61-4f3d-9b8a-1a3a4b3c5d6e"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 409,
  "message": "Conflict."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Mint Account
Managed Payments Intermediary Account (Business)
Managed Payments Intermediary Account (Individual)

Create a Mint account

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

description

string

required

Human-readable description of the account.

Example:

"My account"

type

enum<string>

required

External account type.

first_party: the calling entity itself owns the account.
third_party: a sub-entity or end user owns the account.

Available options:

first_party,

third_party

Example:

"first_party"

purpose

enum<string>

required

Intended use of the account. Digital asset (Mint) accounts always hold stablecoin balances for the owning entity, so the only supported value is custody.

Available options:

custody

Example:

"custody"

clientEntityId

string<uuid>

Optional identifier of the client entity whose account should be created. If omitted, the account is owned by the caller and type must be first_party. If provided, the account is owned by a sub-entity and type must be third_party.

Example:

"a3f1b2c4-d5e6-7890-abcd-ef1234567890"

Response

Successfully created an account.

data

object

An account returned by the create account endpoint.

Show child attributes