# RevCent MCP Guide: `CreateCustomer`

AI/MCP-focused guide for creating a RevCent Customer.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Customer Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomer.md` | Broad overview of Customer records, customer lifecycle, related records, customer cards, groups, and customer-facing AI safety. |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` | Retrieve the Customer before and after customer mutation operations. |
| SearchCustomers | `https://revcent.com/documentation/markdown/mcp/operation/SearchCustomers.md` | Locate a Customer when the Customer ID is unknown. |
| GetCustomers | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomers.md` | Bounded operational Customer retrieval. Not for reporting/metrics. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for customer reporting, metrics, aggregation, and data mining. |


---

## Operation Summary

Operation:

```text
CreateCustomer
```

Title:

```text
Create A Customer
```

Purpose:

```text
Create a customer prior to any purchase attempts.
```

Useful when creating prospects before a purchase attempt.

Important RevCent behavior:

```text
RevCent automatically creates a customer during an initial Sale if the customer does not already exist.
```

Do not create Customers unnecessarily before every Sale. Use `CreateCustomer` when the business explicitly wants a customer/prospect record before purchase, card attachment, customer group assignment, support workflow, or other lifecycle action.

---

## When to Use

Use `CreateCustomer` when:

- a prospect/customer should exist before a purchase attempt,
- support needs to create a customer record manually,
- the customer will be attached to a payment card after creation,
- the customer should be associated with a specific Campaign,
- the user wants to add metadata or an internal customer ID before commerce begins,
- the customer will be added to one or more Customer Groups.

Recommended duplicate prevention:

```text
SearchCustomers by email / phone / internal_customer_id
    ↓
If no existing match, CreateCustomer
    ↓
GetCustomer to verify
```

---

## Input Schema

Required top-level fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `campaign` | string | Yes | Existing Campaign ID or Campaign name within RevCent. |
| `customer` | object | Yes | Customer details. The customer object receives first priority when creating a new Customer. |

Optional top-level fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `bill_to` | object | No | Billing information. If omitted, the `customer` object is used. Useful when adding a credit card with separate billing info. |
| `payment` | object | No | Payment method to add upon customer creation. |
| `internal_customer_id` | string | No | Optional third-party/internal customer ID for records. |
| `metadata` | array | No | Metadata name/value pairs. |

---

## `customer` Object

Required inside `customer`:

| Field | Type | Required |
|---|---:|---:|
| `first_name` | string | Yes |
| `last_name` | string | Yes |
| `email` | string/email | Yes |

Optional customer fields:

```text
address_line_1
address_line_2
city
state
zip
country
company
phone
```

`country` should be the three-letter ISO 3166-1 alpha-3 country code when provided.

Example:

```json
{
  "campaign": "Default Campaign",
  "customer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "555-555-5555",
    "address_line_1": "123 Main St",
    "city": "Miami",
    "state": "FL",
    "zip": "33101",
    "country": "USA"
  }
}
```

---

## `bill_to` Object

Use `bill_to` when billing information differs from the Customer details.

Fields:

```text
first_name
last_name
address_line_1
address_line_2
city
state
zip
country
company
email
phone
```

When `bill_to` is present, `first_name`, `last_name`, and `email` are required inside `bill_to`.

If `bill_to` is omitted, RevCent uses the `customer` object as billing information.

---

## Optional Payment Method on Creation

`payment.credit_card` can be included to create and attach a card at the same time as the Customer.

Fields:

| Field | Type | Description |
|---|---:|---|
| `card_number` | string | Full card number, digits only. |
| `exp_month` | integer | Expiration month as one or two digit integer. |
| `exp_year` | integer | Expiration year as two digit integer. |
| `card_code` | string | Card code, digits only. |

Security rule:

```text
Only collect and submit card data through secure, PCI-appropriate flows.
```

If a Secure Form or Customer Portal flow is available, prefer secure collection rather than exposing raw card details in a public AI conversation.

---

## Metadata

Metadata uses name/value pairs:

```json
[
  {
    "name": "source",
    "value": "support_chat"
  }
]
```

Limits:

| Field | Limit |
|---|---|
| `name` | 1 to 100 characters |
| `value` | 1 to 255 characters |

Do not store card data, secrets, or sensitive authentication values in metadata.

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `customer_id` | 20-character ID returned by the operation. |
| `result` | Result message. |


---

## Recommended Workflow

```text
1. Confirm campaign and required customer fields.
2. SearchCustomers by email/phone/internal ID if duplication is possible.
3. Confirm whether payment data should be added during creation.
4. Use a secure card collection flow if card data is needed.
5. Call CreateCustomer.
6. Use GetCustomer to verify.
7. Add customer to groups or attach cards only when explicitly requested.
```

---

## Customer-Facing AI Verification Warning

Customer operations can expose or modify sensitive customer, contact, address, payment, group, purchase, subscription, trial, refund, fraud, chargeback, note, and lifecycle context.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

AI/MCP should verify that the visitor is actually the customer, or is otherwise authorized, before providing information, modifying customer data, adding cards, changing status, or changing group membership.

Recommended rule:

```text
Do not act on a Customer record in a public-facing flow based only on visitor-provided input.
```

Use a secondary value from the retrieved RevCent Customer record, such as customer email, customer phone, or another record-backed value.

Safe customer-facing flow:

```text
Visitor provides customer/account input
    ↓
AI locates/retrieves the Customer
    ↓
AI verifies a secondary value from the retrieved Customer record
    ↓
AI confirms the requested action
    ↓
Only then performs the operation
```

For consequential actions, require explicit confirmation immediately before running the operation.


---

## Reporting Guidance

This operation is not a reporting or analytics operation.

Do not use customer mutation operations or customer lookup/search operations for:

- reporting,
- metrics,
- aggregation,
- data mining,
- segmentation reports,
- customer lifetime value reports,
- customer counts,
- broad analysis,
- bulk retrieval.

Use:

```text
BigQueryRunQuery
```

for those purposes.

If AI/MCP intended to use operational customer actions or lookup actions for reporting and then realizes `BigQueryRunQuery` is correct, it does not need to tell the user. It should simply run `BigQueryRunQuery`.


---

## Common Mistakes to Avoid

Do not:

- create duplicates without searching first,
- create a Customer without a clear Campaign,
- assume `CreateCustomer` is required before every Sale,
- collect raw card data in unsafe public chat,
- store secrets or card data in metadata,
- add payment data unless explicitly requested and securely collected.

---

## Final AI/MCP Instruction

Use `CreateCustomer` to create a customer before purchase attempts when explicitly needed. Required fields are `campaign` and `customer`; the `customer` object requires `first_name`, `last_name`, and `email`.

RevCent can automatically create customers during initial Sales, so do not create customer records unnecessarily.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.