Campaigns Endpoints

The Campaigns API provides endpoints for managing access review campaigns, including creation, lifecycle management, and approval workflows.

Base URL

All endpoints are relative to /api/v1/campaigns.

---

List Campaigns

Retrieve a paginated list of campaigns.

GET /api/v1/campaigns

Query Parameters

Parameter	Type	Description
status	string	Filter by status (draft, active, completed)
type	string	Filter by campaign type
limit	number	Number of items to return
after	string	Cursor for pagination

Response

{
  "campaigns": [
    {
      "id": "camp-123",
      "name": "Q1 Access Review",
      "status": "active",
      "type": "periodic",
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z",
      "created_at": "2023-12-15T10:30:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "cursor-token"
  }
}

---

Get Campaign

Retrieve details for a specific campaign.

GET /api/v1/campaigns/{id}

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

Returns the complete campaign object with configuration and status.

---

Create Campaign

Create a new access review campaign.

POST /api/v1/campaigns

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "name": "Q2 Access Review",
  "description": "Quarterly access certification",
  "type": "periodic",
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z",
  "scope": {
    "applications": ["app-123", "app-456"],
    "account_types": ["user", "service"]
  }
}

Response

Returns the created campaign object.

---

Update Campaign

Update an existing campaign.

PUT /api/v1/campaigns/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Request Body

Include only the fields to update.

Response

Returns the updated campaign object.

---

Delete Campaign

Delete a campaign.

DELETE /api/v1/campaigns/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

Returns 204 No Content on success.

---

Create Campaign from Template

Create a new campaign based on an existing template.

POST /api/v1/campaigns/from-template/{templateId}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
templateId	string	Template campaign ID

Request Body

{
  "name": "New Campaign from Template",
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z"
}

Response

Returns the created campaign object.

---

Start Campaign

Start a draft campaign to begin the review process.

POST /api/v1/campaigns/{id}/start

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

{
  "status": "queued",
  "message": "Campaign start initiated"
}

---

Complete Campaign

Mark a campaign as completed.

POST /api/v1/campaigns/{id}/complete

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

Returns the completed campaign object.

---

Get Campaign Approvals

Retrieve approval items for a campaign.

GET /api/v1/campaigns/{id}/approvals

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Query Parameters

Parameter	Type	Description
status	string	Filter by status (pending, approved, rejected)

Response

{
  "approvals": [
    {
      "account_id": "acc-123",
      "account_name": "john.doe",
      "status": "pending",
      "reviewer": "manager@company.com"
    }
  ]
}

---

Get Approval Counts

Get approval counts grouped by status.

GET /api/v1/campaigns/{id}/approvals/counts

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

{
  "pending": 50,
  "approved": 120,
  "rejected": 15,
  "flagged": 5
}

---

Approve/Reject Account

Submit an approval decision for an account.

POST /api/v1/campaigns/{id}/approvals/{accountId}

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Request Body

{
  "decision": "approved",
  "comment": "Access verified and appropriate"
}

Response

Returns the updated approval object.

---

Batch Approve

Submit approval decisions for multiple accounts.

POST /api/v1/campaigns/{id}/approvals/batch

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Request Body

{
  "account_ids": ["acc-123", "acc-456"],
  "decision": "approved",
  "comment": "Bulk approval for standard access"
}

Response

Returns list of updated approvals.

---

Undo Approval

Revert an approval decision back to pending within 30 seconds of the decision.

POST /api/v1/campaigns/{id}/approvals/{accountId}/undo

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response

Returns the approval reverted to pending status.

Undo Window

Undo is only available within 30 seconds of making the decision. After this window, the endpoint returns a 409 Conflict error.

---

Query Builder

Get Query Fields

Return the available fields per entity type for building campaign queries.

GET /api/v1/campaigns/query/fields

Response (200):

{
  "account": [
    { "field": "department", "label": "Department", "type": "string", "operators": ["equals", "not_equals", "contains", "is_null", "is_not_null"] },
    { "field": "mfa_status", "label": "MFA Status", "type": "boolean", "operators": ["equals"] }
  ],
  "owner": [
    { "field": "title", "label": "Title", "type": "string", "operators": ["equals", "contains"] }
  ],
  "group": [
    { "field": "name", "label": "Group Name", "type": "string", "operators": ["equals", "contains", "starts_with"] }
  ],
  "role": [
    { "field": "name", "label": "Role Name", "type": "string", "operators": ["equals", "contains"] }
  ],
  "classification": [
    { "field": "name", "label": "Classification", "type": "string", "operators": ["equals"] }
  ]
}

---

Test Campaign Query

Evaluate a query definition and return the matching account count with up to 5 sample accounts.

POST /api/v1/campaigns/query/test

Request body:

