Action object

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`

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.
`actors`	Actor[]	List of actors describing who initiated the action. See 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

{
  "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

{
  "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.

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

{
  "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

{
  "object_type": "businesses",
  "object_id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "type": "decision",
  "note": "Approved after manual review",
  "payload": {
    "status": "approved"
  }
}

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

{
  "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`.

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.