Wallet Signers

Add a signer to a customer's wallets

Adds a new signer to the customer’s wallet infrastructure. An add to a live (already-active) roster typically needs one admin approval — see Multi-signer wallets. The synchronous response returns a verificationUrl whose audience is given by urlAudience: a passkey signer gets their own enrollment link (urlAudience: "signer", also delivered via the wallet_signer.invited webhook) — deliver it to the signer. For a passkey signer added to a live roster this "signer" link is the FIRST of two steps, not full self-service: once the signer enrolls their passkey the add parks a roster-add ceremony for a customer admin’s co-stamp, and that admin link arrives ONLY on the wallet_ceremony.awaiting_admin_approval webhook (carrying the ceremony’s ceremonyId), never in this response. An api_key signer that parks for admin approval instead returns the admin co-stamp link inline (urlAudience: "admin", also delivered via the wallet_ceremony.awaiting_admin_approval webhook) — deliver it to an admin; a synchronously-admitted api_key signer returns null/null. A parked api_key add whose activity is still resolving at the custody provider ALSO returns null/null, but with awaitingProvider: true set — that flag is what distinguishes “nothing to do, fully admitted” from “nothing to do yet, still resolving” until the admin link becomes available (poll reissue-admin-approval, which mints it once the provider settles). If the admin webhook is lost, recover the admin link with POST /wallet-signers/{signerId}/reissue-admin-approval. When an api_key add parks on a roster that carries an ACTIVE api_key admin, the response ADDS machineApproval (a token + approvalMaterial) alongside that admin link and webhook: stamp the material with an ACTIVE api_key admin key and POST { method: "api_key", credential } to /v2/verifications/{token}/complete (credential is { signedBody, stamp, organizationId } as a nested JSON object; a JSON string of the same is deprecated and will be rejected in a future release) to activate the signer without opening the link — the same stamp-and-approve step every machine governance ceremony uses. Conduit never emails anyone — your platform delivers the link. Route by urlAudience, never assume the URL is the signer’s.

The same signing-mode roster rules as the claim apply to later adds: api_key signers are only valid under a programmatic signing mode, and api_key admins only under programmatic unattended — otherwise 422 SIGNING_MODE_ROSTER_INVALID. An api_key signer must include publicKey (compressed P-256: 33 bytes / 66 hex chars, 02/03 prefix); a key already on an active signer returns 409 API_KEY_PUBLIC_KEY_IN_USE. See Programmatic payout signing.

POST

customers

{customerId}

wallet-signers

Add a signer to a customer's wallets

curl --request POST \
  --url https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "signer@example.com",
  "name": "Jane Doe",
  "publicKey": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
'

import requests

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

payload = {
    "email": "signer@example.com",
    "name": "Jane Doe",
    "publicKey": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'signer@example.com',
    name: 'Jane Doe',
    publicKey: '02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
  })
};

