# Define & add new credentials

## The Credential Schema Structure

Before attesting a credential to a user, you must first define its schema.

A credential consists of two parts: a **slug name**, which serves as a unique identifier, and a **list of fields** with their corresponding values.

<table><thead><tr><th width="132">Property</th><th width="118">Type</th><th width="112" data-type="checkbox">Required?</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><strong>slug</strong></td><td>String</td><td>true</td><td>A unique and descriptive name for the credential schema.</td><td>'monthly_expense'</td></tr><tr><td><strong>name</strong></td><td>String</td><td>false</td><td>A short, human-readable name for the credential</td><td>'Monthly expense per category'</td></tr><tr><td><strong>description</strong></td><td>String</td><td>false</td><td>A detailed explanation of the credential, including how it’s calculated and how to interpret it. This helps make the credential self-explanatory.</td><td>'The average financial expenses over the 90 days preceding the credential’s generation date, calculated using data from Plaid. This includes transactions from both credit cards and bank accounts'</td></tr><tr><td><strong>codeUrl</strong></td><td>String</td><td>false</td><td>A direct URL to the code snippet used to calculate this credential. This promotes transparency and allows others to verify how the credential was generated. The link can point to a GitHub repository or any other trusted source provider</td><td></td></tr><tr><td><strong>fields</strong></td><td>JSON</td><td>false</td><td>A payload for the credential, which includes a list of fields and their corresponding values.</td><td>{<br>  "name": "expense",<br>  "type": "uint",<br>  "description": "the dollar value of the average expense"<br>}</td></tr></tbody></table>

### Credential field types

| Type   | Example               |
| ------ | --------------------- |
| uint   | 130; 5400             |
| string | 'USD'; 'Low Fat Milk' |

{% hint style="warning" %}
**Credential Limit**&#x20;

Each credential schema can contain **up to 12 fields**.
{% endhint %}

## Define a New Credential Schema

<mark style="color:green;">`POST`</mark> `/api.moojo.id/define-credential`

**Headers**

| Name         | Value                               |
| ------------ | ----------------------------------- |
| Content-Type | `application/json`                  |
| x-api-key    | `Your API KEY as provided by Moojo` |

**Body**

| Name               | Type             | Description                              |
| ------------------ | ---------------- | ---------------------------------------- |
| `slug`             | string           | A unique name of the credential's scheme |
| `fieldDefinitions` | Array of objects | An array of fields definition            |

**Request example**

{% tabs %}
{% tab title="body" %}
{% code overflow="wrap" %}

```json
{
    "slug": "groceries-expenses",
    "name": "Groceries Expenses",
    "description": "The user’s grocery spending, calculated as the average over the 90 days preceding the credential’s generation date. Based on data provided by MasterCard.",
    "codeUrl": "https://github.com/my-code-url"
    "fieldDefinitions": [  {"name":"monthly-spend",
                            "type":"uint",
                            "description":"The average monthly expense"},
                           {"name":"currency",
                            "type":"string",
                            "description":"3-digit currency code"}
                         ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Response example**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "traceId": "b1adc9d8-1bb2-43c2-98d7-2ce6573f8b63",
    "data": {
        "credentialDefinition": {
            "slug": "groceries-expenses",
            "name": "Groceries Expenses",
            "description": "The user’s grocery spending, calculated as the average over the 90 days preceding the credential’s generation date. Based on data provided by MasterCard.",
            "codeUrl": "https://github.com/my-code-url"
            "ownerAddress": "0x8b689df125676bafa90b923edc4a92a2ea4b0000"
            "fieldDefinitions": [  {"name":"monthly-spend",
                                    "type":"uint",
                                    "description":"The average monthly expense"},
                                   {"name":"currency",
                                    "type":"string",
                                    "description":"3-digit currency code"}
                                 ]
         }
    }
}
```

{% endtab %}
{% endtabs %}

## Add a Credential to a User

After defining a credential schema, you can begin adding credentials based on it to users

<mark style="color:green;">`POST`</mark> `/api.moojo.id/user/add-credential`

**Headers**

| Name         | Value                               |
| ------------ | ----------------------------------- |
| Content-Type | `application/json`                  |
| x-api-key    | `Your API KEY as provided by Moojo` |

**Body**

| Name           | Type   | Description                                                                                                                  |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `publicUserId` | string | The publicUserId of the user receiving the credential. This ID can be found in the response of the user authentication call. |
| `slug`         | string | The unique name of the credential to be added, as defined by the scheme.                                                     |
| `fields`       | Object | An object containing all fields defined in the scheme along with their corresponding values. See the example below.          |

**Request example**

{% tabs %}
{% tab title="body" %}
{% code overflow="wrap" %}

```json
{
  "publicUserId": "{{publicUserId}}",
  "slug": "groceries-expenses",
  "fields": {
    "monthly-spend": 300,
    "currency": "USD"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Response example**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "traceId": "de665302-fb90-4742-85ca-fd399d681fd7",
    "data": {
        "attestedCredential": {
            "createdAt": 1739442337986,
            "issuerAddress": "0x8b689df125676bafa90b923edc4a92a2ea000000",
            "recipientAddress": "0x4e8aefeffaad79fcc520b1c46d09d13ae4000000",
            "slug": "groceries-expenses",
            "fields": {
                "monthly-spend": 300,
                "currency": "USD"
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.moojo.id/user-credentials/define-and-add-new-credentials.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.