# Permanent Supporting Documents

Use the Permanent Supporting Documents resource to retrieve and manage reusable regulatory
documents linked to an Identity.

A Permanent Supporting Document links one or more completed Encrypted Files to a permanent
Supporting Document Template and a personal or business Identity. Once prepared, the same
document can be reused with that Identity where the same permanent document is required.

Create a Permanent Supporting Document only when the applicable Address Requirement
references `personal_permanent_document` or `business_permanent_document`. One-time
forms follow a different workflow and must be linked to an Address Verification through
`onetime_files`.

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).

## Preparing a permanent document

1. Retrieve the applicable [Address Requirement](../requirements/index.html) and inspect
   the personal or business permanent-document relationship.
2. Retrieve the referenced [Supporting Document Template](../supporting-document-templates/get-supporting-document-template.html), confirm that
   `permanent` is `true`, and download the form from its `url`.
3. Complete the form, encrypt it with a current DIDWW public key, and [create an
   Encrypted File](../encrypted-files/create-encrypted-files.html).
4. Create the Permanent Supporting Document before the Encrypted File expires. Link the
   completed file or files, the referenced template, and the Identity that owns the
   document.

Important

Do not create a Permanent Supporting Document for a template where `permanent` is
`false`. Attach the completed Encrypted File through `onetime_files` when
[creating the Address Verification](../address-verifications/create-address-verification.html).

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Permanent Supporting Documents | `GET` | `/v3/permanent_supporting_documents` |
| Retrieve Permanent Supporting Document | `GET` | `/v3/permanent_supporting_documents/{id}` |
| Create Permanent Supporting Document | `POST` | `/v3/permanent_supporting_documents` |
| Update Permanent Supporting Document | `PATCH` | `/v3/permanent_supporting_documents/{id}` |
| Delete Permanent Supporting Document | `DELETE` | `/v3/permanent_supporting_documents/{id}` |

## Retrieve all Permanent Supporting Documents

Retrieves all Permanent Supporting Documents associated with the account.

Use this endpoint to find an existing reusable document before creating another one.
Results can be filtered by `external_reference_id` and sorted by `created_at` or
`external_reference_id`. The related Supporting Document Template and Identity can be
included in the response.

See [Retrieve All Permanent Supporting Documents](get-permanent-documents.html).

```
GET /v3/permanent_supporting_documents
```

## Retrieve Permanent Supporting Document

Retrieves a specific Permanent Supporting Document by its unique ID.

Use this endpoint to inspect the creation time, external reference, template, and Identity
associated with a reusable document.

See [Retrieve Permanent Supporting Document](get-permanent-document.html).

```
GET /v3/permanent_supporting_documents/{id}
```

## Create Permanent Supporting Document

Creates a reusable supporting document for an Identity.

The `files`, `template`, and `identity` relationships are required. Link one or more
unexpired Encrypted Files containing the completed form, the permanent Supporting Document
Template, and the Identity that will reuse the document. You may also set
`external_reference_id` to associate the record with an external system. Its maximum
length is 100 characters.

See [Create Permanent Supporting Document](create-permanent-document.html).

```
POST /v3/permanent_supporting_documents
```

## Update Permanent Supporting Document

Updates the `external_reference_id` of a Permanent Supporting Document.

Only `external_reference_id` can be changed through this endpoint. The `files`,
`template`, `identity`, and `created_at` values cannot be updated; sending any of
them returns an HTTP `400` error with code `105`, and the document is left unchanged.
To replace the document content, template, or identity, create a new Permanent Supporting
Document - creating one for the same template and identity supersedes the previous
document.

See [Update Permanent Supporting Document](update-permanent-document.html).

```
PATCH /v3/permanent_supporting_documents/{id}
```

## Delete Permanent Supporting Document

Deletes a Permanent Supporting Document by its unique ID.

Use this endpoint when a reusable document should no longer be linked to an Identity.
Content, template, and identity changes are made by creating a new Permanent Supporting
Document rather than by updating the existing one.

See [Delete Permanent Supporting Document](delete-permanent-document.html).

```
DELETE /v3/permanent_supporting_documents/{id}
```

## Data reference

See [Permanent Supporting Documents Object](permanent-documents-object.html) for all
attributes and relationships returned by the resource.

## Common Permanent Supporting Document use cases

| Use case | Description |
| --- | --- |
| Prepare a personal regulatory form | Link a completed personal permanent template and its Encrypted Files to a personal Identity. |
| Prepare a business regulatory form | Link a completed business permanent template and its Encrypted Files to a business Identity. |
| Reuse an approved Identity | Use the permanent document already linked to the Identity where the same permanent document is required. |
| Find an existing document | Retrieve records with their templates and Identities before creating a duplicate. |
| Reconcile external records | Update, create, filter, and sort records using `external_reference_id`. |
| Replace document content | Create a new Permanent Supporting Document for the same template and Identity; it supersedes the previous document. Delete a record directly when no replacement is needed. |

## Related resources

- [Address Requirements](../requirements/index.html) - Determine which personal or
  business permanent template is required.
- [Supporting Document Templates](../supporting-document-templates/index.html) - Retrieve
  and download the permanent form referenced by the requirement.
- [Encrypted Files](../encrypted-files/index.html) - Encrypt and upload the completed form
  before creating the Permanent Supporting Document.
- [Identities](../identities/index.html) - Manage the personal or business Identity that
  owns the reusable document.
- [Address Requirement Validation](../requirements/address-requirement-validations.html) - Check the Identity and Address after
  all required records have been prepared.
- [Address Verifications](../address-verifications/index.html) - Submit the prepared DIDs
  and compliance records for review.

On this page