{
  "inclusion_filters": [
    { "entity": "account", "field": "department", "operator": "equals", "value": "Finance" },
    { "entity": "group", "field": "name", "operator": "contains", "value": "Admins" }
  ],
  "exclusion_filters": [
    { "entity": "account", "field": "account_type", "operator": "equals", "value": "service" }
  ]
}

Query logic:

• Inclusion filters across the same entity use AND within that entity, then intersect across entity types.
• Exclusion filters use OR — any match removes the account.

Response (200):

{
  "count": 42,
  "sample_accounts": [
    { "id": "acc-1", "account_name": "jdoe", "email": "jdoe@example.com", "status": "active", "department": "Finance" }
  ]
}

Field descriptions:

Field	Type	Description
inclusion_filters	array	Conditions that select accounts. At least one required.
exclusion_filters	array	Conditions that remove accounts from the inclusion set. Optional.
Each condition entity	string	account, owner, group, role, or classification
Each condition field	string	Field name from /query/fields
Each condition operator	string	One of: equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, greater_equal, less_equal, is_null, is_not_null
Each condition value	any	Value to compare against. Omit for is_null/is_not_null.

TIP

A query with no inclusion filters returns an empty result. Exclusion filters are ignored if there are no inclusion filters.

---

Get Review Items

Get enriched review items with risk data.

GET /api/v1/campaigns/{id}/review-items

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Query Parameters

Parameter	Type	Description
status	string	Filter by approval status
risk	string	Filter by risk level
search	string	Search by account name
sort	string	Sort field
limit	number	Number of items
after	string	Cursor for pagination

Response

Paginated list of review items with account details and risk scores.

---

Get Single Review Item

Retrieve a fully-enriched review item for the account detail panel.

GET /api/v1/campaigns/{id}/review-items/{accountId}

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response

Returns the full enriched review item including risk score, AI recommendation, owner context, and account details.

---

Get Review Item Entitlements

Retrieve group memberships and application role assignments for an account under review.

GET /api/v1/campaigns/{id}/review-items/{accountId}/entitlements

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response (200)

{
  "groups": [
    { "id": "grp-1", "name": "Domain Admins", "is_high_privilege": true },
    { "id": "grp-2", "name": "Engineering", "is_high_privilege": false }
  ],
  "roles": [
    { "id": "role-1", "name": "AppAdmin", "platform": "SalesforceApp", "data_source_name": "Salesforce Prod" }
  ]
}

Response fields:

Field	Type	Description
groups[].id	string	Group identifier
groups[].name	string	Group display name
groups[].is_high_privilege	boolean	true if the group has elevated privileges
roles[].id	string	Role identifier
roles[].name	string	Role display name
roles[].platform	string	Platform the role belongs to
roles[].data_source_name	string	Data source the role was synced from

---

Get Review Item History

Retrieve previous review decisions for an account across past campaigns.

GET /api/v1/campaigns/{id}/review-items/{accountId}/history

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response (200)

{
  "decisions": [
    {
      "campaign_id": "camp-100",
      "campaign_name": "Q4 2025 Access Review",
      "decision": "APPROVED",
      "reviewed_at": "2025-12-10T14:22:00Z",
      "reviewed_by": "manager@example.com",
      "comments": "Access verified and appropriate"
    },
    {
      "campaign_id": "camp-099",
      "campaign_name": "Q3 2025 Access Review",
      "decision": "FLAGGED",
      "reviewed_at": "2025-09-15T09:00:00Z",
      "reviewed_by": "manager@example.com",
      "comments": "Needs followup on elevated group"
    }
  ]
}

Decision values:

Value	Description
APPROVED	Access was confirmed as appropriate
REJECTED	Access was denied and should be removed
REVOKED	Access entitlements were explicitly revoked
FLAGGED	Flagged for further review or escalation

---

AI Recommendations

Get AI Recommendation for Account

Get the stored AI recommendation for a specific account in a campaign.

GET /api/v1/campaigns/{id}/approvals/{accountId}/ai-recommendation

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response

{
  "decision": "approve",
  "confidence": 85,
  "reason": "Account access aligns with role requirements and shows normal usage patterns",
  "primary_factors": [
    "Role-appropriate access",
    "Recent activity within normal range",
    "MFA enabled"
  ],
  "risk_indicators": [],
  "data_gaps": [
    "Manager approval history not available"
  ],
  "generated_at": "2024-01-15T10:30:00Z"
}

Get Batch Groups

Get AI-generated batch groups for efficient bulk review.

GET /api/v1/campaigns/{id}/batch-groups

Path Parameters

Parameter	Type	Description
id	string	Campaign ID

Response

