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

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

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.
`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 (e.g., `{"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 (e.g., `account`).
`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

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 }

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 (e.g., `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

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 }

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

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 }

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

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 }

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

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 }

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.