Agents
Agents automate recurring Trustfull tasks.
Choose an Agent type, provide the required input, and set a schedule. The Agent then runs automatically and can notify you when a result meets the alert conditions you configure.
The Agent type defines the task, the input it requires, and the Trustfull product or products used to perform each run. You do not select a product separately.
For example, a Merchant Risk Agent can check example.com every day and notify your team when its score falls below 451. Merchant Risk uses Trustfull Domain for each scheduled check.
Enterprise onlyAgents are part of the Enterprise plan. A request from an App Key without it returns
403with the messageThis App Key is not enabled for Agents.Contact your account manager to enable Agents.
One-off requests and Agents
Agents are optional and separate from normal API requests. Creating an Agent does not change how your existing integrations work.
| One-off request | Agent |
|---|---|
| Runs once, on demand | Runs automatically on a schedule |
| Uses the product endpoint you choose | Uses the behavior defined by its Agent type |
| Produces one result | Produces a new result on every run |
| Starts when you call the API or use Run Check | Starts according to its saved schedule |
| Has no recurring configuration | Saves the Agent type, input, schedule, and optional alerts |
Use a one-off request when you need an answer now. Use an Agent when Trustfull should repeat the same task and alert you to important results.
The Agent model
An Agent is a saved configuration that runs Requests on a schedule. Each Request produces a Result, and Trustfull can send an Alert when the result meets the conditions configured for that Agent type.
The final step is optional: Trustfull sends an Alert only when you configure a notification channel and the alert condition is met.
Agent types
An Agent type defines what the Agent monitors, which input it needs, and how each run is evaluated. The Agent catalogue groups types into Merchant, Identity, Brand, and Discovery categories.
Merchant Risk is currently the only Agent type you can create. The other types appear in the dashboard as coming soon.
| Agent type | Category | What it does | Availability |
|---|---|---|---|
| Merchant Risk | Merchant | Watches merchant websites for risky content and changes in reputation. | 🟢 Available |
| Customer Identity Change | Identity | Tracks changes to customer contact details and identity signals. | 🟡 Coming soon |
| Brand Impersonation | Brand | Finds lookalike domains and websites posing as your brand. | 🟡 Coming soon |
| Fraud Network Discovery | Discovery | Surfaces shared identifiers and suspicious clusters around an identity. | 🟡 Coming soon |
| Phishing Campaign Discovery | Discovery | Discovers suspicious domains and connected phishing infrastructure. | 🟡 Coming soon |
| Executive Impersonation | Brand | Monitors for accounts and domains impersonating an executive. | 🟡 Coming soon |
| Fraudulent Job Posting | Brand | Finds suspicious job listings that misuse your company identity. | 🟡 Coming soon |
| Fake Mobile App | Brand | Discovers mobile apps imitating your brand or official application. | 🟡 Coming soon |
| Adverse Media | Discovery | Monitors news and online sources for negative coverage about a person, company, or website. | 🟡 Coming soon |
| Leaked Credit Card | Identity | Detects credit card numbers exposed in leaks and underground marketplaces. | 🟡 Coming soon |
| Leaked Email Address | Identity | Finds an email address exposed in data leaks and paste sites. | 🟡 Coming soon |
| Leaked Phone Number | Identity | Finds a phone number exposed in data leaks and public dumps. | 🟡 Coming soon |
Coming-soon Agent types cannot yet be selected in the dashboard or passed to the API.
How an Agent works
- Choose an Agent type. The type determines the task and the input Trustfull needs.
- Provide the input. For Merchant Risk, enter the merchant's domain.
- Set the schedule. Choose how often the Agent runs and, optionally, when it starts.
- Configure alerts. Choose a score threshold and add an email address, webhook, or both.
- Let the Agent run. Trustfull creates a new Request and Result on every scheduled run.
- Respond to alerts. Trustfull notifies the configured channels when the alert condition is met.
Each run uses credits in the same way as the underlying one-off request. A Merchant Risk run uses the same credits as a Trustfull Domain request.
For Merchant Risk, every run asks each Domain data source again, even when the domain was checked recently, so each Result describes the domain as it is at that moment. The new data is also saved, so later requests for the same domain can reuse it. If a source does not answer in time, the run uses the last valid value Trustfull holds for that source, when one is available.
Create an Agent
You can create an Agent from the Trustfull dashboard or programmatically through the Create Agent API. Both methods create the same Agent configuration.
In an API request, pass
"agent_type": "merchant_risk". Do not send a product: the Agent type determines the product used for each run.
1. Choose an Agent type
- Open Agents in the Trustfull dashboard.
- Select New agent.
- Select Merchant Risk, the currently available Agent type.
- Select Continue.
Types marked Coming soon are visible for preview but cannot be selected.
2. Configure the Agent
The second drawer displays the selected Agent type and the fields it requires.
- Enter the merchant domain without a protocol or path, such as
example.com. - Choose a frequency: daily, weekly, or monthly.
- Expand Advanced if you want to choose a start date or configure alerts.
- Select Create agent.
Use All Agents to return to the Agent type drawer before creating the Agent.
If you leave Start date empty, the Agent starts shortly after it is created. All Agent dates use UTC.
Only one Agent can be active for the same Agent type, input, and App Key.
Configure alerts
Alerts are optional. Without an email address or webhook, the Agent continues to run but sends no notifications.
Merchant Risk sends an alert when the score is lower than the configured Score threshold. The default threshold is 451.
Trustfull evaluates every Request independently. If several consecutive Requests return a score below the threshold, each one generates a new alert. An alert does not require the score to change from the previous Result.
For example:
| Result | Threshold | Outcome |
|---|---|---|
450 | 451 | Alert sent |
451 | 451 | No alert |
700 | 451 | No alert |
Configure either or both notification channels:
- Notification email sends an alert to the specified address.
- Webhook URL sends the complete result to a public HTTPS endpoint.
See Agent webhooks to configure an endpoint and verify signed requests.
Review Agent activity
The Agents table shows the Agent type, input, frequency, status, completed runs, last run, and next scheduled run.
Open an Agent or select View lookups from its action menu to review the Requests created by that Agent.
Because every run creates a separate Request, you can inspect each result independently and compare how the result changes over time.
Edit, stop, or restore an Agent
Open the action menu at the end of an Agent row:
- Edit changes the frequency, start date, score threshold, email, or webhook.
- Delete stops future runs and archives the Agent. Previous Requests remain available.
- Restore activates an archived Agent again and preserves its earlier history.
The Agent type and input cannot be changed after creation. Create another Agent when you need a different type or input.
Trustfull may archive an Agent automatically when it cannot continue—for example, when its App Key is inactive or there are not enough credits. Resolve the reported issue before restoring it.
Limits
- Plan. Agents are part of the Enterprise plan.
- Agent types. Merchant Risk is currently the only available type.
- Merchant Risk input. Enter one domain without a protocol or path.
- Frequency. Daily, weekly, or monthly.
- Start date. Optional. When you set one, it must be at least five minutes in the future. Without it, the first run starts about one minute after creation.
- One active Agent per input. An App Key can have one active Agent for each Agent type and input. Creating a second one returns
409. - Credits. Creating an Agent requires a balance of at least 200 credits on the App Key. When the credits run out, the Agent is archived with the reason
no_credits. - Webhook URL. It must use
httpsand pass the verification call described in Agent webhooks. - Number of Agents. There is no limit on the number of Agents per App Key.
FAQ
Why don't I select a product?The Agent type determines which Trustfull product or products run behind the scenes. Merchant Risk uses Trustfull Domain, so you only need to select Merchant Risk and enter the merchant domain.
Can I create an Agent type marked Coming soon?No. Coming-soon types are displayed as a preview but are disabled. Merchant Risk is currently the only type available through the dashboard and API.
Is an Agent required to run a request?No. Use the API or Run Check for a one-off result. Create an Agent only when Trustfull should repeat the task automatically.
Does an Agent reuse the same Request?No. Every run creates a new Request and Result. The Agent is the saved configuration that connects them.
Do I have to configure alerts?No. The Agent continues to run on schedule when both notification fields are empty, but it does not send an alert.
What happens when I delete an Agent?The Agent is archived and no future runs are scheduled. Its previous Requests and Results remain available.
Further reading
- Agents API Reference — create, retrieve, update, archive, and restore Agents programmatically.
- Create an Agent recipe — follow a complete Python example for creating a Merchant Risk Agent.
- Agent webhooks — configure an endpoint and verify signed Agent alerts.
Updated 8 days ago