Skip to main content

Activate Service

In this guide, we will activate service for a monitorable after confirming all pre-activation requirements are complete.

Overview​

Creating a monitorable registers the entity, but service does not start until you activate it. Activation moves systemStatus from INACTIVE to ACTIVE (or FAMILIARIZATION when the jurisdiction requires a familiarization period). Until then, events cannot be created against the monitorable.

Activation is blocked until every requirement with stage: PRE_ACTIVATION is COMPLETE. Post-activation requirements such as PERMIT do not block activation — fulfill those after service is live. See Fulfill Requirements and Monitorable Lifecycle.

Getting Started​

You need a partner application with the following scopes:

  • monitorable:read — to retrieve the monitorable and inspect requirements
  • monitorable:write — to activate the monitorable

If you haven't created an application yet, see the Create Application guide.

Once you have your application credentials, use the Set Access Token button in the navbar to configure your access token for making API requests.

Check Readiness​

Retrieve the monitorable and confirm it is ready to activate:

cURLGET

Before calling activate, verify all of the following:

CheckExpected value
verificationStatusPENDING_REQUIREMENTS or VERIFIED
systemStatusINACTIVE
Pre-activation requirementsNo entry in requirements has both stage: PRE_ACTIVATION and status: INCOMPLETE

Example of a monitorable that is ready to activate:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "verificationStatus": "PENDING_REQUIREMENTS",
  "systemStatus": "INACTIVE",
  "requirements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "type": "NUMBER_OF_CONTACTS",
      "status": "COMPLETE",
      "stage": "PRE_ACTIVATION",
      "count": 1
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "type": "SUBSCRIPTION",
      "status": "COMPLETE",
      "stage": "PRE_ACTIVATION",
      "options": ["ANNUAL", "MONTHLY"]
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "type": "PERMIT",
      "status": "INCOMPLETE",
      "stage": "POST_ACTIVATION"
    }
  ]
}

The incomplete PERMIT requirement above does not block activation because its stage is POST_ACTIVATION.

Pre-Activation Requirements​

Common pre-activation requirement types:

TypeHow to fulfill
TERMSProvide terms (ipAddress and acceptedAt) when creating or updating the monitorable
NUMBER_OF_CONTACTSProvide enough contacts on create or update to meet the required count
SUBSCRIPTIONSet subscription to one of the values in the requirement options array — see Fulfill Requirements
Other jurisdiction requirementsWhen a requirement has stage: PRE_ACTIVATION, fulfill it before activation. Use Check Service Availability to discover requirements before create

If any PRE_ACTIVATION requirement is still INCOMPLETE, activate returns 400 with All pre-activation requirements must be complete before activation.

Activate the Monitorable​

Send a POST request to the /monitorables/:monitorableId/activate endpoint:

Path parameters

cURL command

cURLPOST
curl -X POST "/v1/monitorables/:monitorableId/activate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

On success, systemStatus becomes ACTIVE. When the jurisdiction requires a familiarization period, the effective status is FAMILIARIZATION until that period expires, then it transitions to ACTIVE automatically.

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "verificationStatus": "PENDING_REQUIREMENTS",
  "systemStatus": "ACTIVE",
  "subscription": "MONTHLY",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

See Activation with Familiarization Period for details on the familiarization flow.

Errors​

StatusWhen
400systemStatus is not INACTIVE — message includes Monitorable must have a system status of INACTIVE to be activated
400verificationStatus is not PENDING_REQUIREMENTS or VERIFIED — message includes Monitorable must have a verification status of PENDING_REQUIREMENTS or VERIFIED to be activated
400One or more pre-activation requirements are incomplete — message includes All pre-activation requirements must be complete before activation
404Monitorable not found for the authenticated partner

After Activation​

Post-activation requirements (for example PERMIT) remain incomplete until you fulfill them. Incomplete post-activation requirements can affect verification status and response handling — see Jurisdictions & Compliance and Fulfill Requirements.

Once service is active, you can create events for the monitorable. See Create Events.

Conclusion​

You've activated service for a monitorable. Events can now be created, and post-activation requirements can be fulfilled while service is live.

Next Steps​

Learn More​

API Reference​