Skip to main content
GET
/
api
/
agents
/
{agent_uid}
/
sandbox-entity-search
Sandbox entity search
curl --request GET \
  --url https://api.example.com/api/agents/{agent_uid}/sandbox-entity-search
Search invoices or emails within an organization to find entities for sandbox testing. Results are scoped to the agent’s organization and sorted by recency. Use this endpoint to power an entity picker in the sandbox UI. Pass the returned entity_uid to Sandbox run.

​
Path parameters

​
agent_uid
string
required
UUID of the agent whose organization is searched.

​
Query parameters

​
trigger_type
string
required
Entity type to search. One of: invoice, email_received.
​
q
string
required
Search text (minimum 2 characters). Matches against:
  • Invoices: invoice number, customer name, or invoice UID
  • Emails: subject, sender email, sender name, or message UID
​
per_page
integer
default:"10"
Maximum results to return. Range: 1–50.

​
Response

Returns 200 with a data array of matching entities. The shape of each item depends on trigger_type.

​
Invoice results

{
  "status": "success",
  "status_code": 200,
  "message": "Sandbox entities retrieved",
  "data": [
    {
      "entity_type": "invoice",
      "entity_uid": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
      "label": "INV-2026-0042",
      "description": "Acme Corp",
      "total_cents": 150000,
      "due_date": "2026-04-15",
      "status": "sent",
      "customer": {
        "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    }
  ]
}
FieldTypeDescription
entity_typestringAlways "invoice"
entity_uidstringInvoice UUID
labelstringInvoice number (falls back to UID)
descriptionstring | nullCustomer name
total_centsinteger | nullInvoice total in cents
due_datestring | nullISO 8601 date
statusstring | nullInvoice status (e.g. sent, overdue, paid)
customerobject | nullCustomer uid and name

​
Email results

{
  "status": "success",
  "status_code": 200,
  "message": "Sandbox entities retrieved",
  "data": [
    {
      "entity_type": "message",
      "entity_uid": "f1e2d3c4-b5a6-9788-7069-504132241506",
      "label": "RE: Invoice inquiry",
      "description": "billing@acme.com",
      "from_name": "John Doe",
      "sent_at": "2026-03-20T10:30:00",
      "snippet": "Please find the invoice attached..."
    }
  ]
}
FieldTypeDescription
entity_typestringAlways "message"
entity_uidstringEmail message UUID
labelstringSubject line (falls back to sender email or UID)
descriptionstring | nullSender email address
from_namestring | nullSender display name
sent_atstring | nullISO 8601 datetime
snippetstring | nullEmail body preview

​
Errors

StatusReason
400Missing or invalid query parameters (e.g. q shorter than 2 characters)
404Agent not found
422Unsupported trigger_type
500Internal server error