> ## Documentation Index > Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # SetMonitoredCompanyState > Transitions an account-scoped monitored company between active, paused, and removed states. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes. ## OpenAPI ````yaml /api/worldmonitor.openapi.yaml post /api/company-monitoring/v1/set-monitored-company-state openapi: 3.1.0 info: title: WorldMonitor API description: >- Unified OpenAPI bundle spanning all WorldMonitor services. Versioning and deprecation policy: https://www.worldmonitor.app/docs/api-versioning contact: name: WorldMonitor email: support@worldmonitor.app version: 1.0.0 servers: - url: https://api.worldmonitor.app security: - WorldMonitorKey: [] - ApiKeyHeader: [] paths: /api/company-monitoring/v1/set-monitored-company-state: post: tags: - CompanyMonitoringService summary: SetMonitoredCompanyState description: >- Transitions an account-scoped monitored company between active, paused, and removed states. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes. operationId: SetMonitoredCompanyState parameters: - name: Idempotency-Key in: header description: >- Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours. required: false example: 4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34 schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x21-\x7E]{1,255}$ requestBody: content: application/json: example: companyId: cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV targetLifecycle: MONITORED_COMPANY_LIFECYCLE_ACTIVE schema: $ref: >- #/components/schemas/worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateRequest required: true responses: '200': description: Successful response headers: Idempotency-Key: schema: type: string description: >- The idempotency key echoed from the request. Present only when the client opted into idempotency. Idempotent-Replayed: schema: type: boolean description: >- true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency. content: application/json: example: company: canonicalUrl: https://example.com/worldmonitor claims: - allowedUses: - COMPANY_CLAIM_ALLOWED_USE_DISCOVERY claimId: cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV expiresAt: '2026-01-15T12:00:00Z' provenance: example trustState: COMPANY_CLAIM_TRUST_STATE_DECLARED companyId: cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV coverage: COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN createdAt: '2026-01-15T12:00:00Z' snapshotRequired: true schema: $ref: >- #/components/schemas/worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateResponse '400': description: >- Validation error, invalid Idempotency-Key header, or malformed JSON request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - error - message properties: error: type: string message: type: string - $ref: '#/components/schemas/InvalidRequestBodyError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: >- Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '409': description: A request with this Idempotency-Key is still being processed headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. Retry-After: schema: type: string description: Seconds to wait before retrying the in-flight request. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string '422': description: The Idempotency-Key was already used with a different request body headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' '503': description: >- Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: >- Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: >- Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: >- Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: schemas: worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateRequest: type: object properties: companyId: type: string pattern: ^cm_company_[0-9A-HJKMNP-TV-Z]{26}$ targetLifecycle: type: string enum: - MONITORED_COMPANY_LIFECYCLE_UNSPECIFIED - MONITORED_COMPANY_LIFECYCLE_ACTIVE - MONITORED_COMPANY_LIFECYCLE_PAUSED - MONITORED_COMPANY_LIFECYCLE_REMOVED description: MonitoredCompanyLifecycle is the customer-visible company lifecycle. required: - companyId - targetLifecycle worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateResponse: type: object properties: company: $ref: >- #/components/schemas/worldmonitor_company_monitoring_v1_MonitoredCompany snapshotRequired: type: boolean ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: >- ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: >- Returned when the API key is missing, malformed, or lacks current API access. ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. code: type: string enum: - subscription_lapsed description: >- Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header). requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: >- Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: >- Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error BillingVerificationError: type: object description: >- Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After. properties: error: type: string description: Human-readable billing-verification failure reason. code: type: string enum: - renewal_verification_pending - renewal_verification_failed - entitlement_verification_unavailable description: >- Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header. requiredTier: type: integer format: int32 description: >- Minimum entitlement tier required for this endpoint, when the denial came from a tier gate. required: - error - code GatewayError: type: object description: >- Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error worldmonitor_company_monitoring_v1_MonitoredCompany: type: object properties: companyId: type: string pattern: ^cm_company_[0-9A-HJKMNP-TV-Z]{26}$ description: Stable WorldMonitor logical ID; never a storage-layer document ID. name: type: string domicileCountry: type: string enum: - DOMICILE_COUNTRY_UNSPECIFIED - DOMICILE_COUNTRY_US - DOMICILE_COUNTRY_GB description: >- DomicileCountry is the closed v1 company-domicile set. Event geography is unrestricted. lifecycle: type: string enum: - MONITORED_COMPANY_LIFECYCLE_UNSPECIFIED - MONITORED_COMPANY_LIFECYCLE_ACTIVE - MONITORED_COMPANY_LIFECYCLE_PAUSED - MONITORED_COMPANY_LIFECYCLE_REMOVED description: MonitoredCompanyLifecycle is the customer-visible company lifecycle. claims: type: array items: $ref: >- #/components/schemas/worldmonitor_company_monitoring_v1_CompanyClaim maxItems: 81 coverage: type: string enum: - COMPANY_COVERAGE_STATE_UNSPECIFIED - COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN - COMPANY_COVERAGE_STATE_ADEQUATE - COMPANY_COVERAGE_STATE_PARTIAL - COMPANY_COVERAGE_STATE_STALE - COMPANY_COVERAGE_STATE_UNAVAILABLE - COMPANY_COVERAGE_STATE_NEEDS_CONFIRMATION description: >- CompanyCoverageState reports source and assessment readiness, not event count. observation: type: string enum: - COMPANY_OBSERVATION_STATE_UNSPECIFIED - COMPANY_OBSERVATION_STATE_EVENTS_OBSERVED - COMPANY_OBSERVATION_STATE_NO_EVENTS_OBSERVED - COMPANY_OBSERVATION_STATE_UNKNOWN description: CompanyObservationState is independent of coverage completeness. createdAt: type: string updatedAt: type: string canonicalUrl: type: string description: MonitoredCompany is a compact account-scoped portfolio row. FieldViolation: type: object properties: field: type: string description: >- The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: >- Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. worldmonitor_company_monitoring_v1_CompanyClaim: type: object properties: claimId: type: string pattern: ^cm_claim_[0-9A-HJKMNP-TV-Z]{26}$ description: Stable WorldMonitor logical ID; never a storage-layer document ID. type: type: string enum: - COMPANY_CLAIM_TYPE_UNSPECIFIED - COMPANY_CLAIM_TYPE_ALIAS - COMPANY_CLAIM_TYPE_DOMAIN - COMPANY_CLAIM_TYPE_LEGAL_IDENTIFIER - COMPANY_CLAIM_TYPE_X_ACCOUNT_ID - COMPANY_CLAIM_TYPE_X_HANDLE - COMPANY_CLAIM_TYPE_LOCATION - COMPANY_CLAIM_TYPE_CUSTOMER_REFERENCE description: CompanyClaimType identifies one independently trusted company claim. value: type: string provenance: type: string trustState: type: string enum: - COMPANY_CLAIM_TRUST_STATE_UNSPECIFIED - COMPANY_CLAIM_TRUST_STATE_DECLARED - COMPANY_CLAIM_TRUST_STATE_VERIFIED - COMPANY_CLAIM_TRUST_STATE_EXPIRED - COMPANY_CLAIM_TRUST_STATE_REJECTED description: >- CompanyClaimTrustState is scoped to the individual claim, not the legal subject. allowedUses: type: array items: type: string enum: - COMPANY_CLAIM_ALLOWED_USE_UNSPECIFIED - COMPANY_CLAIM_ALLOWED_USE_DISCOVERY - COMPANY_CLAIM_ALLOWED_USE_ATTRIBUTION - COMPANY_CLAIM_ALLOWED_USE_PRIMARY_EVIDENCE description: CompanyClaimAllowedUse states what a claim may support. maxItems: 3 expiresAt: type: string description: CompanyClaim is one independently attributed and expiring claim. securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). ````