Document update

Updates the metadata of an existing customer document.

This endpoint allows you to modify the document type and description without changing the actual file content. Useful for correcting document categorization or adding additional context.

Endpoint

POST/v2/customer/{customerId}/file/{id}

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Path Parameters

Parameter	Type	Description	Required	Example
customerId	string	Customer ID that owns the document.	Yes	"cust_12345"
id	string	Document unique ID to update.	Yes	"doc_abc123"

Headers

Key	Value	Required
Authorization	123	Yes
Content-Type	application/json	Yes
Accept	application/json	Yes

Request Body

All fields are optional - only include fields that need to be updated.

json

{
  "docType": "PASSPORT",
  "info": "Updated description - US passport for identity verification"
}

---

Request Fields

Document Update Fields

Field	Type	Required	Description	Example
docType	string	No	Updated document type/category.	"PASSPORT"
info	string	No	Updated description/notes about the document.	"Primary identification document"

---

Response (200 OK)

Returns the updated document metadata with all current information.

Response Fields

Document Object

Field	Type	Description	Example
id	string	Unique document identifier.	"doc_abc123"
customerId	string	Customer ID who owns the document.	"cust_12345"
fileName	string	Original filename.	"passport_scan.pdf"
size	integer	File size in bytes.	2048576
mime	string	MIME type of the document.	"application/pdf"
docType	string	Updated document type.	"PASSPORT"
info	string	Updated description/notes.	"Primary identification document"
isLock	boolean	Whether document is locked from modifications.	false
createAt	string	Original document creation timestamp.	"2024-05-15T10:30:00Z"
status	string	Current verification status.	"DST_SUBMITTED"

Example Response:

json

{
  "document": {
    "id": "doc_abc123",
    "customerId": "cust_12345",
    "fileName": "passport_scan.pdf",
    "size": 2048576,
    "mime": "application/pdf",
    "docType": "PASSPORT",
    "info": "Updated description - US passport for identity verification",
    "isLock": false,
    "createAt": "2024-05-15T10:30:00Z",
    "status": "DST_SUBMITTED"
  }
}

---

Field Details

Document Type Values

Document Type	Description	Common Use
PASSPORT	Passport document	Identity verification
DRIVERS_LICENCE_FRONT	Driver's license (front)	Identity verification
DRIVERS_LICENCE_BACK	Driver's license (back)	Identity verification
GOVERNMENT_ID_FRONT	Government ID (front)	Identity verification
GOVERNMENT_ID_BACK	Government ID (back)	Identity verification
UTILITY_BILL	Utility bill	Address verification
BANK_STATEMENT	Bank statement	Financial verification
INCORPORATION_DOCUMENTS	Business incorporation	Business verification
ARTICLES_OF_INCORPORATION	Articles of incorporation	Business verification
FINANCIAL_STATEMENT	Financial statements	Financial verification
LEASE_AGREEMENT	Lease agreement	Address verification
PAYSLIP	Payslip	Income verification
OPERATION_DOCUMENT	Operation-related	Transaction support
OTHER_1, OTHER_2, OTHER_3	Miscellaneous	Various purposes

Document Status Values

Status	Description	Meaning
DST_APPROVED	Document approved	Verified and accepted
DST_SUBMITTED	Document submitted	Awaiting review
DST_CHANGES_REQUESTED	Changes requested	Requires modifications
DST_REJECTED	Document rejected	Failed verification
DST_MISSING	Document missing	Required document not provided

---

Examples

Request

bash

curl -X POST 'https://stagep.tst-apidmndelss.com/v2/customer/cust_12345/file/doc_abc123' \
  -H 'Authorization: 123' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "docType": "PASSPORT",
    "info": "Updated description - US passport for identity verification"
  }'

Programming Language Examples

Python Update Example

python

import requests

