# Proofs

Use the Proofs resource to retrieve and manage evidence required for DID registration.

A Proof links one or more Encrypted Files to an accepted Proof Type and to the entity being
verified. The `entity` can be a personal or business Identity, or an Address. A Proof also
provides its creation time, optional expiration time, and optional external reference ID.

Create Proofs only when the applicable Address Requirement specifies a proof quantity
greater than zero. The requirement also identifies which Proof Types are accepted for the
selected Identity type or Address.

Note

For the complete registration workflow, see [Regulation Resources](../index.html). For
an end-to-end purchasing and verification example, see [Buy a DID Number That
Requires Verification](../../../examples/buy-dids-with-verification.html).

## Selecting the required proof

Inspect the applicable [Address Requirement](../requirements/index.html) before uploading
documents:

| Entity | Required quantity | Accepted Proof Types |
| --- | --- | --- |
| Personal Identity | `personal_proof_qty` | `personal_proof_types` |
| Business Identity | `business_proof_qty` | `business_proof_types` |
| Address | `address_proof_qty` | `address_proof_types` |

When a required quantity is greater than zero:

1. Select one of the accepted Proof Types returned by the Address Requirement. You can use
   [Retrieve Proof Type](../proof-types/get-proof-type.html) when you need its name and
   entity type.
2. Retrieve the current RSA public key, encrypt the supporting document, and [create an
   Encrypted File](../encrypted-files/create-encrypted-files.html).
3. Create the Proof before the Encrypted File expires. Link the uploaded file or files, the
   accepted `proof_type`, and the relevant Identity or Address as `entity`.

The Proof Type's `entity_type` must correspond to the entity being verified. Its possible
values are `Personal`, `Business`, and `Address`.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Proofs | `GET` | `/v3/proofs` |
| Retrieve Proof | `GET` | `/v3/proofs/{id}` |
| Create Proof | `POST` | `/v3/proofs` |
| Delete Proof | `DELETE` | `/v3/proofs/{id}` |

## Retrieve all Proofs

Retrieves all Proofs associated with the account.

Use this endpoint to find existing evidence before creating another Proof. Results can be
filtered by `external_reference_id` and sorted by `created_at`, `expires_at`, or
`external_reference_id`. The related Proof Type and Identity or Address entity can be
included in the response.

See [Retrieve All Proofs](get-proofs.html).

```
GET /v3/proofs
```

## Retrieve Proof

Retrieves a specific Proof by its unique ID.

Use this endpoint to inspect the Proof's creation and expiration metadata, external
reference, accepted Proof Type, and related Identity or Address.

See [Retrieve Proof](get-proof.html).

```
GET /v3/proofs/{id}
```

## Create Proof

Creates a Proof for an Identity or Address.

Link one or more unexpired Encrypted Files, one accepted `proof_type`, and one `entity`.
The entity's JSON:API type must be `identities` or `addresses`. You may also set
`external_reference_id` to associate the Proof with an external system. Its maximum
length is 100 characters.

See [Create Proof](create-proof.html).

```
POST /v3/proofs
```

## Delete Proof

Deletes a Proof by its unique ID.

Use this endpoint to remove evidence that should no longer be linked to an Identity or
Address. There is no Proof update endpoint, so replace an incorrect Proof by deleting it
and creating the correct record.

See [Delete Proof](delete-proof.html).

```
DELETE /v3/proofs/{id}
```

## Data reference

See [Proofs Object](proofs-object.html) for all attributes and relationships returned by
the resource.

## Common Proof use cases

| Use case | Description |
| --- | --- |
| Add personal identity evidence | Link an accepted personal Proof Type and encrypted evidence to a personal Identity. |
| Add business identity evidence | Link an accepted business Proof Type and encrypted evidence to a business Identity. |
| Add address evidence | Link an accepted Address Proof Type and encrypted evidence to an Address. |
| Meet proof quantity requirements | Create the number of Proofs specified by the applicable personal, business, or address proof quantity. |
| Review existing evidence | Retrieve Proofs with their Proof Types and entities before validating registration data. |
| Check Proof expiration | Sort or inspect Proofs by `expires_at` to identify time-limited evidence. |
| Reconcile external records | Create and filter Proofs using `external_reference_id`. |
| Replace incorrect evidence | Delete an incorrect Proof and create a new Proof with the accepted type, entity, and Encrypted Files. |

## Related resources

- [Address Requirements](../requirements/index.html) - Determine how many Proofs are
  required and which Proof Types are accepted.
- [Proof Types](../proof-types/index.html) - Retrieve the names and entity types of
  available evidence categories.
- [Encrypted Files](../encrypted-files/index.html) - Encrypt and upload the document files
  linked to a Proof.
- [Identities](../identities/index.html) - Manage the personal or business entity linked
  to the Proof.
- [Addresses](../addresses/index.html) - Manage the Address entity linked to the Proof.
- [Address Requirement Validation](../requirements/address-requirement-validations.html) - Check the prepared Identity,
  Address, and Proofs against the requirement.
- [Address Verifications](../address-verifications/index.html) - Submit the prepared
  compliance records for review.

On this page