Signal object | Middesk

This page describes the signal object, which represents a risk score and assessment for a business. Signals provide a numerical score from 0 to 1 along with reason codes that explain the factors contributing to the score.

Example JSON response

1 {
2   "object": "signal",
3   "id": "f074244d-5cf3-4703-950a-73a7d54ee555",
4   "name": "Acme Corp",
5   "tin": "12-3456789",
6   "external_id": "customer-123",
7   "model_slug": "default",
8   "score": 0.85,
9   "business_id": "b3638510-87ec-425e-bdaa-ad6e48dec871",
10   "batch_id": null,
11   "requester": {
12     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
13     "type": "api_key",
14     "name": "Production API Key"
15   },
16   "reasons": [
17     {
18       "category": "identification",
19       "group": "customer_information",
20       "description": "The submitted tax ID belongs to the business",
21       "code": "I102",
22       "importance": 0.25
23     },
24     {
25       "category": "verification",
26       "group": "government_filings",
27       "description": "The business is registered in multiple states",
28       "code": "V101",
29       "importance": 0.20
30     }
31   ],
32   "addresses": ["2180 Bryant St Ste 210, San Francisco, CA 94110"],
33   "people": ["John Smith", "Jane Doe"],
34   "created_at": "2024-01-30T23:49:01.100Z"
35 }

Signal attributes

Attribute	Type	Description
`object`	string	The object type. Always `signal`.
`id`	string (uuid)	The unique identifier for the signal.
`name`	string	The business name associated with this signal.
`tin`	string \| null	The Tax Identification Number if provided.
`external_id`	string \| null	An optional external identifier you provided when creating the signal request.
`model_slug`	string	The scoring model used to generate this signal.
`score`	float \| null	The risk score from 0.0 (highest risk) to 1.0 (lowest risk). May be null if the score could not be calculated.
`business_id`	string (uuid) \| null	The unique identifier of the associated business, if one was created.
`batch_id`	string (uuid) \| null	The unique identifier of the batch, if this signal was part of a batch request.
`requester`	object	Information about who requested the signal.
`requester.id`	string (uuid)	The unique identifier of the requester.
`requester.type`	string	The type of requester (for example, `api_key`, `user`).
`requester.name`	string	The name of the requester.
`reasons`	object[]	An array of reason codes explaining the score.
`reasons[].category`	string	The category of the reason. Possible values: `identification`, `verification`, `evaluation`.
`reasons[].group`	string	The group or area this reason pertains to.
`reasons[].description`	string	A human-readable description of the reason.
`reasons[].code`	string	The reason code identifier.
`reasons[].importance`	float	The relative importance of this reason in the overall score.
`addresses`	string[]	List of addresses associated with the business.
`people`	string[]	List of people associated with the business.
`created_at`	timestamp	The timestamp when the signal was created.

Reason categories

Category	Description
`identification`	Reasons related to identifying and finding the business in public records.
`verification`	Reasons related to verifying submitted information against found records.
`evaluation`	Reasons related to evaluating risk factors and business characteristics.

Reason codes

Each signal includes one or more reason codes that explain the score. Reason codes are prefixed by their category: I for identification, V for verification, and E for evaluation.

For the complete list of reason codes and their descriptions, see Reason codes.

Get a demo

Contact your account manager or contact sales to inquire about access.