Skip to main content

Get Plan Details API

The get-plan-details endpoint allows you to retrieve detailed information about a specific plan by its plan_id. The response includes the plan information along with associated documents and supplemental benefits.

Endpoint​

POST /get-plan-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​

{
  plan_id: string;  // Required: Plan identifier
}

Request Parameters​

plan_id (required)​

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

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: {
    plan_id: string;           // Unique plan identifier
    plan_name: string;         // Plan name
    description: string;       // Plan description
    collection_id: string;     // Collection identifier
    color: string;             // Plan color
    created_at: string;         // ISO timestamp
    updated_at: string;         // ISO timestamp
    associated_documents?: {   // Associated documents
      document_id: string;
      document_name: string;
    }[];
    associated_supplemental_benefits?: {  // Associated supplemental benefits
      supplemental_benefit_id: string;
      benefit_name: string;
    }[];
  };
  message: "OKAY";
}

Response Fields​

plan_id​

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

plan_name​

  • Type: string
  • Description: Name of the plan

description​

  • Type: string
  • Description: Description of the plan

collection_id​

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

color​

  • Type: string
  • Description: Color code for the plan

associated_documents​

  • Type: array (optional)
  • Description: Array of documents associated with this plan
  • Fields:
    • document_id: Unique identifier for the document
    • document_name: Name of the document

associated_supplemental_benefits​

  • Type: array (optional)
  • Description: Array of supplemental benefits associated with this plan
  • Fields:
    • supplemental_benefit_id: Unique identifier for the benefit
    • benefit_name: Name of the benefit

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: plan_id";
}

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: "Plan not found";
}

Causes:

  • Plan with the provided plan_id does not exist
  • Invalid plan_id provided

Server Fault (500)​

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

Example Requests​

Example 1: Get Plan Details​

This example shows the complete flow from authentication to retrieving plan 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 plan details using the access token
curl -X POST https://api.example.com/get-plan-details \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "plan_id": "plan-abc-123-def-456"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "plan_id": "plan-abc-123-def-456",
    "plan_name": "Basic Plan",
    "description": "This is a basic plan",
    "collection_id": "collection-123",
    "color": "#FF5733",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "associated_documents": [
      {
        "document_id": "doc-123",
        "document_name": "Plan Document 1"
      },
      {
        "document_id": "doc-456",
        "document_name": "Plan Document 2"
      }
    ],
    "associated_supplemental_benefits": [
      {
        "supplemental_benefit_id": "benefit-123",
        "benefit_name": "Dental Coverage"
      }
    ]
  },
  "message": "OKAY"
}

Behavior Notes​

Associated Data​

  • The response includes all associated documents and supplemental benefits
  • If no documents or benefits are associated, the arrays will be empty or omitted
  • The data is fetched synchronously and included in the response

Response Format​

  • All timestamps are in ISO 8601 format
  • Associated documents and benefits are included as nested arrays
  • The response structure matches the plan structure from the database