Quickstart—Verify a business

Verify a business

A Business is the central object in the Middesk API. When you create a Business in Middesk, you automatically trigger the verification process.

In a production integration, first collect a few key business attributes from your user through your onboarding flow. Then send this data as part of a Create a Business API call.

Only name and addresses parameters are required, but in real-world applications, provide Middesk with more data for a more detailed verification.

To try it out, use:

• Your sandbox API key, available in the Dashboard
• Sample data

For example, if you use a name value of Corporation, Middesk reports the business as being a registered corp. Use a name value of Unregistered Business and Middesk reports the business having no associated registrations.

For addresses, provide 223 Grand St., New York, NY 10013 for a correct address match, or 423 Grand St., New York, NY 10013 for an approximate address match.

1
curl -X POST https://api-sandbox.middesk.com/v1/businesses \
2
  -u <YOUR_SANDBOX_API_KEY>: \
3
  -H "Accept: application/json" \
4
  -d name=Corporation \
5
  -d addresses\[0\]\[address_line1\]=223+Grand+St. \
6
  -d addresses\[0\]\[city\]=new+york \
7
  -d addresses\[0\]\[state\]=NY \
8
  -d addresses\[0\]\[postal_code\]=10013

For a successful request, Middesk returns a 201 status code along with a JSON body containing the new Business object.

Find the verification results

For a test business verification, the results come back quickly—probably by the time you’ve read to this point! View the results using:

• The Middesk Dashboard
• A Retrieve a Business API call
• A webhook endpoint

As the Business was created in the sandbox environment, make sure you make a sandbox API call or look at sandbox data in the Dashboard.

1
curl -X GET https://api-sandbox.middesk.com/v1/businesses/<BUSINESS_ID> \
2
  -u <YOUR_SANDBOX_API_KEY>: \
3
  -H "Accept: application/json"

Review the verification results

The code in Step 1 creates a Business object in your account, and triggers a Middesk verification review. After Middesk completes its verification process, Middesk updates the Business object with the results.

The last step is for you to make a decision about this business based upon Middesk’s report.

However you examine the updated Business object—using the Dashboard, a retrieve API call, or your webhook endpoint—pay attention to:

• data.object.id is the Middesk business_id. Middesk highly recommends storing the business_id on your side as it’s required when peforming subsequent requests. It is also useful for debugging or reviewing activity.
• data.object.status reflects the current status of the Business in the Middesk lifecycle.
• data.object.review.tasks stores high-level insights based on each business attribute. Most Middesk customers render a KYB decision based on the review tasks.

Here is an excerpt of what the data.object.review.tasks array might look like if a business name, address, person, and TIN were submitted for a given business.

1
"tasks": [
2
    {
3
      "category": "name",
4
      "key": "name",
5
      "label": "Business Name",
6
      "message": "Match identified to the submitted Business Name",
7
      "name": "name",
8
      "status": "success",
9
      "sub_label": "Verified",
10
      "sources": [
11
        {
12
          "id": "cba235c3-be54-44f9-bfeb-4f474d6f7e33",
13
          "type": "name",
14
          "metadata": {
15
            "name": "Middesk, Inc",
16
            "submitted": true
17
          }
18
        }
19
      ]
20
    },
21
    {
22
      "category": "address",
23
      "key": "address_verification",
24
      "label": "Office Address",
25
      "message": "Match identified to the submitted Office Address",
26
      "name": "address",
27
      "status": "success",
28
      "sub_label": "Verified",
29
      "sources": [
30
        {
31
          "id": "afa00984-1d0d-4281-806c-5aadd581d29b",
32
          "type": "address",
33
          "metadata": {
34
            "city": "San Francisco",
35
            "state": "CA",
36
            "submitted": true,
37
            "postal_code": "94105-3459",
38
            "full_address": "85 2nd St, San Francisco, CA 94105-3459",
39
            "address_line1": "85 2nd St",
40
            "address_line2": null
41
          }
42
        }
43
      ]
44
    },
45
    {
46
      "category": "watchlist",
47
      "key": "watchlist",
48
      "label": "Watchlist",
49
      "message": "No Watchlist hits were identified",
50
      "name": "watchlist",
51
      "status": "success",
52
      "sub_label": "No Hits",
53
      "sources": []
54
    }
55
  ]

More succinctly put, the JSON results are:

Depending upon your compliance needs and risk tolerance, you may approve this business to use your platform, or reach back out to double-check their TIN (as example responses).

Automate how you handle the verification results in your integration using rulesets or Policies.