For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact SalesGet Support
HomeGuidesAPI reference
HomeGuidesAPI reference
  • Middesk API
        • Action
        • Address
        • Adverse Media Screening
        • Bankruptcy
        • Business
        • Certification
        • Document
        • Formation
        • Industry Classification
        • Lien
        • Litigation
        • Monitor
        • Names
        • Order
        • Person
        • Policy Result
        • Politically Exposed Persons Screening
        • Registration
        • Review Task
        • Signal
        • Tax exempt organization
        • TIN
        • Watchlist
        • Website
        • Profile
LogoLogo
Contact SalesGet Support
On this page
  • Action types
  • Action object
  • Action attributes
  • Effect attributes
  • Actor attributes
  • Action type payloads
  • add_sources
  • add_attributes
  • verify_tin
  • decision
  • dismissal
  • Constraints
Middesk APIBusiness VerificationObject reference

Action object

Was this page helpful?
Previous

Address object

Next
Built with

Actions let you modify objects after verification is complete. Each action records what changed (effects) and who initiated it (actors), providing a full audit trail.

Action types

TypeDescriptionObject type
add_sourcesAdd external data sources with addresses and peoplebusinesses
add_attributesAdd addresses and/or people directlybusinesses
verify_tinMark a TIN as verified via documentbusinesses
decisionChange the business verification statusbusinesses
dismissalDismiss a watchlist resultwatchlist_result

Action object

Example JSON response
1{
2  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
3  "type": "add_sources",
4  "object_type": "Business",
5  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
6  "created_at": "2026-01-15T12:00:00.000Z",
7  "note": "Adding government verification source",
8  "metadata": {},
9  "effects": [
10    {
11      "operation": "created",
12      "diff": null,
13      "target": {
14        "object": "faa_airmen_certificate",
15        "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab"
16      }
17    }
18  ],
19  "actors": [
20    {
21      "actor_type": "account",
22      "data": {
23        "id": "d1e2f3a4-5678-90ab-cdef-1234567890ab",
24        "name": "Example Account"
25      }
26    }
27  ]
28}

Action attributes

AttributeTypeDescription
idstringUnique identifier for the action.
typestringThe action type. One of add_sources, add_attributes, verify_tin, decision, or dismissal.
object_typestringThe type of object the action was performed on. One of Business or Watchlist::Result.
object_idstringThe ID of the object the action was performed on.
created_atstringISO 8601 timestamp of when the action was created.
notestring | nullOptional text note describing the reason for the action.
metadataobjectAdditional metadata associated with the action.
effectsEffect[]List of effects describing what changed. See Effect attributes.
actorsActor[]List of actors describing who initiated the action. See Actor attributes.

Effect attributes

Each effect records a single change made during action execution.

AttributeTypeDescription
operationstringThe type of change. One of created, updated, or linked.
diffobject | nullBefore/after values for each changed field (for example, {"status": {"from": "in_review", "to": "approved"}}).
targetobject | nullReference to the affected resource with object (type) and id.

Actor attributes

Each actor identifies who or what initiated the action.

AttributeTypeDescription
actor_typestringThe type of actor. One of account or user.
dataobjectActor details (varies by actor type).

Action type payloads

add_sources

Add external data sources to a business. Each source can include addresses and people. The business must be in a final status (approved or rejected).

Request body
1{
2  "object_type": "businesses",
3  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
4  "type": "add_sources",
5  "note": "Adding government verification source",
6  "payload": {
7    "sources": [
8      {
9        "source_type": "faa_airmen_certificate",
10        "source_name": "FAA Airmen Registry",
11        "tier": "government",
12        "url": "https://faa.gov/pilots/records",
13        "addresses": [
14          { "full_address": "123 Main St, San Francisco, CA 94102" }
15        ],
16        "people": [
17          { "name": "Kyle Mack", "titles": ["Registered Agent"] }
18        ]
19      }
20    ]
21  }
22}
FieldTypeRequiredDescription
sourcesarrayYesOne or more source objects.
sources[].source_typestringYesIdentifier for the source type.
sources[].source_namestringYesDisplay name for the source.
sources[].business_namestringNoBusiness name as found in the source.
sources[].tierstringNoSource tier (for example, government, public_alternative).
sources[].urlstringNoURL to the source.
sources[].addressesarrayNoAddresses found in the source.
sources[].peoplearrayNoPeople found in the source.

add_attributes

Add addresses and/or people directly to a business without a source reference. The business must be in a final status.

Request body
1{
2  "object_type": "businesses",
3  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
4  "type": "add_attributes",
5  "note": "Adding verified address",
6  "payload": {
7    "addresses": [
8      { "full_address": "456 Oak Ave, Los Angeles, CA 90001" }
9    ],
10    "people": [
11      { "name": "Kyle Mack", "titles": ["CEO"] }
12    ]
13  }
14}
FieldTypeRequiredDescription
addressesarrayNo*Address objects to add.
peoplearrayNo*Person objects to add.
At least one of addresses or people must be provided.

verify_tin

Mark a business’s TIN as verified using an uploaded document. The business must have an existing TIN record and be in a final status.

Request body
1{
2  "object_type": "businesses",
3  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
4  "type": "verify_tin",
5  "payload": {
6    "document_id": "e1f2a3b4-5678-90ab-cdef-1234567890ab"
7  }
8}
FieldTypeRequiredDescription
document_idstringYesID of the document used for TIN verification.

decision

Change the verification status of a business. Valid transitions depend on the current business state.

Request body — approve
1{
2  "object_type": "businesses",
3  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
4  "type": "decision",
5  "note": "Approved after manual review",
6  "payload": {
7    "status": "approved"
8  }
9}
Request body — reject
1{
2  "object_type": "businesses",
3  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
4  "type": "decision",
5  "note": "Rejected due to compliance concerns",
6  "payload": {
7    "status": "rejected"
8  }
9}
FieldTypeRequiredDescription
statusstringYesTarget status: approved, rejected, or in_review.

dismissal

Dismiss a watchlist result. A note is required.

Request body
1{
2  "object_type": "watchlist_result",
3  "object_id": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
4  "type": "dismissal",
5  "note": "False positive - name similarity only",
6  "payload": {
7    "dismissed": true
8  }
9}
FieldTypeRequiredDescription
dismissedbooleanYesMust be true.
A note is required when dismissing watchlist results.

Constraints

  • add_sources, add_attributes, and verify_tin require the business to be in a final status (approved or rejected).
  • decision transitions are validated against the business state machine. You can only transition to statuses the business is eligible for.
  • Actions are atomic — all effects are applied within a single transaction. If any part fails, the entire action is rolled back.
Get a demo
Contact your account manager or contact sales to inquire about access.