Leads and attribution

The leads AI answers sent you, pushed to your CRM or a Google Sheet, and the Analytics and Search Console reads beside them.

GET /brands/{brandId}/leads

The lead ledger with its measured evidence, and the influenced tier.

About this route	Detail
Returns	ledger (rows, total, aiLeads, withEvidence, days) and influenced. With format=csv, the ledger as a CSV file instead.
Seat	Any seat's key, a viewer's included.
Plan	Optimize and up, for format=csv only; the JSON read is open on every plan.
Rate limit	None on this route.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.
format (query)	one of csv	csv downloads the ledger as a CSV file. That export needs the attribution plan gate.

curl "https://api.ansengine.co/brands/{brandId}/leads" \
  -H "Authorization: Bearer ak_your_key"

Status	When
200	ledger (rows, total, aiLeads, withEvidence, days) and influenced. With format=csv, the ledger as a CSV file instead.
400	An id in the path is not a valid id.
401	No valid API key was sent.
402	This needs a higher plan: Optimize and up, for format=csv only; the JSON read is open on every plan. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.

POST /brands/{brandId}/leads/{leadId}/crm

Push one lead into your connected HubSpot or Salesforce, with its evidence.

Note

With both CRMs connected, send target. With one, the body can be empty.

About this route	Detail
Returns	ok, contactId, already and target (hubspot or salesforce). Pushing a lead twice is safe: the second push answers already: true.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Optimize and up.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.
leadId (path, required)	uuid	The lead id.

The body is JSON, and it may be left out. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "enum": [
        "hubspot",
        "salesforce"
      ]
    }
  },
  "additionalProperties": false
}

curl -X POST "https://api.ansengine.co/brands/{brandId}/leads/{leadId}/crm" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	ok, contactId, already and target (hubspot or salesforce). Pushing a lead twice is safe: the second push answers already: true.
400	An id in the path is not valid, the body does not match the schema, or both CRMs are connected and target is missing.
401	No valid API key was sent.
402	This needs a higher plan: Optimize and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
403	The key belongs to a viewer seat, which can read and cannot write.
404	No such brand for this key, or no such lead on this brand.
409	No connected CRM matches: connect HubSpot or Salesforce on the Connections page first.
422	The CRM refused the push. The body says why.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
503	CRM push is not configured on this deployment.

POST /brands/{brandId}/leads/sheets

Append the lead ledger, evidence included, to your own Google Sheet.

About this route	Detail
Returns	ok, appended (the rows written) and tab.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Optimize and up.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.

The body is JSON. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "spreadsheet": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500
    }
  },
  "required": [
    "spreadsheet"
  ]
}

curl -X POST "https://api.ansengine.co/brands/{brandId}/leads/sheets" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	ok, appended (the rows written) and tab.
400	An id in the path is not valid, or spreadsheet is not a Google Sheets URL or id.
401	No valid API key was sent.
402	This needs a higher plan: Optimize and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
403	The key belongs to a viewer seat, which can read and cannot write.
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
409	Google Sheets is not connected for this brand: connect it on the Connections page first.
422	Google refused the append. The body says why.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
503	Connections are not configured on this deployment.

POST /lead-checks

Check how AI answers mention a business: the lead form's check, from your own server.

Note

Send an Idempotency-Key header (8 to 200 characters). The same key with the same inputs returns the check it made with created false; the same key with other inputs is a 409. Each prompt is asked once on each base model and draws from your AI answers pool, and a pool that cannot fund it answers 429. It creates no client and no tracked prompt: the business lands in Pitches as a lead.

About this route	Detail
Returns	created and check: its id, its status (checking, ready or not run), its prompts, and reportUrl, the report to send the business.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Agency Launch and up.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

The body is JSON. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "business": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100
    },
    "website": {
      "type": "string",
      "minLength": 4,
      "maxLength": 200
    },
    "service": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "market": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 80
        },
        {
          "type": "null"
        }
      ]
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "questions": {
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      }
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200
    }
  },
  "required": [
    "business",
    "website",
    "service"
  ],
  "additionalProperties": false
}

curl -X POST "https://api.ansengine.co/lead-checks" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	created and check: its id, its status (checking, ready or not run), its prompts, and reportUrl, the report to send the business.
400	The body does not match the schema, the Idempotency-Key is missing, or the website is not a business's own site.
401	No valid API key was sent.
402	This needs a higher plan: Agency Launch and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
403	The key belongs to a viewer seat, which can read and cannot write.
404	This key's seat does not read the pipeline.
409	This Idempotency-Key was used with other inputs.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
503	Lead checks are not configured on this deployment.

