Skip to main content

Sync Group API

The sync-group endpoint allows you to create, update, or delete groups (collections). This endpoint automatically handles group creation, updates, and deletion based on the provided parameters.

Endpoint​

POST /sync-group

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
domainYesThe domain/group_name identifier for your tenant
AuthorizationYesBearer access_token from generate-client-auth-token
Content-TypeYesMust be application/json

Request Body​

{
  group_id?: string;           // Optional: Group identifier (required for updates/deletes)
  group_name?: string;         // Required for create: Name of the group
  group_description?: string;  // Optional: Description of the group
  is_delete?: boolean;         // Optional: Set to true to delete the group
  // ... other optional fields
}

Request Parameters​

group_id (optional)​

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

group_name (required for create)​

  • Type: string
  • Description: Name of the group/collection
  • Example: "My Group"

group_description (optional)​

  • Type: string
  • Description: Description of the group
  • Example: "This is a description of my group"

is_delete (optional)​

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

Success Response​

Creating a Group​

Status Code: 200

{
  statusCode: 200;
  data: {
    group_id: string;           // Unique group identifier
    group_name: string;         // Group name
    group_description?: string; // Group description (if provided)
    created_at: string;         // ISO timestamp
    updated_at: string;         // ISO timestamp
    // ... other group fields
  };
  message: "OKAY";
}

Updating a Group​

Status Code: 200

{
  statusCode: 200;
  data: {
    group_id: string;           // Unique group identifier
    group_name: string;         // Updated group name
    group_description?: string; // Updated group description
    created_at: string;         // ISO timestamp
    updated_at: string;         // ISO timestamp
    // ... other group fields
  };
  message: "OKAY";
}

Deleting a Group​

Status Code: 200

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

Error Responses​

Missing Required Fields (435)​

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

Unauthorized (403)​

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

Causes:

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

Not Found (437)​

{
  statusCode: 437;
  data: {
  }
  message: "ENTRY_NOT_FOUND";
}

Causes:

  • Attempting to update or delete a group that doesn't exist
  • Invalid group_id provided

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "SERVER_FAULT";
}

Example Requests​

Example 1: Create a New Group​

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

# Step 1: Generate auth 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 group using the auth token
curl -X POST https://api.example.com/sync-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "domain: my-domain" \
  -d '{
    "group_name": "My New Group",
    "group_description": "This is a description of my group"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "group_id": "group-abc-123-def-456",
    "group_name": "My New Group",
    "group_description": "This is a description of my group",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "OKAY"
}

Example 2: Update a Group​

curl -X POST https://api.example.com/sync-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "domain: my-domain" \
  -d '{
    "group_id": "group-abc-123-def-456",
    "group_name": "Updated Group Name",
    "group_description": "Updated description"
  }'

Example 3: Delete a Group​

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

Try It Out

API Configuration

Authentication

Token obtained from the generate-client-auth-token endpoint
The domain/group_name identifier for your tenant

Group Details

Optional. Required for updates and deletes. If not provided for create, a new group ID will be generated
When checked, group_id is required and the group will be deleted

Group Information

Name of the group (required for create)
Optional description of the group

Request Preview

{}

Behavior Notes​

Group Creation​

  • If group_id is not provided, a new group is created
  • group_name is required for group creation
  • A unique group_id is automatically generated if not provided

Group Updates​

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

Group Deletion​

  • When is_delete is true, group_id must be provided
  • Deletion is permanent and cannot be undone
  • All associated data with the group may be deleted