Using the Sandbox Environment

Middesk has a sandbox environment that can be accessed through the API or through the Dashboard. Sandbox mode can be used to test your integration end to end with mock data.

Accessing Sandbox Mode Through the Dashboard

While logged in to the dashboard, you can access the Sandbox test environment by clicking on the Products icon on the top-right corner of the page, then toggling "View Sandbox". Once in Sandbox mode, the sample attributes described under the Example Sandbox Business Attributes table below can be used to create a Business with sample data.

Accessing Sandbox Mode Through the API

You are immediately provided Sandbox API keys when your account is created. Your Sandbox keys can be retrieved by logging into your Middesk account and visiting Developer Settings. Sandbox keys must be used with the Sandbox API url https://api-sandbox.middesk.com/v1/.

Sandbox API requests are free and while you may include real business data in the Create a Business request, the response will return fake data. You may also set up Webhooks in the Sandbox environment.

Example Sandbox Business Attributes

One major benefit of using the Sandbox environment is that you can walk through various example scenarios that you might encounter you Create a Business.

To do so, include one (or more) of the specified values in the table below in your Create a Business request. Middesk will then return a response according to that value. This will allow you to run specific scenarios and build out your integration workflow accordingly.

Feel free to mix-and-match any of the values found on the table to create unique scenarios. For example, you can create a business with an approximate address match and unverified person using the inputs 223 Grand St., New York, NY 10013 and J Doe, respectively.

📘

Default Responses

If none of the special case inputs listed below are included in a submitted business, the Business will fallback to verifying all information. Given most inputs then, you can expect to receive a Review object with successful tasks.

Name Statuses

TypeValueDescription
NameUnregistered BusinessThe business has no Secretary of State filings. The Business returned will have no associated registrations.
NameSimilar Name BusinessThe business has a Secretary of State filing with a similar name to the submitted business name. The "name" review task indicates that a similar name was found to the submitted name.
NameUnverified Name BusinessThe submitted business name is unverified. The "name" review task indicates that a no similar name was found to match the submitted name.
NameCorporationThe business will have a formation entity_type matching the type CORPORATION. CORPORATION is the default if there's no entity type provided.
NamePartnershipThe business will have a formation entity_type matching the type PARTNERSHIP.
NameSole ProprietorshipThe business will have a formation entity_type matching the type SOLE PROPRIETORSHIP.
NameTrustThe business will have a formation entity_type matching the type TRUST.
NameNon ProfitThe business will have a formation entity_type matching the type Non Profit.
NameAgentThe business will have a formation entity_type matching the type AGENT.
NameLLCThe business will have a formation entity_type matching the type LLC.
NameYoung BusinessThe business will have been formed 10 days ago. The formation date should be ten days before the current date.
NameA business name containing the phrase short analyst reviewThis will simulate a standard case of a business being flagged for Middesk's Analyst-in-the-Loop flow by delaying the completion of the Identity order by 2 minutes. After 2 minutes the business will move from status: pending to status: in_review, results will be returned depending on the other trigger values provided, and a business.updated webhook will be sent if that is set up for your account.
NameA business name containing the phrase long analyst reviewThis will simulate a long-running case of a business being flagged for Middesk's Analyst-in-the-Loop flow by delaying the completion of the Identity order by 10 minutes. After 10 minutes the business will move from status: pending to status: in_review, results will be returned depending on the other trigger values provided, and a business.updated webhook will be sent if that is set up for your account.

Address Statuses

TypeValueDescription
Address123 Grand St., New York, NY 10013Unable to identify a match to the submitted Office Address. The submitted address is not found to match any address listed in Business records.
Address223 Grand St., New York, NY 10013Identified a similar address. The submitted address is similar to an address that has been found.
Address423 Grand St., New York, NY 10013Identified an approximate address. Identified an address within 0.2 miles of the submitted Office Address
AddressNew York, NYIdentified an incomplete address. Identified a partial match with a submitted address that is incomplete
Address - CMRAInclude cmra in address_line1 or full_address (e.g. 991 cmra st., New York, NY 10013)

You may also combine this w/ Office Address -Verification values. For example, 423 Grand St. cmra will trigger an Approximate Match + CMRA task
Identified a CMRA address. Submitted Office Address is zoned by USPS as a Commercial Mail Receiving Agency
Address - Registered AgentInclude registered agent in address_line1 or full_address (e.g. 991 registered agent st., New York, NY 10013)