GET /lead-checks/{checkId}

Read one lead check: its status, its counts once ready, and its report link.

About this route	Detail
Returns	check: its status, the business, its prompts and, once ready, report: the answers that came back, how many mention the business, who AI recommends and each answer with its sources.
Seat	Any seat's key, a viewer's included.
Plan	Agency Launch and up.
Rate limit	None on this route.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
checkId (path, required)	uuid	The check id.

curl "https://api.ansengine.co/lead-checks/{checkId}" \
  -H "Authorization: Bearer ak_your_key"

Status	When
200	check: its status, the business, its prompts and, once ready, report: the answers that came back, how many mention the business, who AI recommends and each answer with its sources.
400	An id in the path is not a valid id.
401	No valid API key was sent.
402	This needs a higher plan: Agency Launch and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
404	No such check for this key.

POST /pitches/benchmark

Benchmark one domain: it lands in Pitches as a prospect, ready for its audit.

Note

Send an Idempotency-Key header (8 to 200 characters). The same key with the same inputs returns the pitch it made with created false; the same key with other inputs is a 409. The same domain again on the same day (UTC) returns the pitch made that day. Nothing is asked yet: run the audit from Pitches. A key whose seat is limited to named clients does not read the pipeline and gets a 404.

About this route	Detail
Returns	created, pitch (its id, name and domain), prompts and answers (what its audit will ask, and the AI answers that draws), and prospect, the business as Pitches lists it.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Agency Launch and up.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

The body is JSON. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "minLength": 4,
      "maxLength": 200
    },
    "name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 80
        },
        {
          "type": "null"
        }
      ]
    },
    "vertical": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "scope": {
      "default": "local",
      "type": "string",
      "enum": [
        "local",
        "global"
      ]
    },
    "city": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80
    },
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 40
    },
    "country": {
      "type": "string",
      "pattern": "^[a-z]{2}$"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200
    }
  },
  "required": [
    "domain",
    "vertical"
  ],
  "additionalProperties": false
}

curl -X POST "https://api.ansengine.co/pitches/benchmark" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	created, pitch (its id, name and domain), prompts and answers (what its audit will ask, and the AI answers that draws), and prospect, the business as Pitches lists it.
400	The body does not match the schema, the Idempotency-Key is missing, or the domain is not a business's own public website.
401	No valid API key was sent.
402	This needs a higher plan: Agency Launch and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan). Or: Your AI answers left this month do not fund one audit (answers_short), the included scans an audit uses are spent (scan_quota_reached), the trial's prospect workspace is used (trial_prospect_limit), or this month's new clients and prospects are used (quota_exceeded).
403	The key belongs to a viewer seat, which can read and cannot write.
409	This Idempotency-Key was used with other inputs.
422	The vertical gives no prompt to audit on.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.

GET /brands/{brandId}/revenue-pages

Revenue by landing page in three lanes: organic, AI referral and paid.

About this route	Detail
Returns	rows (per page: organic, ai and paid sessions and revenue), totals and connected. connected is false until Google Analytics 4 is connected for the brand.
Seat	Any seat's key, a viewer's included.
Plan	Optimize and up.
Rate limit	None on this route.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.

curl "https://api.ansengine.co/brands/{brandId}/revenue-pages" \
  -H "Authorization: Bearer ak_your_key"

Status	When
200	rows (per page: organic, ai and paid sessions and revenue), totals and connected. connected is false until Google Analytics 4 is connected for the brand.
400	An id in the path is not a valid id.
401	No valid API key was sent.
402	This needs a higher plan: Optimize and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
502	Google answered with an error. The connection is fine; try again shortly.
503	Integrations are not configured on this deployment.

GET /brands/{brandId}/search-wins

Search Console drops, click through quick wins and demand without a page.

About this route	Detail
Returns	configured, site, window and wins. configured is false when Search Console reads are not set up on this deployment.
Seat	Any seat's key, a viewer's included.
Plan	Optimize and up.
Rate limit	None on this route.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.

curl "https://api.ansengine.co/brands/{brandId}/search-wins" \
  -H "Authorization: Bearer ak_your_key"

Status	When
200	configured, site, window and wins. configured is false when Search Console reads are not set up on this deployment.
400	An id in the path is not a valid id.
401	No valid API key was sent.
402	This needs a higher plan: Optimize and up. The body names the plan gate (feature) and the lowest plan id it admits (minPlan).
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
502	Search Console could not be read right now.