Skip to main content

Sync Plan API

The sync-plan endpoint allows you to create, update, or delete plans within a collection. This endpoint automatically handles plan creation, updates, and deletion based on the provided parameters.

Endpoint​

POST /sync-plan

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;           // Optional: Plan identifier (required for updates/deletes)
  plan_name?: string;         // Required for create: Name of the plan
  description?: string;        // Required for create: Description of the plan
  collection_id?: string;     // Required for create: Collection/group identifier
  color?: string;             // Required for create: Color code for the plan
  is_delete?: boolean;       // Optional: Set to true to delete the plan
}

Request Parameters​

plan_id (optional)​

  • Type: string
  • Description: Unique identifier for the plan. Required when updating or deleting a plan
  • Example: "plan-123" or "550e8400-e29b-41d4-a716-446655440000"

plan_name (required for create)​

  • Type: string
  • Description: Name of the plan
  • Example: "Basic Plan"

description (required for create)​

  • Type: string
  • Description: Description of the plan
  • Example: "This is a basic plan description"

collection_id (required for create)​

  • Type: string
  • Description: Identifier of the collection/group this plan belongs to
  • Example: "collection-123"

color (required for create)​

  • Type: string
  • Description: Color code for the plan (typically hex color code)
  • Example: "#FF5733" or "blue"

is_delete (optional)​

  • Type: boolean
  • Description: Set to true to delete the plan. When deleting, plan_id must be provided
  • Default: false

Success Response​

Creating a Plan​

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
  };
  message: "OKAY";
}

Updating a Plan​

Status Code: 200

{
  statusCode: 200;
  data: {
    plan_id: string;           // Unique plan identifier
    plan_name: string;         // Updated plan name
    description: string;        // Updated plan description
    collection_id: string;     // Collection identifier
    color: string;             // Updated plan color
    created_at: string;         // ISO timestamp
    updated_at: string;         // ISO timestamp
  };
  message: "OKAY";
}

Deleting a Plan​

Status Code: 200

{
  statusCode: 200;
  data: {
  }
  message: "OKAY";
}

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: plan_name, description, collection_id, color";
}

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:

  • Attempting to update or delete a plan that doesn't exist
  • Invalid plan_id provided

Server Fault (500)​

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

Example Requests​

Example 1: Create a New Plan​

This example shows the complete flow from authentication to plan creation:

# 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: Create plan using the access token
curl -X POST https://api.example.com/sync-plan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "plan_name": "Basic Plan",
    "description": "This is a basic plan",
    "collection_id": "collection-123",
    "color": "#FF5733"
  }'

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"
  },
  "message": "OKAY"
}

Example 2: Update a Plan​

curl -X POST https://api.example.com/sync-plan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "plan_id": "plan-abc-123-def-456",
    "plan_name": "Updated Plan Name",
    "description": "Updated description"
  }'

Example 3: Delete a Plan​

curl -X POST https://api.example.com/sync-plan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "is_delete": true,
    "plan_id": "plan-abc-123-def-456"
  }'

Behavior Notes​

Plan Creation​

  • If plan_id is not provided, a new plan is created
  • plan_name, description, collection_id, and color are required for plan creation
  • A unique plan_id is automatically generated if not provided

Plan Updates​

  • When plan_id is provided and is_delete is false or not set, the plan is updated
  • Only provided fields are updated; omitted fields remain unchanged
  • Updates happen synchronously

Plan Deletion​

  • When is_delete is true, plan_id must be provided
  • Deletion is permanent and cannot be undone
  • All associated documents and supplemental benefits are automatically removed