> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/documentation/document-services/operations/main.md).

# Initiate Document

## Initiate Document

> Creates a new document directory entry and uploads/registers its content and metadata.\
> \
> The source documentation only specifies the request/response message contract; HTTP status codes are not documented and have been assigned conventionally.<br>

```json
{"openapi":"3.0.3","info":{"title":"NEXUS Banking Services API","version":"1.0.0"},"tags":[{"name":"document-services"}],"servers":[{"url":"https://sandbox.nexus.selenium.ao","description":"Sandbox"},{"url":"https://api-mock.selenium.ao","description":"Mock"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer Token (OAuth2 / OIDC or JWT) passed in the `Authorization` header."}},"schemas":{"DocumentDirectoryConfiguration":{"type":"object","description":"Configuration of the document service for a directory instance.","properties":{"documentServiceType":{"type":"string","description":"Type of document service."},"documentCategory":{"type":"string","description":"Category of the document."},"documentUpdateFrequency":{"type":"string","description":"Update frequency of the directory."},"documentMaintainerReference":{"type":"string","description":"Reference of the system/service responsible for maintenance."}}},"DocumentEntryDetails":{"type":"object","description":"Core document metadata shared and extended (via `allOf`) across the Initiate, Retrieve, Update and Grant document-services operations.","properties":{"documentType":{"type":"string","description":"Type of the document."},"documentSubType":{"type":"string","description":"Subtype of the document."},"documentName":{"type":"string","description":"Name of the document."},"documentDescription":{"type":"string","description":"Description of the document."},"documentFormat":{"type":"string","description":"File format."},"documentMimeType":{"type":"string","description":"MIME type of the file."},"documentLanguage":{"type":"string","description":"Language of the document."},"documentClassification":{"type":"string","description":"Confidentiality classification."},"documentRetentionPeriod":{"type":"string","description":"ISO 8601 duration, e.g. `P10Y`."},"documentOwnership":{"$ref":"#/components/schemas/DocumentOwnership"},"documentSecurity":{"$ref":"#/components/schemas/DocumentSecurity"},"documentContent":{"$ref":"#/components/schemas/DocumentContent"},"documentCompliance":{"$ref":"#/components/schemas/DocumentCompliance"},"documentWorkflow":{"$ref":"#/components/schemas/DocumentWorkflow"},"businessContext":{"$ref":"#/components/schemas/BusinessContext"}}},"DocumentOwnership":{"type":"object","description":"Owner of a document.","properties":{"documentOwnerReference":{"type":"string","description":"Reference of the document owner."},"documentOwnerType":{"type":"string","description":"Type of the document owner."},"documentOwnerName":{"type":"string","description":"Name of the document owner."}}},"DocumentSecurity":{"type":"object","description":"Security configuration and state of a document.","properties":{"encryptionMethod":{"type":"string","description":"Encryption method applied."},"encryptionStatus":{"type":"string","description":"Encryption status."},"accessLevel":{"type":"string","description":"Access level required for the document."},"accessPermissions":{"type":"array","description":"Access permissions granted.","items":{"type":"string"}},"digitalSignatureRequired":{"type":"boolean","description":"Whether a digital signature is required."},"digitalSignature":{"type":"boolean","description":"Whether the document is digitally signed."},"checksumMD5":{"type":"string","description":"MD5 checksum of the document."},"checksumSHA256":{"type":"string","description":"SHA-256 checksum of the document."}}},"DocumentContent":{"type":"object","description":"Content and metadata of a document file.","properties":{"documentData":{"type":"string","format":"byte","nullable":true,"description":"Base64-encoded document content."},"documentMetadata":{"type":"object","description":"Shape varies by document type (e.g. identification, contract, employment declaration).","additionalProperties":true},"documentExtractedData":{"type":"object","description":"Shape varies by document type.","additionalProperties":true}}},"DocumentCompliance":{"type":"object","description":"Regulatory compliance requirements and status of a document.","properties":{"regulatoryRequirements":{"type":"array","description":"Applicable regulatory requirements.","items":{"type":"string"}},"complianceChecksRequired":{"type":"boolean","description":"Whether compliance checks are required."},"privacyConsent":{"type":"boolean","description":"Whether privacy consent was given."},"retentionConsentGiven":{"type":"boolean","description":"Whether retention consent was given."},"complianceStatus":{"type":"string","description":"Current compliance status."},"lastComplianceCheck":{"type":"string","format":"date-time","description":"Date/time of the last compliance check."},"nextComplianceReview":{"type":"string","format":"date-time","description":"Date/time of the next compliance review."},"retentionCompliance":{"type":"string","description":"Retention compliance status."},"privacyCompliance":{"type":"string","description":"Privacy compliance status."}}},"DocumentWorkflow":{"type":"object","description":"Workflow state of a document.","properties":{"initialWorkflowState":{"type":"string","description":"Initial workflow state."},"currentWorkflowState":{"type":"string","description":"Current workflow state."},"workflowOwner":{"type":"string","description":"Team/system responsible for the workflow."},"processingPriority":{"type":"string","description":"Priority of processing."},"expectedProcessingTime":{"type":"string","description":"ISO 8601 duration."},"notificationRequired":{"type":"boolean","description":"Whether a notification is required."},"nextAction":{"type":"string","description":"Next action planned in the workflow."},"estimatedCompletionTime":{"type":"string","description":"Estimated time of completion."},"workflowHistory":{"type":"array","description":"History of workflow transitions.","items":{"$ref":"#/components/schemas/WorkflowHistoryEntry"}}}},"WorkflowHistoryEntry":{"type":"object","description":"Single entry in a document's workflow history.","properties":{"state":{"type":"string","description":"Workflow state at this entry."},"timestamp":{"type":"string","format":"date-time","description":"Date/time of the entry."},"actor":{"type":"string","description":"Actor who performed the action."},"actorReference":{"type":"string","description":"Reference of the actor."},"comment":{"type":"string","description":"Free-text comment on the entry."},"systemGenerated":{"type":"boolean","description":"Whether the entry was generated automatically by the system."}}},"BusinessContext":{"type":"object","description":"Business context associated with a document.","properties":{"relatedAccountId":{"type":"string","nullable":true,"description":"Related account identifier, when applicable."},"relatedApplicationId":{"type":"string","description":"Related application identifier."},"businessProcess":{"type":"string","description":"Business process associated with the document."},"documentPurpose":{"type":"string","description":"Purpose of the document."},"externalReferences":{"type":"object","properties":{"applicationReference":{"type":"string","description":"Reference of the related application."},"caseReference":{"type":"string","description":"Reference of the related case."}}}}},"DocumentLocation":{"type":"object","description":"Storage location of a document.","properties":{"documentStorageType":{"type":"string","description":"Type of storage."},"documentStorageLocation":{"type":"string","description":"Location of the stored document."},"documentAccessUrl":{"type":"string","description":"URL to access the document."},"documentUploadId":{"type":"string","description":"Identifier of the upload."},"primaryLocation":{"type":"string","description":"Primary location of the archived document."},"backupLocation":{"type":"string","description":"Backup location of the document."},"geographicLocation":{"type":"string","description":"Geographic region of storage."},"accessMethod":{"type":"string","description":"Method used to access the document."},"retrievalTime":{"type":"string","description":"ISO 8601 duration."},"retrievalCost":{"type":"string","description":"Estimated cost of retrieval."}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["status","reason","message","path"],"properties":{"status":{"type":"integer","description":"HTTP status code of the error."},"reason":{"type":"string","description":"High-level error category code."},"message":{"type":"string","description":"Human-readable description of the problem."},"path":{"type":"string","description":"HTTP method and endpoint path that originated the error."},"errordetail":{"type":"array","description":"Detailed error list. May be absent for generic errors (e.g. 500).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string","description":"Domain-specific error code."},"reason":{"type":"string","description":"Textual identifier of the specific cause."},"message":{"type":"string","description":"Detailed message, with concrete values where applicable."}}}},"responses":{"BadRequest":{"description":"The request payload is invalid — inconsistent dates, an amount ≤ 0, an invalid currency, or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing, expired or invalid Bearer Token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Unexpected internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/v1/document-services/document-directory":{"post":{"summary":"Initiate Document","description":"Creates a new document directory entry and uploads/registers its content and metadata.\n\nThe source documentation only specifies the request/response message contract; HTTP status codes are not documented and have been assigned conventionally.\n","tags":["document-services"],"operationId":"initiateDocument","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentDirectoryInitiateInputRecord":{"type":"object","description":"Root object of the document initiation request.","properties":{"documentDirectoryInitiateActionRequest":{"type":"string","description":"Business action requested."},"documentDirectoryInitiateActionTaskRecord":{"type":"object","description":"Task record for the document initiation.","properties":{"documentDirectoryInitiateActionRequest":{"type":"string","description":"Business action requested (repeated at task level)."},"documentDirectoryInitiateActionTaskReference":{"type":"string","description":"Unique reference of the initiation task."},"documentDirectoryInstanceRecord":{"type":"object","description":"Record of the document directory instance.","properties":{"documentDirectoryInstanceReference":{"type":"string","description":"Unique identifier of the document directory instance."},"documentDirectoryConfiguration":{"allOf":[{"$ref":"#/components/schemas/DocumentDirectoryConfiguration"}],"description":"Configuration of the document service."},"documentDirectoryEntryRecord":{"type":"object","description":"Record of the document entry to create.","properties":{"documentEntryDetails":{"$ref":"#/components/schemas/DocumentEntryDetails"}}}}}}}}}}}}}},"responses":{"201":{"description":"Document initiated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"documentDirectoryInitiateOutputRecord":{"type":"object","properties":{"documentDirectoryInitiateActionTaskRecord":{"type":"object","properties":{"documentDirectoryInitiateActionTaskRecord":{"type":"object","properties":{"documentDirectoryInstanceRecord":{"type":"object","properties":{"documentDirectoryInstanceReference":{"type":"string","description":"Unique identifier of the document directory instance."},"documentDirectoryInstanceStatus":{"type":"string","description":"Status of the directory instance."},"documentDirectoryConfiguration":{"$ref":"#/components/schemas/DocumentDirectoryConfiguration"},"documentDirectoryEntryRecord":{"type":"object","properties":{"documentEntryReference":{"type":"string","description":"Unique identifier assigned to the document."},"documentEntryDetails":{"allOf":[{"$ref":"#/components/schemas/DocumentEntryDetails"},{"type":"object","properties":{"documentId":{"type":"string","description":"Unique identifier assigned to the document."},"documentStatus":{"type":"string","description":"Status of the document after initiation."},"documentSize":{"type":"integer","description":"Size of the file, in bytes."},"documentVersion":{"type":"string","description":"Version of the document."},"documentCreationDate":{"type":"string","format":"date-time","description":"Date/time the document was created."},"documentLastModifiedDate":{"type":"string","format":"date-time","description":"Date/time of the last modification."},"documentExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Expiry date of the document, when applicable."},"documentLocation":{"$ref":"#/components/schemas/DocumentLocation"}}}]}}}}}}}}}}},"documentDirectoryInitiateActionResponse":{"type":"object","description":"Outcome of the document initiation.","properties":{"documentDirectoryInitiateActionResponseCode":{"type":"string","description":"Result code of the operation."},"documentDirectoryInitiateActionResponseMessage":{"type":"string","description":"Human-readable message describing the result."},"documentDirectoryInitiateActionResponseDetails":{"type":"object","description":"Additional details of the initiation result.","properties":{"documentId":{"type":"string","description":"Identifier of the created document."},"uploadReference":{"type":"string","description":"Reference of the upload."},"processingEstimate":{"type":"string","description":"Estimated processing time."},"nextSteps":{"type":"array","description":"Next steps in the process.","items":{"type":"string"}},"notificationsSent":{"type":"array","description":"Notifications sent as a result of the initiation.","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://selenium-4.gitbook.io/nexus-docs/documentation/document-services/operations/main.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.