> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Action object

> Perform operations on completed businesses including adding sources, attributes, verifying TINs, and changing decisions.

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

| Type             | Description                                         | Object type        |
| ---------------- | --------------------------------------------------- | ------------------ |
| `add_sources`    | Add external data sources with addresses and people | `businesses`       |
| `add_attributes` | Add addresses and/or people directly                | `businesses`       |
| `verify_tin`     | Mark a TIN as verified via document                 | `businesses`       |
| `decision`       | Change the business verification status             | `businesses`       |
| `dismissal`      | Dismiss a watchlist result                          | `watchlist_result` |

## Action object

**`Example JSON response`**

```json title="Example JSON response"
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "type": "add_sources",
  "object_type": "Business",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "created_at": "2026-01-15T12:00:00.000Z",
  "note": "Adding government verification source",
  "metadata": {},
  "effects": [
    {
      "operation": "created",
      "diff": null,
      "target": {
        "object": "faa_airmen_certificate",
        "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab"
      }
    }
  ],
  "actors": [
    {
      "actor_type": "account",
      "data": {
        "id": "d1e2f3a4-5678-90ab-cdef-1234567890ab",
        "name": "Example Account"
      }
    }
  ]
}
```

## Action attributes

| Attribute     | Type           | Description                                                                                        |
| ------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `id`          | string         | Unique identifier for the action.                                                                  |
| `type`        | string         | The action type. One of `add_sources`, `add_attributes`, `verify_tin`, `decision`, or `dismissal`. |
| `object_type` | string         | The type of object the action was performed on. One of `Business` or `Watchlist::Result`.          |
| `object_id`   | string         | The ID of the object the action was performed on.                                                  |
| `created_at`  | string         | ISO 8601 timestamp of when the action was created.                                                 |
| `note`        | string \| null | Optional text note describing the reason for the action.                                           |
| `metadata`    | object         | Additional metadata associated with the action.                                                    |
| `effects`     | Effect\[]      | List of effects describing what changed. See [Effect attributes](#effect-attributes).              |
| `actors`      | Actor\[]       | List of actors describing who initiated the action. See [Actor attributes](#actor-attributes).     |

## Effect attributes

Each effect records a single change made during action execution.

| Attribute   | Type           | Description                                                                                                      |
| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `operation` | string         | The type of change. One of `created`, `updated`, or `linked`.                                                    |
| `diff`      | object \| null | Before/after values for each changed field (for example, `{"status": {"from": "in_review", "to": "approved"}}`). |
| `target`    | object \| null | Reference to the affected resource with `object` (type) and `id`.                                                |

## Actor attributes

Each actor identifies who or what initiated the action.

| Attribute    | Type   | Description                                    |
| ------------ | ------ | ---------------------------------------------- |
| `actor_type` | string | The type of actor. One of `account` or `user`. |
| `data`       | object | Actor 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`**

```json title="Request body"
{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "add_sources",
  "note": "Adding government verification source",
  "payload": {
    "sources": [
      {
        "source_type": "faa_airmen_certificate",
        "source_name": "FAA Airmen Registry",
        "tier": "government",
        "url": "https://faa.gov/pilots/records",
        "addresses": [
          { "full_address": "123 Main St, San Francisco, CA 94102" }
        ],
        "people": [
          { "name": "Kyle Mack", "titles": ["Registered Agent"] }
        ]
      }
    ]
  }
}
```

| Field                     | Type   | Required | Description                                                    |
| ------------------------- | ------ | -------- | -------------------------------------------------------------- |
| `sources`                 | array  | Yes      | One or more source objects.                                    |
| `sources[].source_type`   | string | Yes      | Identifier for the source type.                                |
| `sources[].source_name`   | string | Yes      | Display name for the source.                                   |
| `sources[].business_name` | string | No       | Business name as found in the source.                          |
| `sources[].tier`          | string | No       | Source tier (for example, `government`, `public_alternative`). |
| `sources[].url`           | string | No       | URL to the source.                                             |
| `sources[].addresses`     | array  | No       | Addresses found in the source.                                 |
| `sources[].people`        | array  | No       | People 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`**

```json title="Request body"
{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "add_attributes",
  "note": "Adding verified address",
  "payload": {
    "addresses": [
      { "full_address": "456 Oak Ave, Los Angeles, CA 90001" }
    ],
    "people": [
      { "name": "Kyle Mack", "titles": ["CEO"] }
    ]
  }
}
```

| Field       | Type  | Required | Description             |
| ----------- | ----- | -------- | ----------------------- |
| `addresses` | array | No\*     | Address objects to add. |
| `people`    | array | No\*     | Person objects to add.  |

> **Note**
>
> 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`**

```json title="Request body"
{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "verify_tin",
  "payload": {
    "document_id": "e1f2a3b4-5678-90ab-cdef-1234567890ab"
  }
}
```

| Field         | Type   | Required | Description                                   |
| ------------- | ------ | -------- | --------------------------------------------- |
| `document_id` | string | Yes      | ID 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`**

```json title="Request body — approve"
{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "decision",
  "note": "Approved after manual review",
  "payload": {
    "status": "approved"
  }
}
```

**`Request body — reject`**

```json title="Request body — reject"
{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "decision",
  "note": "Rejected due to compliance concerns",
  "payload": {
    "status": "rejected"
  }
}
```

| Field    | Type   | Required | Description                                            |
| -------- | ------ | -------- | ------------------------------------------------------ |
| `status` | string | Yes      | Target status: `approved`, `rejected`, or `in_review`. |

### dismissal

Dismiss a watchlist result. A note is required.

**`Request body`**

```json title="Request body"
{
  "object_type": "watchlist_result",
  "object_id": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
  "type": "dismissal",
  "note": "False positive - name similarity only",
  "payload": {
    "dismissed": true
  }
}
```

| Field       | Type    | Required | Description     |
| ----------- | ------- | -------- | --------------- |
| `dismissed` | boolean | Yes      | Must be `true`. |

> **Note**
>
> 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](https://www.middesk.com/contact-sales) to inquire about access.