Create an Identity

`POST` request to `/identities` to create an Identity.

POST to /identity

Creates an offchain Identity. Consider pairing this with createAtom for onchain Identity creation. The Intuition Portal user journey for creating a Identity combines both of these interactions.

POST https://api.intuition.systems/identity

Fetch

   await fetch(`${apiUrl}/identity`, {
      method: 'POST',
      "headers": {
        "Content-Type": "application/json",
        "x-api-key": <API_KEY>
      },
      "body": {
         "display_name": "JP", // Required display name for Identity
         "creator": "0x...81", // Ethereum address for Identity creator
         "description": "It is JP.", // Optional description for identity
         "image": "https://my-image.com/me.jpg", // Optional image for Identity
         "external_reference": "https://github.com", // Optional link for Identity
      }
    })

Curl

curl -X POST "https://api.intuition.systems/identity" \
     -H "Content-Type: application/json" \
     -H "x-api-key: <API_KEY>" \
     -d '{
           "display_name": "JP",
           "creator": "0x...81",
           "description": "It is JP.",
           "image": "https://my-image.com/me.jpg",
           "external_reference": "https://github.com",
         }'

Security

This request requires a valid API Key to be included with each request.

Headers

• Content-Type: application/json

• x-api-key: <API_Key>

Body Parameters

Parameter	Description
display_name	string - Required The display_name for the Identity. Example: MyIdentity
creator	string - Required The Ethereum address of the Identity creator. Example: 0x...81
description	string - Optional The description for the Identity. Example: This is my Identity.
image_url	string - Required The image_url for the Identity. This should be a valid URL. Example: https://my-image.com/me.jpg
external_reference	string - Optional An external_reference link for the Identity. This should be a valid URL. Example: https://github.com

Response

If an Identity is successfully created you'll receive the Identity object for the new Identity.

{
  "id": "f9xxxxxx...",
  "identity_id": "did:intuition:ipfs:Xxx",
  "identity_hash": "x...",
  "display_name": "JP",
  "description": "It's me, JP",
  "image": "image_url",
  "creator": {
      "id": "7xxxxxxx...",
      "created_at": "2024-02-13T14:58:43.809055Z",
      "updated_at": "2024-02-13T14:58:43.809055Z",
      "last_login": "2024-02-21T18:47:26.556035Z",
      "api_key": "",
      "wallet": "0x...",
      "role": "User"
  },
  "status": "complete",
  "created_at": "2024-02-15T05:47:17.289011Z",
  "num_positions": 0,
  "updated_at": "2024-02-15T05:47:17.289011Z",
  "vault_id": "1",
  "assets_sum": "0",
  "conviction_sum": "0",
  "conviction_price": "0"
},

Here is an example Zod schema and TypeScript interface you can use for the Identity:

Zod

export const IdentitySchema = z.object({
  identity_id: z.string(),
  vault_id: z.string(),
  display_name: z.string(),
  description: z.string().optional(),
  image: z.string().optional(),
  corpora_id: z.string().nullish(),
  semantic: z.string().nullish(),
  external_reference: z.string().nullish(),
  creator: EmbedUserUserAggregatesSchema.optional(),
  created_at: z.string(),
  num_positions: z.number(),
  assets_sum: z.string(), // bigint
  conviction_sum: z.string(), // bigint
  conviction_price: z.string(), // bigint
  updated_at: z.string(),
  status: z.string().optional(),
  isUser: z.boolean().optional(),
  user_conviction: z.string().optional(), // bigint
  user_conviction_value: z.string().optional(), // bigint
}

Interface

// if using Zod, you can directly infer:
 
export type Identity = z.infer<typeof IdentitySchema>

// used in another interface:

interface ClaimProps {
  subject: Identity | null
  predicate: Identity | null
  object: Identity | null
}

export const UserSchema = z.object({
  did: z.string().optional(),
  wallet: z.string(),
  display_name: z.string().optional(),
  image: z.string().optional(),
  id: z.string().uuid(),
})

// if not using Zod, here's an example of the Identity type:

type Identity = {
    vault_id: string;
    created_at: string;
    updated_at: string;
    display_name: string;
    identity_id: string;
    num_positions: number;
    assets_sum: string;
    conviction_sum: string;
    conviction_price: string;
    updated_at: string;
    num_positions: number;
    assets_sum: string;
    conviction_sum: string;
    conviction_price: string;
    updated_at: string;
    status?: string;
    isUser?: string;
    user_conviction?: string;
    user_conviction_value?: string;

Response Codes

Code	Description
200	OK Identity successfully created. Response data.
400	Bad Request Example: Improperly formatted JSON, such as including a trailing comma.
404