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.

1
require 'json'
2
3
# Sinatra
4
post '/my/monitoring_webhook/url' do
5
  payload = request.body.read
6
  event = JSON.parse(payload)
7
8
  case event.type
9
  when 'person.created'
10
    person_event = event['data']['object']
11
    business_id = person_event['business_id']
12
    puts 'Person added!
13
  else
14
    # Unexpected event type
15
    status 400
16
    return
17
  end
18
19
  status 200
20
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.

1
{
2
  "object": "person",
3
  "name": "JOHN DOE",
4
  "submitted": false,
5
  "business_id": "628821e0-3a16-4d84-8c7b-1e8f5920ac65",
6
  "sources": [
7
    {
8
      "id": "f7cb73f4-gcaf-4676-92c5-396ec3fa7694",
9
      "type": "registration",
10
      "metadata": {
11
        "state": "MT",
12
        "status": "active",
13
        "file_number": "F0012345",
14
        "jurisdiction": "FOREIGN"
15
      }
16
    }
17
  ],
18
  "titles": [
19
    {
20
      "object": "person_title",
21
      "title": "DIRECTOR"
22
    }
23
  ],
24
  "people_bankruptcies": []
25
}

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.

1
require 'net/http'
2
require 'net/https'
3
require 'json'
4
5
def 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
	person_task = response['review']['tasks'].find { |task| task['category'] == 'person_verification' }
26
27
	if person_task['status'] == 'success'
28
		puts 'Person match'
29
	else
30
    puts 'Person match failure'
31
	end
32
rescue StandardError => e
33
  puts "HTTP Request failed (#{e.message})"
34
end