> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primevault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Contact

> Save a blockchain address as a contact. The contact needs your API user's approval before it takes effect.

**POST** `/api/external/contacts/`

## Request body

<ParamField body="name" type="string" required>
  Contact display name.
</ParamField>

<ParamField body="subOrgId" type="string">
  Sub-org that owns the contact.
</ParamField>

<ParamField body="address" type="string" required>
  Destination address on the selected chain.
</ParamField>

<ParamField body="blockChain" type="string" required>
  REST field. The SDK accepts this as `chain`.
</ParamField>

<ParamField body="tags" type="string[]">
  Searchable contact tags.
</ParamField>

<ParamField body="externalId" type="string">
  Client-controlled reference.
</ParamField>

<ParamField body="assetList" type="string[]">
  Assets permitted for the contact. The SDK serializes an omitted value as an empty array.
</ParamField>

<ParamField body="contactGroupIds" type="string[]">
  Organization-scoped contact groups to attach.
</ParamField>

## Response

```json theme={null}
{
  "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](/approvals/get-approval-message) with `entityId` set to the contact `id`, sign the `message`, and send the signature to [Submit Approval Action](/approvals/submit-approval-action). See [Approvals](/approvals/overview) for the full flow.

With the SDK, approve separately or in one call:

```typescript theme={null}
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

```typescript theme={null}
interface CreateContactRequest {
  name: string;
  subOrgId?: string;
  address: string;
  chain: string;
  tags?: string[];
  externalId?: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

createContact(request: CreateContactRequest): Promise<Contact>
```

<RequestExample dropdown>
  ```json REST request body theme={null}
  {
    "name": "Operations Wallet",
    "subOrgId": "sub_org_123",
    "address": "0xAbC123...",
    "blockChain": "ETHEREUM",
    "tags": ["vendor", "priority"],
    "externalId": "vendor-1001",
    "assetList": ["USDC", "ETH"],
    "contactGroupIds": ["contact_group_123"]
  }
  ```

  ```bash cURL theme={null}
  # 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"]
    }'
  ```

  ```typescript JavaScript SDK theme={null}
  interface CreateContactRequest {
    name: string;
    subOrgId?: string;
    address: string;
    chain: string;
    tags?: string[];
    externalId?: string;
    assetList?: string[];
    contactGroupIds?: string[];
  }

  createContact(request: CreateContactRequest): Promise<Contact>
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.