Create a 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>

{
  "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
}

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

{
  "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
}

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);

JavaScript SDK

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

createContact(request: CreateContactRequest): Promise<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>

{
  "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
}

⌘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>

{
  "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
}

API Basics

Approvals

Accounts

Sub-Orgs

Transactions

Request body

Response

Approve the contact

JavaScript SDK

​Request body

​Response

​Approve the contact

​JavaScript SDK

Request body

Response

Approve the contact

JavaScript SDK