Skip to main content

Get Document Details API

The get-document-details endpoint allows you to retrieve detailed information about a specific document by its document_id. The response includes the document information along with associated plans.

Endpoint​

POST /get-document-details

Authentication​

This endpoint requires authentication using the access token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {access_token}

Request Headers​

HeaderRequiredDescription
AuthorizationYesBearer access_token from generate-client-auth-token
Content-TypeYesMust be application/json

Request Body​

{
  document_id: string;  // Required: Document identifier
}

Request Parameters​

document_id (required)​

  • Type: string
  • Description: Unique identifier for the document
  • Example: "doc-123" or "550e8400-e29b-41d4-a716-446655440000"

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: {
    document_id: string;           // Unique document identifier
    document_name: string;         // Document name
    document_description?: string;  // Document description
    document_type?: string;        // Document type (PDF, DOCX, TXT, IMG, OTHER)
    document_priority?: string;     // Document priority
    collection_id: string;          // Collection identifier
    document_file_path?: string;    // File path (if file-based)
    document_url?: string;          // Document URL (if URL-based)
    document_tags?: string[];       // Array of tags
    created_at: string;             // ISO timestamp
    updated_at: string;             // ISO timestamp
    collection_name?: string;       // Collection name
    associated_plans?: {           // Associated plans
      plan_id: string;
      plan_name: string;
      color: string;
    }[];
  };
  message: "OKAY";
}

Response Fields​

document_id​

  • Type: string
  • Description: Unique identifier for the document

document_name​

  • Type: string
  • Description: Name of the document

document_description​

  • Type: string (optional)
  • Description: Description of the document

document_type​

  • Type: string (optional)
  • Description: Type of document
  • Possible Values: "PDF", "DOCX", "TXT", "IMG", "OTHER"

collection_id​

  • Type: string
  • Description: Identifier of the collection/group this document belongs to

document_file_path​

  • Type: string (optional)
  • Description: File path for file-based documents

document_url​

  • Type: string (optional)
  • Description: URL for URL-based documents

associated_plans​

  • Type: array (optional)
  • Description: Array of plans associated with this document
  • Fields:
    • plan_id: Unique identifier for the plan
    • plan_name: Name of the plan
    • color: Color code for the plan

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Document ID is required";
}

Unauthorized (403)​

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

  • Missing or invalid Authorization header
  • Expired or invalid access token

Not Found (437)​

{
  statusCode: 437;
  data: {
  }
  message: "Document not found";
}

Causes:

  • Document with the provided document_id does not exist
  • Invalid document_id provided

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "Failed to fetch document";
}

Example Requests​

Example 1: Get Document Details​

This example shows the complete flow from authentication to retrieving document details:

# Step 1: Generate access token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Get document details using the access token
curl -X POST https://api.example.com/get-document-details \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "document_id": "doc-abc-123-def-456"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "document_id": "doc-abc-123-def-456",
    "document_name": "My Document",
    "document_description": "This is my document",
    "document_type": "PDF",
    "document_priority": "normal",
    "collection_id": "collection-123",
    "document_file_path": "documents/my-document.pdf",
    "document_tags": ["important", "reference"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "collection_name": "My Collection",
    "associated_plans": [
      {
        "plan_id": "plan-123",
        "plan_name": "Basic Plan",
        "color": "#FF5733"
      }
    ]
  },
  "message": "OKAY"
}

Behavior Notes​

Associated Plans​

  • The response includes all plans associated with the document
  • If no plans are associated, the associated_plans array will be empty or omitted
  • Plan information includes plan ID, name, and color

Collection Information​

  • The response includes the collection name along with the collection ID
  • This provides context about which collection the document belongs to

Response Format​

  • All timestamps are in ISO 8601 format
  • Associated plans are included as nested arrays
  • The response structure matches the document structure from the database