Sandbox

Mark a sandbox customer as a house account

Sandbox-only. Marks (or unmarks) one of your business customers as a house account — the only source a purpose: prefunding payout accepts. Every sandbox organization is seeded with one house account already; use this to prefund from a customer you onboarded yourself. More than one customer can carry the marker. The marker alone is not enough to send from: the customer also needs its own active wallet on the destination chain, or its own USD account, or the payout is refused. On live, only Conduit can set it, so treat the marker itself as sandbox setup rather than something your integration writes. Returns the customer at its new state.

PATCH

sandbox

customers

{customerId}

house-account

Mark a sandbox customer as a house account

curl --request PATCH \
  --url https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "isHouseAccount": true
}
'

import requests

url = "https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account"

payload = { "isHouseAccount": True }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({isHouseAccount: true})
};

fetch('https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account', 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.conduit.financial/v2/sandbox/customers/{customerId}/house-account",
  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([
    'isHouseAccount' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-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://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account"

	payload := strings.NewReader("{\n  \"isHouseAccount\": true\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"isHouseAccount\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account")

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

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"isHouseAccount\": true\n}"

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

{
  "id": "<string>",
  "applicationId": "<string>",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "features": [
    {
      "feature": "virtual_account",
      "isActive": true
    }
  ],
  "isHouseAccount": false,
  "type": "business",
  "legalName": "Acme Payments Inc.",
  "taxId": "12-3456789",
  "registeredAddress": {
    "addressLine1": "100 Market St",
    "city": "San Francisco",
    "country": "US",
    "addressLine2": "Suite 400",
    "state": "CA",
    "postalCode": "94105"
  },
  "dateOfIncorporation": "2020-03-15",
  "legalStructure": "Sociedade Limitada",
  "contactEmail": "compliance@acmepay.com",
  "clientReferenceId": "client-cus-001",
  "tradeName": "Acme Pay",
  "registrationNumber": "12345678",
  "website": "https://acmepay.com",
  "coreIndustry": "Financial Technology",
  "primaryIndustry": "fintech_companies",
  "regulatedOrRestrictedActivities": [
    "<string>"
  ],
  "contactPhone": "+14155551234"
}

{
  "type": "INVALID_OID_FORMAT",
  "title": "Invalid Object ID Format",
  "status": 400,
  "detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
  "resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
  "docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_MISSING",
  "title": "API Key Missing",
  "status": 401,
  "detail": "The request did not include an API key. All API requests must be authenticated.",
  "resolution": "Include your API key in the 'x-api-key' header with every request.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_READ_ONLY",
  "title": "API Key Is Read-Only",
  "status": 403,
  "detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
  "resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "CUSTOMER_NOT_FOUND",
  "title": "Customer Not Found",
  "status": 404,
  "detail": "No customer exists with the specified ID, or the customer belongs to a different organization.",
  "resolution": "Verify the customer ID is correct. Use the list customers endpoint to find valid customer IDs for your organization.",
  "docs": "https://conduit-v2.mintlify.app/errors#customer-not-found",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "HOUSE_ACCOUNT_BUSINESS_ONLY",
  "title": "House Account Business Only",
  "status": 409,
  "detail": "Only business customers can be marked as a house account. This customer is an individual.",
  "resolution": "House-account marking applies only to business customers; individual customers are not eligible.",
  "docs": "https://conduit-v2.mintlify.app/errors#house-account-business-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "UNSUPPORTED_MEDIA_TYPE",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
  "resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
  "docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "RATE_LIMITED",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
  "resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
  "docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z",
  "retryAfterSeconds": 3
}

{
  "type": "INTERNAL_ERROR",
  "title": "Internal Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
  "docs": "https://conduit-v2.mintlify.app/errors#internal-error",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Authorizations

x-api-key

string

header

required

Path Parameters

customerId

string

required

Body

application/json

isHouseAccount

boolean

required

Whether this customer is the organization's own house account — the only kind of account a prefunding payout can be sent from.

Example:

true

Response

The customer at its new house-account state

string

required

Unique customer identifier

Pattern: ^cus_[0-9A-Za-z]{22}$

applicationId

string

required

ID of the onboarding application that created this customer.

Pattern: ^app_[0-9A-Za-z]{22}$

createdAt

string<date-time>

required

Timestamp when the customer was created

Example:

"2026-01-15T09:30:00.000Z"

updatedAt

string<date-time>

required

Timestamp when the customer was last modified

Example:

"2026-01-15T09:30:00.000Z"

features

object[]

required

List of features enabled for this customer

Show child attributes

isHouseAccount

boolean

required

Whether this customer is the organization's own house account rather than an external customer. Read-only on live; on sandbox, set it with PATCH /v2/sandbox/customers/{customerId}/house-account.

Example:

false

type

enum<string>

required

Available options:

business

legalName

string

required

Registered legal name of the business

Example:

"Acme Payments Inc."

taxId

string

required

Government-issued tax identifier (e.g. EIN for US businesses).

Example:

"12-3456789"

registeredAddress

object

required

Registered office address. Same nested shape the onboarding request submits, so it round-trips field-for-field.

Show child attributes

dateOfIncorporation

string<date>

required

Date the business was incorporated (YYYY-MM-DD)

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$

Example:

"2020-03-15"

legalStructure

string

required

Legal structure of the business — the local jurisdiction name the customer declared at onboarding (e.g. 'Sociedade Limitada', 'GmbH', 'C-Corporation'). Free-form string; the available options are jurisdiction-specific and surfaced by the requirements discovery endpoint.

Example:

"Sociedade Limitada"

contactEmail

string

required

Primary business contact email

Example:

"compliance@acmepay.com"

clientReferenceId

string

Client-provided external identifier for cross-referencing. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces.

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Example:

"client-cus-001"

tradeName

string

Doing-business-as name. Omitted if same as legal name.

Example:

"Acme Pay"

registrationNumber

string

Business registration or incorporation number

Example:

"12345678"

website

string

Business website URL

Example:

"https://acmepay.com"

coreIndustry

enum<string>

Primary industry classification of the business

Available options:

Agriculture,

Mining,

Manufacturing,

Retail/Wholesale,

Healthcare,

Real Estate,

Transport/Logistics,

Energy,

Education,

Financial Technology,

Professional Services,

Hospitality,

Construction,

Telecommunications,

Other

Example:

"Financial Technology"

primaryIndustry

string

Attested primary industry. The accepted values change over time, so read the current set from GET /v2/onboarding/policy-subjects?axis=industry.

Example:

"fintech_companies"

regulatedOrRestrictedActivities

string[]

Attested regulated or restricted activities. The accepted values change over time, so read the current set from GET /v2/onboarding/policy-subjects?axis=regulated_activity.

contactPhone

string

Primary business contact phone number

Example:

"+14155551234"

⌘I

Mark a sandbox customer as a house account

curl --request PATCH \
  --url https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "isHouseAccount": true
}
'

import requests

url = "https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account"

payload = { "isHouseAccount": True }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({isHouseAccount: true})
};

fetch('https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account', 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.conduit.financial/v2/sandbox/customers/{customerId}/house-account",
  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([
    'isHouseAccount' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-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://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account"

	payload := strings.NewReader("{\n  \"isHouseAccount\": true\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"isHouseAccount\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/house-account")

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

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"isHouseAccount\": true\n}"

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

{
  "id": "<string>",
  "applicationId": "<string>",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "features": [
    {
      "feature": "virtual_account",
      "isActive": true
    }
  ],
  "isHouseAccount": false,
  "type": "business",
  "legalName": "Acme Payments Inc.",
  "taxId": "12-3456789",
  "registeredAddress": {
    "addressLine1": "100 Market St",
    "city": "San Francisco",
    "country": "US",
    "addressLine2": "Suite 400",
    "state": "CA",
    "postalCode": "94105"
  },
  "dateOfIncorporation": "2020-03-15",
  "legalStructure": "Sociedade Limitada",
  "contactEmail": "compliance@acmepay.com",
  "clientReferenceId": "client-cus-001",
  "tradeName": "Acme Pay",
  "registrationNumber": "12345678",
  "website": "https://acmepay.com",
  "coreIndustry": "Financial Technology",
  "primaryIndustry": "fintech_companies",
  "regulatedOrRestrictedActivities": [
    "<string>"
  ],
  "contactPhone": "+14155551234"
}

{
  "type": "INVALID_OID_FORMAT",
  "title": "Invalid Object ID Format",
  "status": 400,
  "detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
  "resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
  "docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_MISSING",
  "title": "API Key Missing",
  "status": 401,
  "detail": "The request did not include an API key. All API requests must be authenticated.",
  "resolution": "Include your API key in the 'x-api-key' header with every request.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_READ_ONLY",
  "title": "API Key Is Read-Only",
  "status": 403,
  "detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
  "resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "CUSTOMER_NOT_FOUND",
  "title": "Customer Not Found",
  "status": 404,
  "detail": "No customer exists with the specified ID, or the customer belongs to a different organization.",
  "resolution": "Verify the customer ID is correct. Use the list customers endpoint to find valid customer IDs for your organization.",
  "docs": "https://conduit-v2.mintlify.app/errors#customer-not-found",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "HOUSE_ACCOUNT_BUSINESS_ONLY",
  "title": "House Account Business Only",
  "status": 409,
  "detail": "Only business customers can be marked as a house account. This customer is an individual.",
  "resolution": "House-account marking applies only to business customers; individual customers are not eligible.",
  "docs": "https://conduit-v2.mintlify.app/errors#house-account-business-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "UNSUPPORTED_MEDIA_TYPE",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
  "resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
  "docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "RATE_LIMITED",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
  "resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
  "docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z",
  "retryAfterSeconds": 3
}

{
  "type": "INTERNAL_ERROR",
  "title": "Internal Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
  "docs": "https://conduit-v2.mintlify.app/errors#internal-error",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Overview

Errors

Customers

Registered Addresses

Wallets

Wallet Signers

Signing Quorum

Virtual Accounts

Applications

Documents

Verifications

Signing Requests

Transactions

Payouts

RFIs

Whitelist Recipients

Orders

Quotes

Webhook Endpoints

Webhook Deliveries

Webhook Event Types

Features

Customer Onboarding

Markup

Sandbox

Mark a sandbox customer as a house account

Authorizations

Path Parameters

Body

Response