Skip to main content

Get Plans API

The get-plans endpoint allows you to retrieve a list of plans. You can optionally filter plans by collection_id to get plans for a specific collection.

Endpoint​

POST /get-plans

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​

{
  collection_id?: string;  // Optional: Filter plans by collection ID
}

Request Parameters​

collection_id (optional)​

  • Type: string
  • Description: Filter plans by collection/group identifier. If not provided, all plans are returned
  • Example: "collection-123"

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;
      }[];
    },
    // ... more plans
  ];
  message: "OKAY";
}

Response Fields​

Each plan in the array contains:

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​

Unauthorized (403)​

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

Causes:

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

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "An unexpected error occurred. Please try again.";
}

Example Requests​

Example 1: Get All Plans​

This example shows retrieving all plans:

# 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 all plans using the access token
curl -X POST https://api.example.com/get-plans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{}'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "plan_id": "plan-abc-123",
      "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": [],
      "associated_supplemental_benefits": []
    },
    {
      "plan_id": "plan-def-456",
      "plan_name": "Premium Plan",
      "description": "This is a premium plan",
      "collection_id": "collection-123",
      "color": "#33FF57",
      "created_at": "2024-01-14T09:20:00Z",
      "updated_at": "2024-01-14T09:20:00Z",
      "associated_documents": [
        {
          "document_id": "doc-123",
          "document_name": "Plan Document 1"
        }
      ],
      "associated_supplemental_benefits": []
    }
  ],
  "message": "OKAY"
}

Example 2: Get Plans by Collection​

This example shows retrieving plans filtered by collection ID:

curl -X POST https://api.example.com/get-plans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "collection_id": "collection-123"
  }'

Behavior Notes​

Filtering​

  • If collection_id is provided, only plans for that collection are returned
  • If collection_id is not provided, all plans are returned
  • Empty arrays are returned if no plans match the filter criteria

Associated Data​

  • Each plan in the response includes 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 Ordering​

  • Plans are returned in an unspecified order
  • You may need to sort them client-side if a specific order is required

Empty Results​

  • If no plans exist (or match the filter), an empty array [] is returned
  • This is not an error condition