Activity History

The Activity API gives you a complete audit trail of every search and enrichment request you've made. Use it to review past work, find specific entities you've already accessed, and avoid paying repeat credits for data you already have.

Why Activity Matters

Every time you run a search or enrichment through the API, DealMachine logs it as an activity record. Each record captures:

What you requested — the full parameters (locations, filters, enrichment inputs)
What came back — summary stats and the entity IDs returned
What it cost — credits consumed, broken down by new vs. repeat
Which API key made the request: the stable key ID and current key name

This means you can answer questions like:

"What searches have I run this month?"
"Have I already looked up this property or person?"
"Which of my searches used an equity filter?"
"Did I already enrich john@example.com?"
"What were the exact filters I used in that search last week?"
"Which entity IDs came back from a specific request?"

Activity Types

Every activity has a type that tells you which endpoint generated it:

Type	Endpoint	Description
`search_people`	`POST /v1/people/search`	People/contact search
`search_properties`	`POST /v1/properties/search`	Property search
`count_people`	`POST /v1/people/search/count`	People count query
`count_properties`	`POST /v1/properties/search/count`	Property count query
`enrich_email`	`POST /v1/enrichment/email`	Email enrichment
`enrich_phone`	`POST /v1/enrichment/phone`	Phone enrichment
`enrich_address`	`POST /v1/enrichment/address`	Address enrichment
`enrich_latlng`	`POST /v1/enrichment/latlng`	Lat/lng enrichment
`enrich_reverse_geocode`	`POST /v1/enrichment/latlng`	Reverse geocode enrichment
`enrich_apn`	`POST /v1/enrichment/apn`	APN enrichment
`enrich_name`	`POST /v1/enrichment/name`	Name enrichment
`export_people`	`POST /v1/people/export`	People export
`export_properties`	`POST /v1/properties/export`	Property export
`get_person`	`GET /v1/people/:id`	Person lookup
`get_person_batch`	`POST /v1/people/ids`	Batch person lookup
`get_property`	`GET /v1/properties/:id`	Property lookup
`get_property_batch`	`POST /v1/properties/ids`	Batch property lookup
`phone_dnc_check`	`POST /v1/phones/dnc`	DNC phone check
`validate_addresses`	`POST /v1/addresses/validate`	Address validation
`comps_analysis`	`POST /v1/comps`	Comparable sales analysis
`api_key_created`	API key management	API key created
`api_key_rotated`	API key management	API key rotated
`api_key_revoked`	API key management	API key revoked
`additional_credit_grant`	Credit management	Additional credits granted
`additional_credit_purchase`	Credit management	Additional credits purchased

Common Workflows

Searching by Text

Use the query parameter to search across all your activity by filter name, location, enrichment input, or anything else in the original request. This is the fastest way to find a past search when you remember what you searched for but not when.

1234{
  "query": "equity",
  "sort": [{ "field": "relevance", "direction": "desc" }]
}

This returns every activity that mentions "equity" anywhere in its request parameters — like searches using the equity_percent filter. The response includes a matched_on array showing exactly which part matched. See Text Search for the full reference.

Reviewing Past Searches

Pull up everything you've searched in the last 30 days:

12345678910{
  "filters": {
    "type": ["search_people", "search_properties"]
  },
  "date_range": {
    "start": "2025-06-01T00:00:00Z",
    "end": "2025-06-30T23:59:59Z"
  },
  "sort": [{ "field": "created_at", "direction": "desc" }]
}

Checking If You've Already Accessed an Entity

Before running a new search or enrichment, check if you've already pulled data on a specific person or property:

123456{
  "entity_ids": ["per_x1y2z3"],
  "filters": {
    "type": ["search_people", "enrich_email", "enrich_phone"]
  }
}

If results come back, you've already accessed that entity — and it won't cost additional credits within the same billing period.

Replaying a Search

Found an activity record for a search you want to re-run? The Get Activity endpoint returns the full original request parameters, so you can copy them directly into a new search request.

Building a Local Cache

Use activity history to maintain a local record of which entities you've already pulled. Page through the entity_ids on each activity to build a local lookup table, then skip entities you already have when running new searches.

Activity Endpoints

Endpoint	Method	Description
`/v1/activity/search`	POST	Query and filter your activity history
`/v1/activity/:activity_id`	GET	Get full details of a specific activity record

Notes

Activity records are read-only. You cannot modify or delete them.
Activity is scoped to your organization — all API keys and OAuth tokens under the same organization share the same activity log.
Each activity includes api_key_id and api_key_name so you can attribute organization-wide usage to the caller. The name is null when the matching key record is no longer available.
Count queries (count_people, count_properties) are logged but do not include entity IDs since no data is returned.
Activity records are retained for 12 months from the date of the request.
Querying activity does not consume credits.