Skip to main content

Fulfill Requirements

Fulfill Requirements

In this guide, we will learn how to identify and fulfil compliance requirements for a monitorable.

Overview​

When a monitorable is created, the platform evaluates the applicable compliance rules and generates requirements automatically. Each requirement stays INCOMPLETE until the necessary data is provided.

Common requirement types include PERMIT and SUBSCRIPTION. Some jurisdictions require an alarm permit before police or fire services will respond to an alarm. When a premises monitorable is created in such an area, the platform generates a PERMIT requirement. The requirement stays INCOMPLETE until a permit number and expiry date are recorded.

When the partner has active subscription offerings, premises monitorables also receive a SUBSCRIPTION pre-activation requirement that must be completed before activation.

For more background on compliance and how requirements are generated, see Jurisdictions & Compliance. For subscription offerings, see Subscriptions.

Getting Started​

Before submitting permit data, you need a partner application with the following scopes:

  • monitorable:read — to retrieve requirements and the monitorable
  • monitorable:write — to submit the permit

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.

Get the Requirement ID​

After a premises monitorable is created, the platform generates its compliance requirements automatically. Retrieve the monitorable to find the permit requirement and record its id:

cURLGET

Locate the entry with "type": "PERMIT" in the requirements array:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "requirements": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "type": "PERMIT",
      "status": "INCOMPLETE",
      "stage": "POST_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "eventTypes": ["BURGLARY", "HOLDUP_DURESS"],
      "applicationUrl": "https://www.county.gov/permit",
      "fees": [
        {
          "type": "PERMIT_INITIAL",
          "frequency": "PT0S",
          "amount": 50.00,
          "currency": "USD"
        }
      ],
      "renewal": {
        "frequency": "P1Y",
        "responsibleParty": "CUSTOMER",
        "fee": { "amount": 30.00, "currency": "USD", "frequency": "P1Y" }
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Record the requirement id — you will need it in the next step.

Submit the Permit​

Permits are submitted through the PATCH /monitorables/:monitorableId endpoint using the permits array. Each entry is matched to its requirement by requirementId.

cURLPATCH
FieldTypeDescription
requirementIdstringThe id of the PERMIT requirement on this monitorable
numberstringPermit number issued by the authority (max 200 characters)
expiresAtstringPermit expiration as an ISO 8601 datetime

On success the API returns the updated monitorable. The permit requirement status transitions to COMPLETE, and the submitted permit appears in the permits array:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "requirements": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "type": "PERMIT",
      "status": "COMPLETE",
      "stage": "POST_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "eventTypes": ["BURGLARY", "HOLDUP_DURESS"],
      "applicationUrl": "https://www.county.gov/permit",
      "fees": [
        {
          "type": "PERMIT_INITIAL",
          "frequency": "PT0S",
          "amount": 50.00,
          "currency": "USD"
        }
      ],
      "renewal": {
        "frequency": "P1Y",
        "responsibleParty": "CUSTOMER",
        "fee": { "amount": 30.00, "currency": "USD", "frequency": "P1Y" }
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-02-01T09:00:00Z"
    }
  ],
  "permits": [
    {
      "requirementId": "660e8400-e29b-41d4-a716-446655440001",
      "number": "PER-2024-001",
      "expiresAt": "2025-12-31T23:59:59Z",
      "createdAt": "2024-02-01T09:00:00Z",
      "updatedAt": "2024-02-01T09:00:00Z"
    }
  ]
}

Updating a Permit​

To update a permit (for example on renewal), submit a new PATCH request with the same requirementId and the updated number and expiresAt. The permit record is upserted — the existing entry is updated in place.

Subscription Requirement​

When a premises monitorable has a SUBSCRIPTION requirement, fulfill it by setting subscription on the monitorable. The value must be one of the types listed in the requirement options array.

Retrieve the monitorable and locate the entry with "type": "SUBSCRIPTION":

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "requirements": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "type": "SUBSCRIPTION",
      "status": "INCOMPLETE",
      "stage": "PRE_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "options": ["ANNUAL", "MONTHLY"],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Submit the selected plan with PATCH /monitorables/:monitorableId:

cURLPATCH
FieldTypeDescription
subscriptionstringOne of the values in the SUBSCRIPTION requirement options (MONTHLY or ANNUAL)

On success the requirement status transitions to COMPLETE and subscription is set on the monitorable. The subscription cannot be changed after the monitorable has been activated.

If the monitorable has no SUBSCRIPTION requirement, sending subscription returns a 404 error. Values outside the allowed options return a 400 error.

Conclusion​

You've submitted permit data for a monitorable. Once the permit requirement is complete, the monitorable's overall status transitions to VERIFIED (assuming all other requirements are also complete) and events can be monitored without restriction.

Learn More​