# Create Bitstring Status List

Users are able to create Bitstring Status List entries on-ledger, in order to revoke or suspend Verifiable Credentials. This is a derivation from the core spec made by cheqd to support a more decentralized and resilient approach to storing Status Lists.

## Step 1: Set up your account

Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Set up your account</strong></mark></td><td>Set up your account with cheqd Studio and log in to start using the APIs.</td><td><a href="../../../getting-started/studio/set-up-account">set-up-account</a></td></tr></tbody></table>

## Step 2: Create a DID

Before you can create a Status List, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Create an Issuer DID</strong></mark></td><td>Create a W3C conformant DID on cheqd using the <code>did:cheqd</code> DID Method.</td><td><a href="../../dids/create-did">create-did</a></td></tr></tbody></table>

## Step 3: Select the unencrypted Status List API

When [creating a Status List](https://docs.cheqd.io/product/studio/status-lists), a user will have the following options:&#x20;

<details>

<summary>/credential-status/create/encrypted</summary>

Using this API will encrypt the bitstring of the Status List, meaning that a set of Payment Conditions will need to be met in order to access the Status List contents.

</details>

<details>

<summary>/credential-status/create/unencrypted</summary>

Using this API will create a regular Status List on-ledger, where the contents of the Status List are visible to any users who queries the blockchain.&#x20;

</details>

For the purpose of this tutorial, we will assume the user is creating an unencrypted Status List. For encrypted Status Lists, [follow the tutorial here](https://docs.cheqd.io/product/studio/payments/charge).

## Step 4: Create unencrypted Status List

Using the `/credential-status/create/unencrypted` API, users have two options for creating an encrypted Status List on-ledger:

1. **Filling out a simple form** using the `application/x-www-url-form-encoded` option within an API client of your choice.
2. **Compiling a Status List payload yourself** using the `application/json` option within an API client of your choice.

## Create an unencrypted StatusList2021 or BitstringStatusList credential status list.

> This endpoint creates an unencrypted StatusList2021 or BitstringStatusList credential status list. The StatusList is published as a DID-Linked Resource on ledger. As input, it can can take input parameters needed to create the status list via a form, or a pre-assembled status list in JSON format. Status lists can be created as either encrypted or unencrypted.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Status Lists"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"CredentialStatusCreateUnencryptedRequest":{"allOf":[{"$ref":"#/components/schemas/CredentialStatusCreateBody"}]},"CredentialStatusCreateBody":{"allOf":[{"type":"object","required":["did","statusListName"],"properties":{"did":{"description":"DID of the StatusList2021 or BitstringStatusList publisher.","type":"string","format":"uri"},"statusListName":{"description":"The name of the StatusList2021 or BitstringStatusList DID-Linked Resource to be created.","type":"string"},"length":{"description":"The length of the status list to be created. The default and minimum length is 131072 which is 16kb.","type":"integer","minimum":0,"exclusiveMinimum":true,"default":131072},"encoding":{"description":"The encoding format of the StatusList2021 or BitstringStatusList (only base64url supported) DiD-Linked Resource to be created.","type":"string","default":"base64url","enum":["base64url","hex"]},"statusListVersion":{"description":"Optional field to assign a human-readable version in the StatusList2021 or BitstringStatusList DID-Linked Resource.","type":"string"},"statusSize":{"description":"Only for BitstringStatusList: bits per credential, used to support multiple status in same list.","type":"integer","minimum":1},"credentialCategory":{"description":"Category of credentials this status list is for.","type":"string","enum":["credential","accreditation"]},"statusMessages":{"description":"Only for BitstringStatusList (Mandatory if statusSize > 1): Message explaining each bit","type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}},"ttl":{"description":"Only for BitstringStatusList: Time to Live in Miliseconds (not expiry).","type":"integer","minimum":1000}}},{"$ref":"#/components/schemas/AlsoKnownAs"}]},"AlsoKnownAs":{"type":"object","properties":{"alsoKnownAs":{"type":"array","description":"Optional field to assign a set of alternative URIs where the DID-Linked Resource can be fetched from.","items":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"URI where the DID-Linked Resource can be fetched from. Can be any type of URI (e.g., DID, HTTPS, IPFS, etc.)"},"description":{"type":"string","description":"Optional description of the URI."}}}}}},"CredentialStatusCreateUnencryptedResult":{"allOf":[{"type":"object","properties":{"created":{"type":"boolean"}}},{"$ref":"#/components/schemas/CredentialStatusUnencryptedResult"}]},"CredentialStatusUnencryptedResult":{"type":"object","properties":{"resource":{"type":"object","properties":{"StatusList2021":{"type":"object","properties":{"encodedList":{"type":"string"},"type":{"type":"string"},"validFrom":{"type":"string","format":"date-time"}}},"metadata":{"type":"object","properties":{"type":{"type":"string"},"encoding":{"type":"string"},"encrypted":{"type":"boolean"}}}}},"resourceMetadata":{"type":"object"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/credential-status/create/unencrypted":{"post":{"tags":["Status Lists"],"summary":"Create an unencrypted StatusList2021 or BitstringStatusList credential status list.","description":"This endpoint creates an unencrypted StatusList2021 or BitstringStatusList credential status list. The StatusList is published as a DID-Linked Resource on ledger. As input, it can can take input parameters needed to create the status list via a form, or a pre-assembled status list in JSON format. Status lists can be created as either encrypted or unencrypted.","parameters":[{"in":"query","name":"listType","description":"The type of Status List.","required":true,"schema":{"type":"string","enum":["StatusList2021","BitstringStatusList"]}},{"in":"query","name":"statusPurpose","description":"The purpose of the status list.\n- For StatusList2021: Single value (revocation or suspension)\n- For BitstringStatusList: Can accept multiple values as array of strings\n\nOnce this is set, it cannot be changed. A new status list must be created to change the purpose.\n","required":true,"schema":{"oneOf":[{"type":"string","enum":["revocation","suspension"]},{"type":"array","items":{"type":"string","enum":["revocation","suspension","message","refresh"]}}]}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedRequest"}}}},"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedResult"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```

### Option 1. Choose from a few variables and we will compile the Status List for you

This is the easiest way to create unencrypted Status Lists on cheqd and is recommended for users who are not overly familiar with compiling JSON objects.&#x20;

Using the `application/x-www-url-form-encoded` option, users are able to choose between the following variables and options to create an unencrypted Status List on-ledger:

<details>

<summary>statusPurpose (required)</summary>

* revocation (creates a Status List where each entry refers to revocation status)
* suspension (creates a Status List where each entry refers to suspension status. Note that suspended Credentials may become unsuspended).

</details>

<details>

<summary>did (required)</summary>

Enter the Decentralized Identifier (DID) of the Status List publisher [created in Step 2](#step-2-create-a-did). For example:

```json
did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63
```

</details>

<details>

<summary>statusListName (required)</summary>

This is the name of your Status List. This will also need to be kept consistent for all future updates of the same Status List. For example:

```json
employmentCredentialRevocationList
```

</details>

<details>

<summary>length (optional)</summary>

The length of the Status List to be created. The default and minimum length is 140000 which is 16kb. For example:

```json
140000
```

</details>

<details>

<summary>encoding (optional)</summary>

The encoding format of the encrypted StatusList DID-Linked Resource to be created.&#x20;

* base64url
* base64
* hex

</details>

<details>

<summary>statusListVersion (optional)</summary>

A user set value to represent the version of the Status List. For example:

```json
1.0
```

</details>

<details>

<summary>alsoKnownAs (optional)</summary>

A user set field to assign a set of alternative URIs where the DID-Linked Resource can be fetched from. For example:

```json
https://www.foo.com
```

</details>

### Option 2. Publish a JSON payload yourself

Instead of using simple form variables, you can create an encrypted Status List using a JSON payload yourself using the `application/json` option on the Swagger UI.&#x20;

#### Request format

An example of the JSON payload needed to be submitted is below:

```json
{
  "did": "did:cheqd:testnet:7c2b990c-3d05-4ebf-91af-f4f4d0091d2e",
  "statusListName": "cheqd-employee-credentials",
  "length": 140000,
  "encoding": "base64url"
}
```

## Step 5: Hit the API

Once the Issuer has populated the requisite information for the unencrypted Status List request, they can use the API below to submit it to the ledger.&#x20;

## Create an unencrypted StatusList2021 or BitstringStatusList credential status list.

> This endpoint creates an unencrypted StatusList2021 or BitstringStatusList credential status list. The StatusList is published as a DID-Linked Resource on ledger. As input, it can can take input parameters needed to create the status list via a form, or a pre-assembled status list in JSON format. Status lists can be created as either encrypted or unencrypted.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Status Lists"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"CredentialStatusCreateUnencryptedRequest":{"allOf":[{"$ref":"#/components/schemas/CredentialStatusCreateBody"}]},"CredentialStatusCreateBody":{"allOf":[{"type":"object","required":["did","statusListName"],"properties":{"did":{"description":"DID of the StatusList2021 or BitstringStatusList publisher.","type":"string","format":"uri"},"statusListName":{"description":"The name of the StatusList2021 or BitstringStatusList DID-Linked Resource to be created.","type":"string"},"length":{"description":"The length of the status list to be created. The default and minimum length is 131072 which is 16kb.","type":"integer","minimum":0,"exclusiveMinimum":true,"default":131072},"encoding":{"description":"The encoding format of the StatusList2021 or BitstringStatusList (only base64url supported) DiD-Linked Resource to be created.","type":"string","default":"base64url","enum":["base64url","hex"]},"statusListVersion":{"description":"Optional field to assign a human-readable version in the StatusList2021 or BitstringStatusList DID-Linked Resource.","type":"string"},"statusSize":{"description":"Only for BitstringStatusList: bits per credential, used to support multiple status in same list.","type":"integer","minimum":1},"credentialCategory":{"description":"Category of credentials this status list is for.","type":"string","enum":["credential","accreditation"]},"statusMessages":{"description":"Only for BitstringStatusList (Mandatory if statusSize > 1): Message explaining each bit","type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}},"ttl":{"description":"Only for BitstringStatusList: Time to Live in Miliseconds (not expiry).","type":"integer","minimum":1000}}},{"$ref":"#/components/schemas/AlsoKnownAs"}]},"AlsoKnownAs":{"type":"object","properties":{"alsoKnownAs":{"type":"array","description":"Optional field to assign a set of alternative URIs where the DID-Linked Resource can be fetched from.","items":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"URI where the DID-Linked Resource can be fetched from. Can be any type of URI (e.g., DID, HTTPS, IPFS, etc.)"},"description":{"type":"string","description":"Optional description of the URI."}}}}}},"CredentialStatusCreateUnencryptedResult":{"allOf":[{"type":"object","properties":{"created":{"type":"boolean"}}},{"$ref":"#/components/schemas/CredentialStatusUnencryptedResult"}]},"CredentialStatusUnencryptedResult":{"type":"object","properties":{"resource":{"type":"object","properties":{"StatusList2021":{"type":"object","properties":{"encodedList":{"type":"string"},"type":{"type":"string"},"validFrom":{"type":"string","format":"date-time"}}},"metadata":{"type":"object","properties":{"type":{"type":"string"},"encoding":{"type":"string"},"encrypted":{"type":"boolean"}}}}},"resourceMetadata":{"type":"object"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/credential-status/create/unencrypted":{"post":{"tags":["Status Lists"],"summary":"Create an unencrypted StatusList2021 or BitstringStatusList credential status list.","description":"This endpoint creates an unencrypted StatusList2021 or BitstringStatusList credential status list. The StatusList is published as a DID-Linked Resource on ledger. As input, it can can take input parameters needed to create the status list via a form, or a pre-assembled status list in JSON format. Status lists can be created as either encrypted or unencrypted.","parameters":[{"in":"query","name":"listType","description":"The type of Status List.","required":true,"schema":{"type":"string","enum":["StatusList2021","BitstringStatusList"]}},{"in":"query","name":"statusPurpose","description":"The purpose of the status list.\n- For StatusList2021: Single value (revocation or suspension)\n- For BitstringStatusList: Can accept multiple values as array of strings\n\nOnce this is set, it cannot be changed. A new status list must be created to change the purpose.\n","required":true,"schema":{"oneOf":[{"type":"string","enum":["revocation","suspension"]},{"type":"array","items":{"type":"string","enum":["revocation","suspension","message","refresh"]}}]}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedRequest"}}}},"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialStatusCreateUnencryptedResult"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```