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. For an end-to-end purchasing and verification example, see Buy a DID Number That Requires Verification.

Preparing a permanent document

1. Retrieve the applicable Address Requirement and inspect the personal or business permanent-document relationship.

2. Retrieve the referenced Supporting Document Template, 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.

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.

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

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.

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 /v3/permanent_supporting_documents/{id}

Data reference

See Permanent Supporting Documents Object 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 — Determine which personal or business permanent template is required.

• Supporting Document Templates — Retrieve and download the permanent form referenced by the requirement.

• Encrypted Files — Encrypt and upload the completed form before creating the Permanent Supporting Document.

• Identities — Manage the personal or business Identity that owns the reusable document.

• Address Requirement Validation — Check the Identity and Address after all required records have been prepared.

• Address Verifications — Submit the prepared DIDs and compliance records for review.