beaconcrm_create_record

WRITE: create ONE new record of the given type in the live Beacon database. Not idempotent: calling it twice creates two records (use beaconcrm_upsert_record to avoid duplicates). Beacon workflows may run as a result. Invalid field values are rejected with the rule that failed. POST /entity/{entity}.

Argument	Type	Description
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
fields*	object	Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {"type": ["Donation"], "customer": [1725]}); emails are [{"email", "is_primary"}]; currency is {"value", "currency"}; dates are ISO strings.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity",
    "fields"
  ],
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "fields": {
      "type": "object",
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  }
}

beaconcrm_delete_record

WRITE, DESTRUCTIVE: delete ONE record. Beacon keeps deleted records as 'archived' (listable with archived=true), but this server has no restore tool, so treat the deletion as irreversible. Related data that depends on the record may be affected. It is sent once and never retried. DELETE /entity/{entity}/{id}.

destructive

Argument	Type	Description
id*	integer	Id of the record to delete.
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity",
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Id of the record to delete.",
      "exclusiveMinimum": 0
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    }
  }
}

beaconcrm_filter_records

Search records of one type with Beacon filter conditions (read-only; it uses POST because the filter is a body). Each condition is {"field", "operator", "value"}. Operators by field type: text == != starts_with ends_with contains not_contains null not_null; select (value is an array) contains not_contains in not_in null not_null; number == != > < null not_null; date date_on date_after date_before date_between (value e.g. "2026-01-01", "last_month", or ["2026-01-01","2026-06-01"]); checkbox == true; point-to-record (value is an array of ids) contains not_contains. Location parts: address.city etc.; emails: emails.email. Conditions can nest as {"filter_conditions": [...], "filter_strictness": "all"|"any"}. Example: [{"field":"emails.email","operator":"==","value":"[email protected]"}]. POST /entities/{entity}/filter.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
sort_by	string	Field key to sort by, e.g. created_at.
archived	boolean	true = list deleted (archived) records instead of active ones.
per_page	integer	Results per page, 1-100 (default 25).
populate

beaconcrm_get_record

One record by type and id, with all its fields. GET /entity/{entity}/{id}.

read-only

Argument	Type	Description
id*	integer	Record id.
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
populate	boolean	Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity",
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Record id.",
      "exclusiveMinimum": 0
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "populate": {
      "type": "boolean",
      "description": "Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted."
    }
  }
}

beaconcrm_list_exports

List recent export jobs with status, progress (100 = complete) and, when complete, a signed download url. Pass entity_export_id to check one job started by beaconcrm_trigger_export. GET /entity_exports.

read-only

Argument	Type	Description
entity_export_id	any	Only this export (the id returned by beaconcrm_trigger_export).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "entity_export_id": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "exclusiveMinimum": 0
        },
        {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{1,64}$"
        }
      ],
      "description": "Only this export (the id returned by beaconcrm_trigger_export)."
    }
  }
}

beaconcrm_list_record_types

List the record types of this Beacon account (people, organisations, payments, custom types, ...) with their fields (keys, types, options). Call this first: the keys are what the other tools take as `entity` and as field names. GET /entity_types.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

beaconcrm_list_records

List records of one type (for example person, organization, payment), one page at a time. Use beaconcrm_filter_records to search by field values. GET /entities/{entity}.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
sort_by	string	Field key to sort by, e.g. created_at.
archived	boolean	true = list deleted (archived) records instead of active ones.
per_page	integer	Results per page, 1-100 (default 25).
populate	boolean	Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted.
sort_direction	string	Sort direction (default: Beacon's default order).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "sort_by": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.]{1,100}$",
      "description": "Field key to sort by, e.g. created_at."
    },
    "archived": {
      "type": "boolean",
      "description": "true = list deleted (archived) records instead of active ones."
    },
    "per_page": {
      "type": "integer",
      "maximum": 100,
      "description": "Results per page, 1-100 (default 25).",
      "exclusiveMinimum": 0
    },
    "populate": {
      "type": "boolean",
      "description": "Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted."
    },
    "sort_direction": {
      "enum": [
        "asc",
        "desc"
      ],
      "type": "string",
      "description": "Sort direction (default: Beacon's default order)."
    }
  }
}

beaconcrm_list_users

List the users of the Beacon account (id, role, name, email). Use the inner user.id for 'link to a user' fields. GET /users.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
per_page	integer	Results per page, 1-100 (default 25).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "per_page": {
      "type": "integer",
      "maximum": 100,
      "description": "Results per page, 1-100 (default 25).",
      "exclusiveMinimum": 0
    }
  }
}

beaconcrm_trigger_export

WRITE: start an export job from an existing export template (created in Beacon). Returns the new export's id with status in_progress; then poll beaconcrm_list_exports with that id until progress is 100 and it carries a download url. Each call starts another job. POST /entity_export/trigger.

Argument	Type	Description
entity_export_template_id*	integer	Id of the export template (shown in the Beacon URL when you view the template).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity_export_template_id"
  ],
  "properties": {
    "entity_export_template_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Id of the export template (shown in the Beacon URL when you view the template).",
      "exclusiveMinimum": 0
    }
  }
}

beaconcrm_update_record

WRITE: change fields of ONE existing record. Only the fields you pass are changed; a select or reference field passed as an empty array [] is CLEARED, removing its existing values. The previous values are not kept by this tool. Beacon workflows may run as a result. PATCH /entity/{entity}/{id}.

destructive

Argument	Type	Description
id*	integer	Record id.
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
fields*	object	Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {"type": ["Donation"], "customer": [1725]}); emails are [{"email", "is_primary"}]; currency is {"value", "currency"}; dates are ISO strings.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity",
    "id",
    "fields"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Record id.",
      "exclusiveMinimum": 0
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "fields": {
      "type": "object",
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  }
}

beaconcrm_upsert_record

WRITE: create a record, or update the existing one whose key field matches. `primary_field_key` names the field used to find the match (for example "emails" for a person, or "external_id"); `fields` must contain a value for it. If a record matches it is UPDATED with the given fields (an empty array leaves an existing value untouched on upsert); otherwise a new record is created. Beacon workflows may run as a result. PUT /entity/{entity}/upsert.

destructive

Argument	Type	Description
entity*	string	Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types.
fields*	object	Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {"type": ["Donation"], "customer": [1725]}); emails are [{"email", "is_primary"}]; currency is {"value", "currency"}; dates are ISO strings.
primary_field_key*	string	Field key used to match an existing record, e.g. emails or external_id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entity",
    "primary_field_key",
    "fields"
  ],
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "fields": {
      "type": "object",
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "primary_field_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.]{1,100}$",
      "description": "Field key used to match an existing record, e.g. emails or external_id."
    }
  }
}

Beacon CRM MCP by usefulapi

Try it

beaconcrm_create_record

Beacon CRM MCP by usefulapi

Try it

beaconcrm_create_record

Tools (11)