---
title: "corestack_agency_referral_create"
url: https://docs.corefinity.com/mcp/tools/corestack_agency_referral_create
type: tool
last_updated: 2026-11-13
feature: agency
related:
  - https://docs.corefinity.com/api/reference/agency/create-agency-referral.md
  - https://docs.corefinity.com/guides/agencies/agency-portal.md
---
# corestack_agency_referral_create

**Refer a lead.** Refer a lead to Corefinity for your agency. Corefinity's sales team is told at once. Scope: write.

- Scope: `write`
- Runs as a task: no

## When to use it

Refer a lead to Corefinity for your agency, as the Partner Referrals form in the Control Panel does and
`POST /api/agency/referrals`. The referral is your agency's. Corefinity's sales team is emailed and told in Slack as soon
as it is saved, so confirm the details with the person first. Answers the referral as corestack_agency_referral_get.

## Inputs

- `company_name` (string, up to 255 characters, required)
- `website_url` (string, up to 255 characters, required): the lead's website, such as `example.com` or
  `https://www.example.com` (`http` or `https` only).
- `main_contact_name` (string, up to 255 characters)
- `main_contact_email` (string, up to 255 characters): an address whose domain receives mail.
- `main_contact_mobile` (string, up to 32 characters): checked together with `main_contact_mobile_country`, as the
  form checks them, and stored in international form.
- `main_contact_mobile_country` (two letters, such as `GB`): the mobile number's country.
- `current_provider` (string, up to 255 characters): who hosts them today.
- `current_cost` (number, 0 or more): what they pay today.
- `contact_lead` (boolean): Corefinity may contact the lead directly.
- `preferred_contact_method` (`email` or `phone`)
- `notes` (string)

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "company_name": {
      "maxLength": 255,
      "type": "string"
    },
    "contact_lead": {
      "description": "Corefinity may contact the lead directly.",
      "type": "boolean"
    },
    "current_cost": {
      "minimum": 0,
      "type": "number"
    },
    "current_provider": {
      "maxLength": 255,
      "type": "string"
    },
    "main_contact_email": {
      "maxLength": 255,
      "type": "string"
    },
    "main_contact_mobile": {
      "maxLength": 32,
      "type": "string"
    },
    "main_contact_mobile_country": {
      "description": "ISO country of the mobile number, e.g. GB.",
      "maxLength": 2,
      "minLength": 2,
      "type": "string"
    },
    "main_contact_name": {
      "maxLength": 255,
      "type": "string"
    },
    "notes": {
      "maxLength": 65535,
      "type": "string"
    },
    "preferred_contact_method": {
      "enum": [
        "email",
        "phone"
      ],
      "type": "string"
    },
    "website_url": {
      "maxLength": 255,
      "type": "string"
    }
  },
  "required": [
    "company_name",
    "website_url"
  ],
  "type": "object"
}
```

## Refusals

- `forbidden`: your roles do not let you create partner referrals.
- `invalid_arguments`: on the field named, with the form's message (for example a website that is not a web address,
  or a mobile number that does not fit its country).
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_agency_referral_create",
  "arguments": {
    "company_name": "Example Ltd",
    "website_url": "example.com",
    "main_contact_name": "Sam Smith",
    "main_contact_email": "sam@example.com",
    "preferred_contact_method": "email",
    "notes": "Moving to Corefinity this quarter."
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_agency_referral_create with company_name Example Ltd, website_url example.com, main_contact_name Sam Smith, main_contact_email sam@example.com, preferred_contact_method email, notes Moving to Corefinity this quarter.. (Refer a lead.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/agency/referrals](https://docs.corefinity.com/api/reference/agency/create-agency-referral.md)
- Guide: [Agency portal](https://docs.corefinity.com/guides/agencies/agency-portal.md)