fetch('https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers', 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/customers/{customerId}/wallet-signers",
  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([
    'email' => 'signer@example.com',
    'name' => 'Jane Doe',
    'publicKey' => '02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "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/customers/{customerId}/wallet-signers"

	payload := strings.NewReader("{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}"

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

{
  "id": "<string>",
  "email": "signer@example.com",
  "name": "Jane Doe",
  "role": "admin",
  "credentialType": "passkey",
  "passkeyCount": 0,
  "status": "pending_activation",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "verificationUrl": "https://app.conduit.financial/verify/mtQzSU2hdy0DuZ6za2IHIoVDgXzshrFtN38kMULRDFw",
  "urlAudience": "signer",
  "awaitingProvider": true,
  "machineApproval": {
    "token": "<string>",
    "approvalMaterial": {
      "activityId": "<string>",
      "fingerprint": "<string>",
      "subOrganizationId": "<string>"
    }
  }
}

{
  "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": "IDEMPOTENCY_KEY_CONFLICT",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
  "resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
  "docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
  "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": "SIGNERS_NOT_SUPPORTED",
  "title": "Signers Not Supported",
  "status": 422,
  "detail": "Signers can only be managed on non-custodial wallets. This customer's wallet is custodial, so the backend signs on its behalf.",
  "resolution": "Claim the wallet as non-custodial via POST /v2/customers/:id/wallets/claim-non-custodial before adding or removing signers.",
  "docs": "https://conduit-v2.mintlify.app/errors#signers-not-supported",
  "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

Headers

Idempotency-Key

string

required

Caller-generated unique key that lets the server safely replay this request. The original response is returned for 30 days on any retry with the same key from the same organization. Required on every state-changing money-moving or resource-creating POST.

Required string length: 1 - 128

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

Example:

"01J7B3K2X9M8N5P6Q7R8S9T0V1"

Path Parameters

customerId

string

required

Example:

"cus_1A2b3C4d5E6f7G8h9I0jKl"

Body

application/json

string<email>

required

Email address of the signer to add

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Example:

"signer@example.com"

name

string

Display name of the signer

Example:

"Jane Doe"

role

enum<string>

admin = root-quorum member + signing-quorum member; signer = signing-quorum only

Available options:

admin,

signer

credentialType

enum<string>

How this signer will stamp. api_key requires publicKey.

Available options:

passkey,

api_key

publicKey

string

Machine-signer P-256 compressed public key (33 bytes, 02/03 prefix + 64 hex chars, optional 0x prefix). Required when credentialType=api_key.

Pattern: ^(?:0x)?(?:02|03)[0-9a-fA-F]{64}$

Example:

"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

Response

string

required

Unique wallet signer identifier

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

string

required

Signer's email address

Example:

"signer@example.com"

name

string | null

required

Signer's display name

Example:

"Jane Doe"

role

enum<string>

required

admin = root-quorum member + signing-quorum member; signer = signing-quorum only

Available options:

admin,

signer

credentialType

enum<string>

required

How this signer stamps requests

Available options:

passkey,

api_key

passkeyCount

integer

required

Number of passkeys enrolled for this signer

Required range: 0 <= x <= 9007199254740991

Example:

0

status

enum<string>

required

Current signer status

Available options:

pending_activation,

activating,

active,

pending_removal,

removed,

error

createdAt

string<date-time>

required

Timestamp when the signer was created

Example:

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

updatedAt

string<date-time>

required

Timestamp when the signer was last updated

Example:

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

verificationUrl

string | null

required

Synchronous URL for this add, or null when none applies. Read urlAudience to know who it is for before delivering it — a passkey add returns the signer's enrollment link, an api_key add pending approval returns a customer admin's co-stamp link. On a live roster a "signer" link is the FIRST of two links, not full self-service: after the signer enrolls their passkey the add parks a roster-add ceremony for an admin co-stamp, whose link arrives only on the wallet_ceremony.awaiting_admin_approval webhook (carrying the ceremony's ceremonyId).

Example:

"https://app.conduit.financial/verify/mtQzSU2hdy0DuZ6za2IHIoVDgXzshrFtN38kMULRDFw"

urlAudience

enum<string> | null

required

Audience of verificationUrl: signer = the new signer's credential-enrollment link (deliver to the signer) — on a live roster this is only the first of two links, the second being an admin co-stamp delivered on the wallet_ceremony.awaiting_admin_approval webhook; admin = a customer admin's approval link (deliver to an admin; also delivered via the wallet_ceremony.awaiting_admin_approval webhook); null when there is no URL.

Available options:

signer,

admin

awaitingProvider

enum<boolean>

True only while the parked activity is still resolving at the custody provider — verificationUrl/urlAudience are null here too, but unlike a synchronously-admitted add there is a ceremonyId to track and nothing yet for any human to approve. Absent on every other outcome.

Available options:

true

machineApproval

object

Additional material for a machine (api_key) add that parks for approval on a roster carrying an ACTIVE api_key admin. It is handed back ALONGSIDE verificationUrl (urlAudience: "admin") and the wallet_ceremony.awaiting_admin_approval webhook, which are always present — approve either way. Stamp approvalMaterial with an ACTIVE api_key admin's P-256 key and POST { method: "api_key", credential } to /v2/verifications/{token}/complete (credential is { signedBody, stamp, organizationId } as a nested JSON object; a JSON string of the same is deprecated and will be rejected in a future release) to activate the signer — the same stamp-and-approve step every machine governance ceremony uses. Absent when the roster has no api_key admin to stamp.

Show child attributes

⌘I

Add a signer to a customer's wallets

curl --request POST \
  --url https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "signer@example.com",
  "name": "Jane Doe",
  "publicKey": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
'

import requests

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

payload = {
    "email": "signer@example.com",
    "name": "Jane Doe",
    "publicKey": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'signer@example.com',
    name: 'Jane Doe',
    publicKey: '02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
  })
};

fetch('https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers', 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/customers/{customerId}/wallet-signers",
  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([
    'email' => 'signer@example.com',
    'name' => 'Jane Doe',
    'publicKey' => '02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "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/customers/{customerId}/wallet-signers"

	payload := strings.NewReader("{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"signer@example.com\",\n  \"name\": \"Jane Doe\",\n  \"publicKey\": \"02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\"\n}"

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

{
  "id": "<string>",
  "email": "signer@example.com",
  "name": "Jane Doe",
  "role": "admin",
  "credentialType": "passkey",
  "passkeyCount": 0,
  "status": "pending_activation",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "verificationUrl": "https://app.conduit.financial/verify/mtQzSU2hdy0DuZ6za2IHIoVDgXzshrFtN38kMULRDFw",
  "urlAudience": "signer",
  "awaitingProvider": true,
  "machineApproval": {
    "token": "<string>",
    "approvalMaterial": {
      "activityId": "<string>",
      "fingerprint": "<string>",
      "subOrganizationId": "<string>"
    }
  }
}

{
  "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": "IDEMPOTENCY_KEY_CONFLICT",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
  "resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
  "docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
  "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": "SIGNERS_NOT_SUPPORTED",
  "title": "Signers Not Supported",
  "status": 422,
  "detail": "Signers can only be managed on non-custodial wallets. This customer's wallet is custodial, so the backend signs on its behalf.",
  "resolution": "Claim the wallet as non-custodial via POST /v2/customers/:id/wallets/claim-non-custodial before adding or removing signers.",
  "docs": "https://conduit-v2.mintlify.app/errors#signers-not-supported",
  "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

Add a signer to a customer's wallets

Authorizations

Headers

Path Parameters

Body

Response