{
  "batch_groups": [
    {
      "id": "batch-123",
      "name": "Standard Developers - Engineering",
      "description": "Standard developer accounts with typical access patterns",
      "risk_level": "low",
      "account_count": 45,
      "ai_analysis": {
        "title": "Standard Engineering Access",
        "traits": ["Developer role", "Active MFA", "Recent activity"],
        "summary": ["All accounts show normal usage", "No policy violations", "Consistent with role"],
        "recommendation": "approve",
        "confidence": 92
      },
      "account_ids": ["acc-1", "acc-2", "..."]
    }
  ]
}

Review Batch Group

Apply a decision to all accounts in a batch group.

POST /api/v1/campaigns/{id}/batch-groups/{batchId}/review

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
batchId	string	Batch group ID

Request Body

{
  "decision": "approved",
  "comment": "Batch approval for standard access"
}

Response

Returns list of updated approvals for all accounts in the batch.

---

Risk Assessment

Get Risk Assessment for Account

Get detailed risk assessment including risk factors and policy checks.

GET /api/v1/campaigns/{id}/approvals/{accountId}/risk-assessment

Path Parameters

Parameter	Type	Description
id	string	Campaign ID
accountId	string	Account ID

Response

{
  "score": 75,
  "level": "high",
  "triggered_factors": [
    {
      "name": "Privileged Account",
      "description": "Account has administrative privileges",
      "weight": 30,
      "severity": "high"
    },
    {
      "name": "Stale Account",
      "description": "No login activity in 90+ days",
      "weight": 25,
      "severity": "medium"
    }
  ],
  "passing_factors": [
    {
      "name": "MFA Enabled",
      "description": "Multi-factor authentication is configured",
      "weight": 0,
      "severity": "low"
    }
  ]
}

Get Policy Checks for Account

Get policy check results for an account in a campaign.

GET /api/v1/campaigns/{id}/approvals/{accountId}/policy-checks

Response

{
  "policy_checks": [
    {
      "policy_id": "pol-123",
      "policy_name": "Require MFA for Privileged Accounts",
      "status": "PASS",
      "message": "Account has MFA enabled"
    },
    {
      "policy_id": "pol-456",
      "policy_name": "Maximum Inactive Period",
      "status": "FAIL",
      "message": "Account inactive for 120 days, exceeds 90 day limit"
    }
  ]
}

---

Rule Evaluation Jobs

Test Campaign Rule

Test a campaign rule against current data without creating a campaign.

POST /api/v1/campaigns/rules/test

Request Body

{
  "rule_type": "account",
  "condition": "account.privileged = true AND account.mfa_enabled = false"
}

Response

{
  "job_id": "job-123",
  "status": "pending",
  "job_type": "test"
}

Get Rule Evaluation Job Status

Get the status and results of a rule evaluation job.

GET /api/v1/campaigns/rules/jobs/{jobId}

Path Parameters

Parameter	Type	Description
jobId	string	Evaluation job ID

Response

{
  "id": "job-123",
  "job_type": "test",
  "status": "completed",
  "total_entities": 1500,
  "processed_entities": 1500,
  "percent_complete": 100,
  "total_matches": 23,
  "sample_matches": [
    {
      "account_id": "acc-1",
      "account_name": "admin.user",
      "matched": true
    }
  ],
  "is_valid": true,
  "completed_at": "2024-01-15T10:35:00Z"
}

Campaign Rule Evaluation

Evaluate campaign rules for an active campaign (applies automated decisions).

POST /api/v1/campaigns/{id}/rules/evaluate

Triggers asynchronous rule evaluation. Returns job info for progress tracking.

Response

{
  "job_id": "job-456",
  "campaign_id": "camp-123",
  "status": "pending",
  "job_type": "campaign"
}

---

Campaign Rules

Get Assigned Rules

GET /api/v1/campaigns/{id}/rules

Assign Rules to Campaign

POST /api/v1/campaigns/{id}/rules

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "rule_ids": ["rule-123", "rule-456"]
}

Update Rule Status in Campaign

PUT /api/v1/campaigns/{id}/rules/{ruleId}

Request Body

{
  "enabled": true
}

Evaluate Campaign Rules

POST /api/v1/campaigns/{id}/rules/evaluate

Triggers asynchronous rule evaluation. Returns job info for progress tracking.

---

Campaign Policies

Get Policies for Campaign

GET /api/v1/campaigns/{id}/policies

Apply Policy to Campaign

POST /api/v1/campaigns/{id}/policies/{policyId}

Query Parameters

Parameter	Type	Description
threshold	number	Policy threshold (optional)

Remove Policy from Campaign

DELETE /api/v1/campaigns/{id}/policies/{policyId}

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Campaign does not exist
409	Conflict - Invalid state transition
500	Internal Server Error

---

Related Topics

• Campaign Rules API - Rule management endpoints
• Policies API - Policy management endpoints
• API Reference - Complete API index