Create a Blockchain Contact

REST request body

{
  "name": "Operations Wallet",
  "subOrgId": "sub_org_123",
  "address": "0xAbC123...",
  "blockChain": "ETHEREUM",
  "tags": ["vendor", "priority"],
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "contactGroupIds": ["contact_group_123"]
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/contacts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Operations Wallet",
    "subOrgId": "sub_org_123",
    "address": "0xAbC123...",
    "blockChain": "ETHEREUM",
    "tags": ["vendor", "priority"],
    "externalId": "vendor-1001",
    "assetList": ["USDC", "ETH"],
    "contactGroupIds": ["contact_group_123"]
  }'

interface CreateContactRequest {
  name: string;
  subOrgId?: string;
  address: string;
  chain: string;
  tags?: string[];
  externalId?: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

createContact(request: CreateContactRequest): Promise<Contact>

Response example

{
  "id": "contact_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "name": "Operations Wallet",
  "blockChain": "ETHEREUM",
  "address": "0xAbC123...",
  "status": "PENDING",
  "tags": ["vendor", "priority"],
  "createdById": "api_user_123",
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false
}

interface Contact {
  id: string;
  orgId: string;
  subOrgId?: string;
  name: string;
  blockChain: string;
  address: string;
  status: ContactStatus;
  isSmartContractAddress: boolean;
  tags?: string[];
  createdById: string;
  isSanctioned: boolean;
  externalId?: string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  assetList?: string[];
}

POST /api/external/contacts/

Request body

string

required

Contact display name.

string

Sub-org that owns the contact.

string

required

Destination address on the selected chain.

string

required

REST field. The SDK accepts this as chain.

string[]

Searchable contact tags.

string

Client-controlled reference.

string[]

Assets permitted for the contact. The SDK serializes an omitted value as an empty array.

string[]

Organization-scoped contact groups to attach.

Response

Returns the new Contact with status: "PENDING".

string

Contact ID.

string

Organization that owns the contact.

string

Sub-org that owns the contact, if any.

string

Contact display name.

string

Chain of the address.

string

Blockchain address.

ContactStatus

PENDING, APPROVED, or DECLINED. A new contact stays PENDING until it’s approved. See ContactStatus.

boolean

Whether the address is a smart contract.

string[]

Searchable contact tags.

string

User or API user that created the contact.

boolean

Whether the address is flagged by sanctions screening.

string

Your own reference, if you set one.

string[]

Assets permitted for the contact.

string

Creation timestamp (ISO 8601).

string

Last update timestamp (ISO 8601).

boolean

Whether the contact is deleted.

Approve the contact

A new contact comes back with status: "PENDING" and needs your API user’s approval. Call Get Approval Message with entityId set to the contact id, sign the message, and send the signature to Submit Approval Action. See Approvals for the full flow. With the SDK, approve separately or in one call:

const contact = await apiClient.createContact(request);
const approvedContact = await apiClient.createContactApproval(contact);

// Convenience helper: create, then approve.
const approved = await apiClient.createContactWithApproval(request);

REST request body

{
  "name": "Operations Wallet",
  "subOrgId": "sub_org_123",
  "address": "0xAbC123...",
  "blockChain": "ETHEREUM",
  "tags": ["vendor", "priority"],
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "contactGroupIds": ["contact_group_123"]
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/contacts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Operations Wallet",
    "subOrgId": "sub_org_123",
    "address": "0xAbC123...",
    "blockChain": "ETHEREUM",
    "tags": ["vendor", "priority"],
    "externalId": "vendor-1001",
    "assetList": ["USDC", "ETH"],
    "contactGroupIds": ["contact_group_123"]
  }'

interface CreateContactRequest {
  name: string;
  subOrgId?: string;
  address: string;
  chain: string;
  tags?: string[];
  externalId?: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

createContact(request: CreateContactRequest): Promise<Contact>

Response example

{
  "id": "contact_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "name": "Operations Wallet",
  "blockChain": "ETHEREUM",
  "address": "0xAbC123...",
  "status": "PENDING",
  "tags": ["vendor", "priority"],
  "createdById": "api_user_123",
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false
}

interface Contact {
  id: string;
  orgId: string;
  subOrgId?: string;
  name: string;
  blockChain: string;
  address: string;
  status: ContactStatus;
  isSmartContractAddress: boolean;
  tags?: string[];
  createdById: string;
  isSanctioned: boolean;
  externalId?: string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  assetList?: string[];
}

⌘I

REST request body

{
  "name": "Operations Wallet",
  "subOrgId": "sub_org_123",
  "address": "0xAbC123...",
  "blockChain": "ETHEREUM",
  "tags": ["vendor", "priority"],
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "contactGroupIds": ["contact_group_123"]
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/contacts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Operations Wallet",
    "subOrgId": "sub_org_123",
    "address": "0xAbC123...",
    "blockChain": "ETHEREUM",
    "tags": ["vendor", "priority"],
    "externalId": "vendor-1001",
    "assetList": ["USDC", "ETH"],
    "contactGroupIds": ["contact_group_123"]
  }'

interface CreateContactRequest {
  name: string;
  subOrgId?: string;
  address: string;
  chain: string;
  tags?: string[];
  externalId?: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

createContact(request: CreateContactRequest): Promise<Contact>

Response example

{
  "id": "contact_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "name": "Operations Wallet",
  "blockChain": "ETHEREUM",
  "address": "0xAbC123...",
  "status": "PENDING",
  "tags": ["vendor", "priority"],
  "createdById": "api_user_123",
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false
}

interface Contact {
  id: string;
  orgId: string;
  subOrgId?: string;
  name: string;
  blockChain: string;
  address: string;
  status: ContactStatus;
  isSmartContractAddress: boolean;
  tags?: string[];
  createdById: string;
  isSanctioned: boolean;
  externalId?: string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  assetList?: string[];
}

API Basics

Approvals

Vaults

Blockchain Contacts

Bank Accounts

Assets and Chains

Sub-Orgs

Transactions

Create a Blockchain Contact

Request body

Response

Approve the contact

​Request body

​Response

​Approve the contact

Request body

Response

Approve the contact