Monitor people

Monitor for changes to the people associated with a business so you can detect officer turnover, ownership shifts, and other personnel changes that may affect your risk decision. Middesk identifies people changes from Secretary of State officer listings and related authoritative sources, so the events reflect the legal record rather than self-reported updates.

People changes often signal a material event: a CEO departure, a buyout, a re-incorporation, or simply a routine annual filing that adds new directors. Use these events to re-run review tasks and decide whether the submitted person on the business still matches the current officer set.

To handle changes to people on a business, subscribe to the person.created and person.deleted events in your webhook endpoint:

• person.created — a new officer was identified for the business.
• person.deleted — a previously identified officer is no longer associated with the business.

require 'json'
# Sinatra
post '/my/monitoring_webhook/url' do
  payload = request.body.read
  event = JSON.parse(payload)
  case event.type
  when 'person.created'
    person_event = event['data']['object']
    business_id = person_event['business_id']
    puts 'Person added!
  else
    # Unexpected event type
    status 400
    return
  end
  status 200
end

Use the event payload

Depending on your use case, you can use the name event directly (like storing the new name for review in your application) or use the event as a trigger to reevaluate the approval status of the business using the full business payload.

{
  "object": "person",
  "name": "JOHN DOE",
  "submitted": false,
  "business_id": "628821e0-3a16-4d84-8c7b-1e8f5920ac65",
  "sources": [
    {
      "id": "f7cb73f4-gcaf-4676-92c5-396ec3fa7694",
      "type": "registration",
      "metadata": {
        "state": "MT",
        "status": "active",
        "file_number": "F0012345",
        "jurisdiction": "FOREIGN"
      }
    }
  ],
  "titles": [
    {
      "object": "person_title",
      "title": "DIRECTOR"
    }
  ],
  "people_bankruptcies": []
}

Use the business review tasks

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

Use the Person Verification Task to evaluate whether the name still matches to the submitted business name.

require 'net/http'
require 'net/https'
require 'json'
def send_request
	business_id = "<business_id>"
  uri = URI("https://api.middesk.com/v1/businesses/#{business_id}")
  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Accept", "application/json"
  # Add headers
  req.add_field "Authorization", "Basic <api_key>"
  # Fetch Request
  res = http.request(req)
	response = JSON.parse(res.body)
	person_task = response['review']['tasks'].find { |task| task['category'] == 'person_verification' }
	if person_task['status'] == 'success'
		puts 'Person match'
	else
    puts 'Person match failure'
	end
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end