---
title: "Create a new relationship"
method: POST
path: "/entities/{entityDID}/relationships"
tags: ["Relationships"]
---

# Create a new relationship

`POST /entities/{entityDID}/relationships`

Creates a new relationship between an address and an entity. Relationships establish ownership or control over blockchain addresses. Optionally includes an ownership proof for verification.

## Path parameters

- `entityDID` string, did, required — Decentralized Identifier (DID)

## Request body

- object
  - `from` string
  - `to` string, required
  - `custodian` string
  - `proof` union
    - object
      - `status` 'pending' | 'rejected' | 'flagged' | 'verified', required
      - `did` string, required
      - `address` string, required
      - `xpub` string
      - `chainSpecificData` object
      - `type` 'eip-191' | 'eip-712' | 'eip-1271' | 'bip-137' | 'bip-322' | 'tip-191' | 'ed25519' | 'xrp-ed25519' | 'xlm-ed25519' | 'cip-8' | 'siwe' | 'siwx', required
      - `proof` string, required
      - `attestation` string, required
      - `wallet_provider` string, nullable
    - object
      - `status` 'pending' | 'rejected' | 'flagged' | 'verified', required
      - `did` string, required
      - `address` string, required
      - `xpub` string
      - `chainSpecificData` object
      - `type` 'screenshot', required
      - `url` string, uri, required
    - object
      - `status` 'pending' | 'rejected' | 'flagged' | 'verified', required
      - `did` string, required
      - `address` string, required
      - `xpub` string
      - `chainSpecificData` object
      - `type` 'self-declaration', required
      - `confirmed` boolean, required
      - `attestation` string
    - object
      - `status` 'pending' | 'rejected' | 'flagged' | 'verified', required
      - `did` string, required
      - `address` string, required
      - `xpub` string
      - `chainSpecificData` object
      - `type` 'microtransfer', required
      - `proof` string
      - `chain` string
      - `destination` string
      - `amountSubunits` number
  - `asset` string

## Response `201`

Relationship created successfully

- object
  - `relationship` object, required
    - `@id` string, required
    - `@type` string
    - `from` string, required
    - `to` string, required
    - `custodian` string, nullable
    - `status` 'UNCONFIRMED' | 'CONFIRMED' | 'PROVEN', required
    - `memoTag` string, nullable
    - `createdTime` string
    - `updatedTime` string
    - `proofId` string

## Other responses

- `400` — Bad Request - The server could not process the request due to a client error.
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Not Found - The requested resource could not be found.
- `409` — Conflict - The request could not be completed due to a conflict with the current state of the resource.
- `500` — Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.net/notabene/apis/notabene-api.md) · [All operations](https://skmtc.net/notabene/apis/notabene-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notabene/notabene-api/versions/70056745a433/schema)