You may also combine this w/ Office Address -Verification values. For example, 423 Grand St. registered agent will trigger an Approximate Match + Registered Agent task
Identified a Registered Agent address:
Submitted Office Address is actually the address of a Registered Agent, not the actual business
Address - DeliverabilityInclude undeliverable in address_line1 or full_address (e.g. 991 st. undeliverable, New York, NY 10013

You may also combine this w/ Office Address -Verification values. For example, 423 Grand St. undeliverable will trigger an Approximate Match + Undeliverable task
Identified an Undeliverable address:
The USPS is unable to deliver mail to the submitted Office Address

SOS Statuses

TypeValueDescription
SOS Filings - DomesticBusiness Name = Domestic MissingMissing Domestic Secretary of State Filing: The business has no domestic filing
SOS Filings - DomesticBusiness Name = Domestic InactiveDomestic Secretary of State Filing is Inactive: Inactive domestic filing found
SOS Filings - DomesticBusiness Name = Domestic UnknownUnable to detect status of Domestic Filing: No domestic filing status provided
SOS Filings - Partially InactiveBusiness Name = Partial InactiveAt least one Secretary of state filing is inactive and another active: At least one filing is active. Another inactive.

Entity Types

TypeValueDescription
entity_typeCORPORATIONThis will cause the entity_type_match insight to return a failure
entity_typeLLCThis will cause the entity_type_match insight to return a success

Person Statuses

TypeValueDescription
PersonJ DoeUnable to identify a match to the submitted person. The person input will result in an unverified Person, meaning there's no match found to the Person's name on any Business record.

TIN Statuses

TypeValueDescription
TIN110000099TIN Name mismatch. The submitted TIN was found to be associated with a different entity name.
TIN111222333TIN Name unknown and issued. The submitted TIN's status is unknown. The TIN's issued status will be issued.
TIN444555666TIN Name unknown and not issued This TIN will return unverified with the submitted name and will also be marked as unissued.
TINtin = 222333444
Person = Jane Match
If SSN or SSN and EIN is added to the end of the Person name, then the returned tin_type will change accordingly
TIN Name matches the submitted person.
The submitted TIN is associated with the submitted person.
TINBusiness name ends with SSN or SSN and EINTIN type changed The submitted TIN will have a tin_type of whichever type is added to the submitted business name
TIN333444555IRS Unavailable. The IRS is unavailable at this time. TIN will be rerun once the IRS is available again

Bankruptcy

TypeValueDescription
BankruptcyA business name containing the word bankruptcyThe business will have a bankruptcy. The Business will have a bankruptcy attached.

Watchlist

TypeValueDescription
WatchlistA Business name or Person name containing the phrase watchlist hit.The business or person will have a watchlist hit on them

Industry Classification

TypeValueDescription
Industry ClassificationAny websiteThe business' website will have an industry classification
Industry ClassificationA website containing the wordshighriskThe business' website will have an industry classification with a high risk result.

Liens Search

TypeValueDescription
No Liens FoundAny business nameNo liens will be found. The liens search will return no records for this business.

Note: Liens is a premium feature. See this page for more information.
Liens Found - BlanketAny business name containing the phrase liens foundBy default, blanket liens will be found (see the collateral_type field).
Liens Found - CollateralTo produce collateral liens in the search results, add the phrase liens found collateral lien to the business name.

NPI Records

TypeValueDescription
NPI RecordsA business named Healthcare ProviderThis will return a business with NPI records returned. The submitted address will be linked to an NPI record.

FMCSA Records

TypeValueDescription
FMCSA RegistrationsA business named Trucking BusinessThis will return a business with FMCSA registrations . The submitted address will be linked to an FMCSA registration.

People Bankruptcy

TypeValueDescription
PersonA person with a provided first_name, last_name, and SSN, with the last name containing bankruptcyWhen people bankruptcies are ordered, the provided person will have a bankruptcy returned on them.

Socure KYC

TypeValueDescription
Person with KYC fieldsAny person with KYC fieldsAll of the fields present on a sandbox Socure KYC Person request will be sent through to Socure's sandbox triggers. You can read about Socure's sandbox trigger values here (Socure account and login required).

Note: KYC is a premium feature. See this page for more information.

Adverse Media

TypeValueDescription
adverse_mediaA business name containing "adverse media highrisk"This will result in a High Risk result for adverse media (identity/business_verification_verify and adverse_media must be ordered on the business)
adverse_mediaA business name containing "adverse media lowrisk"This will result in a Low Risk result for adverse media (identity/business_verification_verify and adverse_media must be ordered on the business)
adverse_mediaA business name containing "adverse media moderaterisk"This will result in a Moderate Risk result for adverse media (identity/ business_verification_verify and adverse_media must be ordered on the business)

Differences between Sandbox and Production

The Sandbox environment enables you to familiarize yourself and experiment with the Middesk API before going live in a Production environment. Listed below are some key differences between the two environments:

Depth of report information

Middesk provides a rich set of information for its Businesses. In Production, a Business could have a significant number of Resources associated with it such as multiple registration records, multiple addresses, multiple officers, and so on. The Sandbox environment provides enough information to build an integration, but the variance in the data that is returned is limited in order to address the most common integration use cases.

Business lifecycle

As referenced in the Lifecycle of a Business section, Middesk transitions a Business through multiple statuses, from pending to in_review. The Sandbox environment supports all of these statuses, with the exception of the in_audit status. When building in Sandbox, it's important to take this difference into consideration.

Documents

In Sandbox, Documents can be ordered for every Business that is created. Ordering Documents automatically is a premium feature which must also be enabled in Production. If interested in learning more, please contact sales.

Liens

In Sandbox, Liens can be ordered for every Business that is created. Ordering Liens Searches automatically is a premium feature which must also be enabled in Production. If interested in learning more, please contact sales.

Litigations

In Sandbox, Litigations are not automatic. Ordering litigations is a premium feature and to enable the support in Sandbox, it has to be enabled in production and configured to order automatically. If interested in learning more, please contact sales.

Additional features

Business Batches

Businesses can be created in Batches in both the Sandbox and Production environments. Use this feature to create many businesses at once, and provide attributes as detailed in the table above to trigger different verification scenarios as desired.

Industry Classification

Classifications can be created for Sandbox businesses if a website URL is inputted or as stand-alone classifications. For both products, the possible inputs to get different results are described below:

Website URLResults
ContainshighriskIncludes a result in a high-risk category.
Anything elseResults only in low-risk categories.

Monitoring

To test monitoring, create a business with the inputs described below. The business will automatically have a monitor with the corresponding event type. After a minute, the business and its records will be updated accordingly to simulate the occurrence of that event, which you can receive by creating a webhook or polling for updates.

Event TypeInput FieldValueDescription
watchlist_result.createdBusiness NameWatchlist Result Created IncA new Watchlist Result will be created for the Business
tin.retrievedTI111222333The TIN will initially be unknown and then become verified.
registration.updatedBusiness NameMonitoring Registration.UpdatedA registration associated will be updated and a registration.updated officers, status, addresses fields will be updated.

Lien Filing

To test Lien Filing, you'll need to have Lien Filing enabled in production. If it is not currently enabled, you can contact [email protected] to get that set up. Once enabled, you can test with the File a Lien endpoint in Sandbox. Approximately thirty seconds after you hit the File a Lien endpoint, we'll transition the Lien status to filed to mimic the time it takes Middesk to process your request. At this point, a production filing would have been submitted to the government, but no UCC-1 Document would be associated with the Lien, and this is the case in Sandbox too. After approximately another thirty seconds, we'll transition the Lien status to open to mimic the time it takes the government to process the filing. At this point, a production filing would have a UCC-1 document, and a blank UCC-1 document will be present on the Lien in Sandbox to reflect this. lien.updated Webhook Events are sent when the Lien status changes.

User Roles and Permissions

Each Middesk user has a role that allows for specific capabilities:

  1. Member: Basic team member; can create and view Businesses
  2. Developer: Includes all Member privileges as well as the ability to view (and edit where appropriate) API Keys, Webhooks, APILogs, IPAllowLists, and add Batches
  3. Admin: All privileges; including Developer privileges as well as the ability to add team members and to customize Policies