# From a lead to a brand

Audit and check a prospect through the API, then create their brand with POST /v1/projects: the audit becomes its plan and the check its first AI visibility history.

Source: https://magistermarketing.com/docs/api/leads-to-brands

Audit a prospect and check their AI visibility through the API. When they sign, create their brand in your organization with the results already in it, and manage it in Magister from then on.

### 1. Audit and check the prospect

```bash
curl -X POST https://api.magistermarketing.com/v1/audits/site \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://acme.com"}'

curl -X POST https://api.magistermarketing.com/v1/ai-visibility/check \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'
```

Each answers with a `job_id`. Keep both; they are billed in API credits like any job.

### 2. Create the brand when they sign

```bash
curl -X POST https://api.magistermarketing.com/v1/projects \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"website_url": "https://acme.com", "name": "Acme", "from_jobs": ["<audit job_id>", "<check job_id>"]}'
```

```json
{
  "data": {
    "status": "created",
    "message": "Added Acme. Its marketing plan is being built from the audit you already ran, and its agent is being set up.",
    "project_id": "5b2c1d7e-8a4f-4e2b-9c1d-7e8a4f4e2b9c",
    "name": "Acme",
    "website_url": "https://acme.com/",
    "audit": {
      "job_id": "<audit job_id>",
      "plan_id": "9c1d7e8a-4f4e-4b9c-8d7e-8a4f4e2b9c1d",
      "carried": true
    },
    "ai_visibility": {
      "job_id": "<check job_id>",
      "imported": true,
      "set_id": "1d7e8a4f-4e2b-4c1d-9e8a-4f4e2b9c1d7e",
      "round_id": "7e8a4f4e-2b9c-4d7e-8a4f-4e2b9c1d7e8a",
      "answers": 9
    }
  },
  "credits_charged": 0,
  "request_id": "8f14e45f-ceea-4e7a-9b1c-1f2a3b4c5d6e"
}
```

The brand is set up as if it had been added in Magister, with its plan, its agent and its place in your billing:

- **The audit becomes its plan.** No second audit runs. Magister builds the marketing plan from it in a few minutes, billed on your plan's credits like any new brand's first plan, and the audit's AI visibility round carries over with it.
- **The check becomes its first AI visibility history.** It arrives as a set with the check's questions and engines and one round dated to when the check ran, with every answer, score, mention, position, competitor and source. From then on Magister tracks the set weekly, billed on your plan. An engine that Magister's tracking asks with web search (OpenAI, Claude, Grok) but that your check asked without it is left out, since there is nothing to compare with.

### The rules

- `from_jobs` takes your organization's finished jobs, started by any of its keys: at most one site audit and one AI visibility check, both of the brand's own site.
- A job counts as finished once it reads `succeeded`: poll `GET /v1/jobs/{job_id}` with the key that started it (an audit job is settled when it is read), and a job another of your keys started settles by itself within a few minutes. Until then it answers **409** `not_ready`. A failed job, or a job of another site, answers **422**.
- An audit becomes one brand's plan, and a check one brand's history, once: carried into another brand, either answers **409** `conflict`.
- Sending the same request again never adds a second brand. It answers **200** with the brand it created, with the audit as its plan and the check carried in (once). A brand someone else already added for the site gets nothing carried into it (`carried` and `imported` are `false`, reason `brand_exists`). A brand's id is returned only when the key's creator can open it; otherwise it answers **409** `conflict`.
- The key needs the `write` scope, and its creator must be an owner or admin of the organization, or a member allowed to add brands (**403** `not_authorized` otherwise).

### What it costs

Creating the brand costs no API credits. The brand is billed on your plan like any other.

- A brand your plan already includes is created right away, and so is any brand of a paid plan Magister made complimentary.
- Any other brand answers **402** `payment_required` with its `charge` (`amount_cents`, `interval`) and `add_brand_url`, and nothing is added or charged: an API key never agrees to a price. Add the brand at `add_brand_url` instead; the audit and check stay in your API jobs.
- An organization on Free, or with no active plan, answers **402** `payment_required` with `upgrade_url`.