Monitor business activityMonitor SoS registrations

Monitor status

Monitor for changes to the registration(s) associated with the business you’re monitoring.

To handle changes to a business’s registrations, subscribe to the registration.created and registration.updated events in your webhook endpoint. Use this to detect a change to any field on an existing registration and learn about new registrations associated with a business.

This example demonstrates handling an event update triggered by a change in registration status, but the same pattern can be generalized for any field associated with a registration.

1require 'json'
2
3# Sinatra
4post '/my/monitoring_webhook/url' do
5  payload = request.body.read
6  event = JSON.parse(payload)
7
8  case event.type
9  when 'registration.updated'
10    registration_event = event['data']['object']
11    business_id = registration_event['business_id']
12
13    # check for presence of a change in status field
14		if registration_event['previous_attributes').keys.include('status')
15    	puts registration_event['status']
16    end
17  else
18    # Unexpected event type
19    status 400
20    return
21  end
22
23  status 200
24end

Use the event payload

The event payload includes a snapshot of the registration associated to the business. Use the data.object.status field inside the webhook payload to read the registration’s status directly from the webhook event.

A special previous_attributes field is included in the embedded event object. This field contains a JSON object with the associated key/value pairs that have changed (and includes the previous values).

JSON
1{
2  "object": "registration",
3  "id": "87b564c8-fb5d-40m2-9e61-b5b5df902aeb",
4  "business_id": "006ecba9-4ec4-4610-8a2a-4ff0bb101e94",
5  "name": "My Monitored Business",
6  "status": "inactive",
7  "sub_status": null,
8  "status_details": "Inactive",
9  "jurisdiction": "FOREIGN",
10  "entity_type": "UNKNOWN",
11  "file_number": "06717223",
12  "addresses": [
13    "85 2nd St San Francisco CA, 94105"
14  ],
15  "officers": [],
16  "registered_agent": {},
17  "registration_date": "2007-08-21",
18  "state": "KY",
19  "source": "https://web.sos.ky.gov/BusSearchNProfile/search.aspx",
20  "previous_attributes": {
21    "status": "active"
22  }
23}

Use business review tasks

Re-evaluate the business’s review tasks by requesting the full business payload using the GET /businesses endpoint.

Use the SOS Domestic review task to re-evaluate the domestic filing status of the business after receiving the registration.updated event.

1require 'net/http'
2require 'net/https'
3require 'json'
4
5def send_request
6	business_id = "<business_id>"
7  uri = URI("https://api.middesk.com/v1/businesses/#{business_id}")
8
9  # Create client
10  http = Net::HTTP.new(uri.host, uri.port)
11  http.use_ssl = true
12  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
13
14  # Create Request
15  req =  Net::HTTP::Get.new(uri)
16  # Add headers
17  req.add_field "Accept", "application/json"
18  # Add headers
19  req.add_field "Authorization", "Basic <api_key>"
20
21  # Fetch Request
22  res = http.request(req)
23
24	response = JSON.parse(res.body)
25	sos_domestic_task = response['review']['tasks'].find { |task| task['category'] == 'sos_domestic' }
26
27	if sos_domestic_task['status'] == 'success'
28		puts 'SOS status active'
29	else
30    puts 'SOS status inactive'
31	end
32rescue StandardError => e
33  puts "HTTP Request failed (#{e.message})"
34end

Handle state-specific alerts

The most recent snapshot of the registration is included in the registration.updated event. Use this snapshot to selectively handle webhook events. For example, if you’re only interested in events emanating from a specific registration state, ignore events triggered from other registration updates.

This example filters on KY-only updates.

Ruby
1require 'json'
2
3# Only handle updates in KY
4post '/my/monitoring_webhook/url' do
5  payload = request.body.read
6  event = JSON.parse(payload)
7
8  case event.type
9  when 'registration.updated'
10    registration_event = event['data']['object']
11    business_id = registration_event['business_id']
12		state = registration_event['state']
13
14		# ignore other states
15    return if state != 'KY'
16
17    puts registration_event['status']
18  else
19    # Unexpected event type
20    status 400
21    return
22  end
23
24  status 200
25end

Next, use GET /businesses endpoint to fetch the full registration payload and select for individual registrations.

Ruby
1require 'net/http'
2require 'net/https'
3require 'json'
4
5def send_request
6	business_id = "<business_id>"
7  uri = URI("https://api.middesk.com/v1/businesses/#{business_id}")
8
9  # Create client
10  http = Net::HTTP.new(uri.host, uri.port)
11  http.use_ssl = true
12  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
13
14  # Create Request
15  req =  Net::HTTP::Get.new(uri)
16  # Add headers
17  req.add_field "Accept", "application/json"
18  # Add headers
19  req.add_field "Authorization", "Basic <api_key>"
20
21  # Fetch Request
22  res = http.request(req)
23
24	response = JSON.parse(res.body)
25	ky_registration = response['registrations'].find {|registration| registration['state'] = 'KY' }
26
27	if ky_registration
28		puts 'KY registration"
29	else
30    puts 'Missing KY registration'
31	end
32rescue StandardError => e
33  puts "HTTP Request failed (#{e.message})"
34end
Get a demo
Contact your account manager or contact sales to inquire about access.