def update_document(customer_id, document_id, auth_token, doc_type=None, info=None):
    url = f"https://stagep.tst-apidmndelss.com/v2/customer/{customer_id}/file/{document_id}"
    headers = {
        "Authorization": auth_token,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    
    payload = {}
    if doc_type:
        payload["docType"] = doc_type
    if info:
        payload["info"] = info
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 200:
        result = response.json()
        print("Document updated successfully")
        print(f"Document ID: {result['document']['id']}")
        print(f"New Type: {result['document']['docType']}")
        print(f"New Info: {result['document']['info']}")
        return result['document']
    else:
        print(f"Error updating document: {response.status_code} - {response.text}")
        return None

# Usage
updated_doc = update_document(
    customer_id="cust_12345",
    document_id="doc_pass123",
    auth_token="123",
    doc_type="PASSPORT",
    info="Primary identification - US passport"
)

JavaScript/Node.js Update Example

javascript

const https = require('https');

function updateDocument(customerId, documentId, authToken, updates) {
    return new Promise((resolve, reject) => {
        const postData = JSON.stringify(updates);
        
        const options = {
            hostname: 'stagep.tst-apidmndelss.com',
            path: `/v2/customer/${customerId}/file/${documentId}`,
            method: 'POST',
            headers: {
                'Authorization': authToken,
                'Content-Type': 'application/json',
                'Accept': 'application/json',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

        const request = https.request(options, (response) => {
            let data = '';

            response.on('data', (chunk) => {
                data += chunk;
            });

            response.on('end', () => {
                if (response.statusCode === 200) {
                    const result = JSON.parse(data);
                    console.log('Document updated successfully');
                    console.log('New Type:', result.document.docType);
                    console.log('New Info:', result.document.info);
                    resolve(result.document);
                } else {
                    reject(new Error(`HTTP ${response.statusCode}: ${data}`));
                }
            });
        });

        request.on('error', (error) => {
            reject(error);
        });

        request.write(postData);
        request.end();
    });
}

// Usage
updateDocument('cust_12345', 'doc_pass123', '123', {
    docType: 'PASSPORT',
    info: 'Primary identification - US passport'
})
.then(document => console.log('Update successful:', document.id))
.catch(error => console.error('Error:', error.message));

Java Update Example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public class DocumentUpdater {
    public static JSONObject updateDocument(String customerId, String documentId, 
                                          String authToken, String docType, String info) {
        try {
            String urlString = String.format(
                "https://stagep.tst-apidmndelss.com/v2/customer/%s/file/%s",
                customerId, documentId
            );
            
            URL url = new URL(urlString);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", authToken);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setRequestProperty("Accept", "application/json");
            connection.setDoOutput(true);
            
            // Create request body
            JSONObject requestBody = new JSONObject();
            if (docType != null) requestBody.put("docType", docType);
            if (info != null) requestBody.put("info", info);
            
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = requestBody.toString().getBytes("utf-8");
                os.write(input, 0, input.length);
            }
            
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(
                    new InputStreamReader(connection.getInputStream())
                );
                String inputLine;
                StringBuilder response = new StringBuilder();
                
                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();
                
                JSONObject result = new JSONObject(response.toString());
                System.out.println("Document updated successfully");
                return result.getJSONObject("document");
            } else {
                System.err.println("Error updating document: " + responseCode);
                return null;
            }
        } catch (Exception e) {
            System.err.println("Request error: " + e.getMessage());
            return null;
        }
    }
    
    // Usage
    public static void main(String[] args) {
        JSONObject updatedDoc = updateDocument(
            "cust_12345", "doc_pass123", "123", 
            "PASSPORT", "Primary identification - US passport"
        );
        
        if (updatedDoc != null) {
            System.out.println("Updated document: " + updatedDoc.toString());
        }
    }
}

Common Update Scenarios

1. Correct Document Type Example

Scenario: Fix incorrectly categorized document type.

Request:

json

{
  "docType": "BANK_STATEMENT",
  "info": "Q1 2024 bank statement for financial verification"
}

Response:

json

{
  "document": {
    "id": "doc_bank456",
    "customerId": "cust_12345",
    "fileName": "financial_document.pdf",
    "size": 2987654,
    "mime": "application/pdf",
    "docType": "BANK_STATEMENT",
    "info": "Q1 2024 bank statement for financial verification",
    "isLock": false,
    "createAt": "2024-05-20T11:30:00Z",
    "status": "DST_SUBMITTED"
  }
}

2. Add Detailed Description Example

Scenario: Add more context to a document description.

Request:

json

{
  "info": "California driver's license - front side, issued 2022, expires 2026"
}

Response:

json

{
  "document": {
    "id": "doc_dl789",
    "customerId": "cust_12345",
    "fileName": "drivers_license_front.png",
    "size": 2456789,
    "mime": "image/png",
    "docType": "DRIVERS_LICENCE_FRONT",
    "info": "California driver's license - front side, issued 2022, expires 2026",
    "isLock": true,
    "createAt": "2024-05-12T13:20:00Z",
    "status": "DST_APPROVED"
  }
}

3. Update Business Document Example

Scenario: Update business incorporation documents with specific details.

Request:

json

{
  "docType": "ARTICLES_OF_INCORPORATION",
  "info": "Delaware C-Corporation - filed January 2023, EIN: 12-3456789"
}

Response:

json

{
  "document": {
    "id": "doc_biz123",
    "customerId": "cust_biz999",
    "fileName": "incorporation_docs.pdf",
    "size": 5120480,
    "mime": "application/pdf",
    "docType": "ARTICLES_OF_INCORPORATION",
    "info": "Delaware C-Corporation - filed January 2023, EIN: 12-3456789",
    "isLock": true,
    "createAt": "2024-04-15T08:45:00Z",
    "status": "DST_APPROVED"
  }
}

4. Minimal Update Example

Scenario: Update only the description without changing document type.

Request:

json

{
  "info": "Updated: Address verification with current utility bill"
}

Response:

json

{
  "document": {
    "id": "doc_util456",
    "customerId": "cust_12345",
    "fileName": "electricity_bill.jpg",
    "size": 1856320,
    "mime": "image/jpeg",
    "docType": "UTILITY_BILL",
    "info": "Updated: Address verification with current utility bill",
    "isLock": false,
    "createAt": "2024-05-18T09:15:00Z",
    "status": "DST_SUBMITTED"
  }
}

Bulk Update Script Example

Python script for updating multiple documents:

python

import requests

def update_multiple_documents(customer_id, document_updates, auth_token):
    results = []
    for update in document_updates:
        try:
            url = f"https://stagep.tst-apidmndelss.com/v2/customer/{customer_id}/file/{update['document_id']}"
            headers = {
                "Authorization": auth_token,
                "Content-Type": "application/json",
                "Accept": "application/json"
            }
            
            payload = {}
            if 'doc_type' in update:
                payload['docType'] = update['doc_type']
            if 'info' in update:
                payload['info'] = update['info']
            
            response = requests.post(url, headers=headers, json=payload)
            success = response.status_code == 200
            
            results.append({
                'document_id': update['document_id'],
                'success': success,
                'message': response.json().get('message', '') if success else f"HTTP {response.status_code}"
            })
            
            print(f"Document {update['document_id']}: {'Success' if success else 'Failed'}")
            
        except Exception as e:
            results.append({
                'document_id': update['document_id'],
                'success': False,
                'message': str(e)
            })
            print(f"Document {update['document_id']}: Error - {e}")
    
    return results

# Usage
updates = [
    {
        'document_id': 'doc_123',
        'doc_type': 'PASSPORT',
        'info': 'US passport - primary identification'
    },
    {
        'document_id': 'doc_456',
        'info': 'Updated description for utility bill'
    }
]

results = update_multiple_documents("cust_12345", updates, "123")

# Print summary
success_count = sum(1 for r in results if r['success'])
print(f"\nSummary: {success_count}/{len(results)} documents updated successfully")

---

Error Responses

1. Document Not Found:

   json

   {
     "error": "Document not found: doc_99999"
   }

2. Customer Not Found:

   json

   {
     "error": "Customer not found: cust_99999"
   }

3. Unauthorized:

   json

   {
     "error": "Unauthorized"
   }

4. Document Locked:

   json

   {
     "error": "Cannot update locked document"
   }

5. Invalid Document Type:

   json

   {
     "error": "Invalid document type: INVALID_TYPE"
   }

---

Notes

• Partial Updates: Only include fields that need to be changed
• Locked Documents: Documents with isLock: true cannot be updated
• Status Impact: Updating document metadata may affect verification status
• Audit Trail: Document updates are typically logged for compliance
• File Content: This endpoint only updates metadata, not the actual file content

Restrictions:

• ❌ Cannot update locked documents (isLock: true)
• ❌ Cannot change the actual file content (use upload for replacement)
• ❌ Cannot modify fileName, size, mime, or createAt fields
• ✅ Can update docType and info fields for unlocked documents
• ✅ Can update documents with any status except when locked

Best Practices:

1. Verify Before Update: Check document status and lock status before updating
2. Clear Descriptions: Use descriptive info fields for better document management
3. Consistent Categorization: Use appropriate document types for compliance
4. Error Handling: Handle all possible error responses gracefully
5. User Confirmation: Implement confirmation for significant metadata changes