# RevCent MCP Guide: `CreateUserThirdPartyIntegration`

AI/MCP-focused guide for creating User Third Party Integrations in RevCent.

This document explains the `CreateUserThirdPartyIntegration` operation, the required Site Third Party Integration prerequisite, Secure Form credential handling, third-party options, third-party assets, post-creation configuration, and how to handle custom/non-native integrations using RevCent Functions.

---

## Related Documentation

AI/MCP clients should also read:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md
```

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewFunction.md
```

Related operation guides:

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| Third Party Integration Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Explains Site Third Party Integrations, User Third Party Integrations, native integrations, and custom Function-based integrations. |
| Functions Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFunction.md` | Explains how Functions can integrate with non-native third-party systems. |
| GetSiteThirdPartyIntegrations | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Lists native RevCent Site Third Party Integrations. |
| GetSiteThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Retrieves one native integration and its credential/option requirements. |
| GetUserThirdPartyIntegrations | | Lists existing connected user integrations. |
| GetUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/GetUserThirdPartyIntegration.md` | Retrieves one connected user integration and account-specific options/assets. |
| EditUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Used after creation to configure third-party options or update credentials/settings. |
| CreateSecureForm | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Securely collects third-party credentials without exposing secrets in chat. |
| CreateFunction | `https://revcent.com/documentation/markdown/mcp/operation/CreateFunction.md` | Creates a custom Function for non-native third-party integrations. |
| EditFunction | `https://revcent.com/documentation/markdown/mcp/operation/EditFunction.md` | Edits custom Function logic for non-native integrations. |

---

## Operation Summary

Operation:

```text
CreateUserThirdPartyIntegration
```

Title:

```text
Create A User Third Party Integration
```

Purpose:

```text
Create a User Third Party Integration.
```

A User Third Party Integration is the user's connected instance of a native RevCent Site Third Party Integration.

Simple model:

```text
Site Third Party Integration = RevCent-native integration definition
User Third Party Integration = user's connected/configured account for that native integration
```

A User Third Party Integration can later be used by other RevCent features such as:

- Tax Profiles,
- Shipping/tracking workflows,
- Offline/alternate payment workflows,
- AI Assistants,
- AI Voice Agents,
- other native RevCent features that require connected third-party accounts.

---

## Site Integration vs User Integration

Before creating a User Third Party Integration, AI/MCP must understand the difference.

| Concept | Meaning |
|---|---|
| Site Third Party Integration | Native RevCent integration definition. It defines provider name, integration type, credentials, and possible options. |
| User Third Party Integration | The user's connected instance of the Site Third Party Integration, with saved credentials/options. |

Important:

```text
CreateUserThirdPartyIntegration.site_third_party_integration expects a Site Third Party Integration ID.
Downstream RevCent features usually expect a User Third Party Integration ID.
```

Example:

```text
CreateTaxProfile.third_party_integration = user_third_party_integration_id
```

not:

```text
site_third_party_integration_id
```

---

## Native Integration Types

Site Third Party Integrations are native to RevCent and have an `integration_type`.

Known values:

| Type | Purpose |
|---|---|
| `ai` | Powers AI chat, AI Assistants, and AI-related features where applicable. |
| `ai_voice` | Powers voice-enabled AI Voice Agents. |
| `offline_payment` | Supports alternate/offline payments such as Sezzle, Afterpay, Affirm, Klarna, Amazon Pay, and similar providers. |
| `tax` | Calculates taxes on purchases where RevCent is responsible for tax calculation. |
| `shipping` | Tracks shipments and pulls shipment updates such as delivery status. |

AI/MCP must verify the `integration_type` before creating or using the integration.

Examples:

```text
Tax Profile needs a user integration backed by integration_type = tax.
AI Voice Agent needs an ai_voice integration where applicable.
AI Assistant needs an ai integration where applicable.
Shipping/tracking workflows need shipping integrations where applicable.
Offline payment mapping needs offline_payment integrations where applicable.
```

Do not use the wrong integration type.

---

## Input Schema

`CreateUserThirdPartyIntegration` input schema:

```text
type: object
additionalProperties: false
required:
  - name
  - site_third_party_integration
```

Only send supported fields.

---

## Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | User Third Party Integration name. Must be unique from other User Third Party Integration names. |
| `site_third_party_integration` | string | Yes | 20-character Site Third Party Integration ID. |

---

## Optional Fields

| Field | Type | Description |
|---|---:|---|
| `description` | string | Human-readable description of the user integration. |
| `enabled` | boolean | Whether the User Third Party Integration is enabled. |
| `secure_form_id` | string | 20-character Secure Form ID containing sensitive credentials. |

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `user_third_party_integration_id` | string | 20-character User Third Party Integration ID. |
| `result` | string | Result message. |

Store the returned:

```text
user_third_party_integration_id
```

This ID is used by other RevCent operations and features.

---

## Required Prerequisite: Select a Site Third Party Integration

Before calling `CreateUserThirdPartyIntegration`, AI/MCP must know which native Site Third Party Integration the user wants to connect.

Use:

```text
GetSiteThirdPartyIntegrations
```

to list available native integrations.

Then use:

```text
GetSiteThirdPartyIntegration
```

to retrieve the exact integration and inspect:

- integration type,
- credential requirements,
- credential field IDs,
- required credential fields,
- option requirements,
- third-party option IDs,
- option field IDs,
- whether option values are static or pulled from the third party after credentials are saved.

Correct prerequisite flow:

```text
1. User asks to connect a third-party provider.
2. Use GetSiteThirdPartyIntegrations.
3. Find the native Site Third Party Integration.
4. Confirm integration_type matches the intended feature.
5. Use GetSiteThirdPartyIntegration.
6. Review required credentials and third_party_options.
7. Create Secure Form for credentials.
8. User completes Secure Form.
9. Call CreateUserThirdPartyIntegration.
```

Do not guess the Site Third Party Integration ID.

---

## Secure Credential Requirement

Third-party credentials are sensitive.

AI/MCP must not ask users to paste API keys, tokens, passwords, usernames, secrets, private keys, or provider credentials into chat.

Use:

```text
CreateSecureForm
```

For third-party integrations, create the Secure Form with:

```json
{
  "form_source": "third_party_integration",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Where:

```text
form_source_id = Site Third Party Integration ID
```

The Secure Form returns:

- `secure_form_id`,
- `form_url`,
- `completed`,
- `expiration_date_unix`.

The user opens the `form_url`, enters credentials securely, and tells the AI/MCP client when the form is complete.

Then include:

```text
secure_form_id
```

in `CreateUserThirdPartyIntegration`.

Important:

```text
Secure Forms expire after 1 hour.
```

If the Secure Form expires, create a new one.

---

## Example Request

```json
{
  "name": "Main Tax Provider",
  "description": "Tax provider integration used for RevCent Tax Profiles.",
  "enabled": false,
  "site_third_party_integration": "SSSSSSSSSSSSSSSSSSSS",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Recommended:

```text
Create the user integration disabled until credentials and required third_party_options are verified.
```

Then enable later with `EditUserThirdPartyIntegration` after setup is complete.

---

## Field Details

### `name`

The name must be unique among User Third Party Integrations.

Use names that identify provider, brand, store, purpose, or environment.

Good examples:

```text
Main Tax Provider
Brand A Tax Integration
Main Shipping Tracking Provider
WooCommerce Alternate Payment - Sezzle
Production AI Provider
Voice Agent Provider - Main
```

Poor examples:

```text
Integration
Test
Third Party
Provider
```

---

### `description`

Use the description to explain:

- provider,
- purpose,
- integration type,
- shop/brand/campaign context,
- production vs test usage,
- where it will be used,
- whether post-creation options are still required.

Example:

```text
User tax integration for subscription renewal and trial expiration tax calculation. Created from native tax site integration. Requires post-creation option selection before enabling.
```

---

### `enabled`

Whether the User Third Party Integration is active.

Best practice:

```text
Use enabled = false until credentials and required options are verified.
```

Use `enabled = true` only when the integration is ready to be used by dependent RevCent features.

---

### `site_third_party_integration`

The 20-character Site Third Party Integration ID.

This must come from:

```text
GetSiteThirdPartyIntegrations
```

or:

```text
GetSiteThirdPartyIntegration
```

Do not use a User Third Party Integration ID in this field.

---

### `secure_form_id`

The 20-character Secure Form ID containing credentials.

Use only after the user completes the Secure Form.

Do not include raw credential values in the request.

---

## Third Party Options

Some Site Third Party Integrations have:

```text
third_party_options
```

These are provider-specific configuration options that must be saved after creating the User Third Party Integration.

The live operation description is explicit:

```text
After creating a user third party integration, you may need to edit the integration to provide any third_party_options that may be required.
```

If the Site Third Party Integration has `third_party_options`, the flow does not end at creation.

Correct flow:

```text
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
Review account-specific options/assets
    ↓
Choose required option values
    ↓
EditUserThirdPartyIntegration with third_party_options
    ↓
GetUserThirdPartyIntegration again to verify saved options
```

If the Site Third Party Integration has no `third_party_options`, no post-creation option edit is required.

---

## Third Party Assets / Account-Specific Options

Some option fields are select fields whose values come from the third party provider's API.

These are third-party assets.

Examples of possible provider-specific assets:

- accounts,
- stores,
- locations,
- warehouses,
- tax nexus entities,
- shipping services,
- payment provider accounts,
- voice numbers,
- AI models,
- provider-specific resources.

Important behavior:

```text
If an option field uses third-party assets, RevCent can only retrieve those options after credentials are saved.
```

Correct flow:

```text
1. Review Site Third Party Integration.
2. Create Secure Form.
3. Create User Third Party Integration with credentials.
4. Use GetUserThirdPartyIntegration.
5. RevCent pulls account-specific third-party assets/options.
6. User chooses the correct option values.
7. Use EditUserThirdPartyIntegration to save those choices.
```

Do not guess third-party asset values.

Do not choose an option without user confirmation when multiple provider assets exist.

---

## Option Field Types

Third-party option fields can be:

| Field Type | Meaning |
|---|---|
| `input` | User provides a value. |
| `select` | User selects one or more values from available options. |

Select fields can be:

| Select Setting | Meaning |
|---|---|
| `third_party_asset = false` | Options are statically provided in the Site Third Party Integration schema. |
| `third_party_asset = true` | Options are pulled from the third-party API after credentials are saved. |
| `multiple = true` | More than one selected value can be saved. |
| `multiple = false` | Only one selected value should be saved. |

AI/MCP must preserve option and field IDs exactly.

---

## Saving Third Party Options

Use:

```text
EditUserThirdPartyIntegration
```

with `third_party_options`.

Example shape:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "third_party_options": [
    {
      "id": "option_id_from_site_integration",
      "fields": [
        {
          "id": "field_id_from_site_integration",
          "value": [
            "selected_or_entered_value"
          ]
        }
      ]
    }
  ]
}
```

Rules:

- `id` at option level must be the option ID from the Site Third Party Integration.
- `id` at field level must be the field ID from the option's fields array.
- `value` is always an array.
- For single-value fields, use an array containing one value.
- For multi-select fields, use an array containing all selected values.
- Do not invent IDs.
- Do not guess values pulled from third-party assets.
- Verify after editing with `GetUserThirdPartyIntegration`.

---

## Full Native Integration Creation Workflow

Recommended AI/MCP workflow:

```text
1. Confirm the user wants to create/connect a third-party integration.
2. Ask what provider/purpose they need.
3. Use GetSiteThirdPartyIntegrations.
4. Select the correct native Site Third Party Integration.
5. Confirm integration_type matches the intended use.
6. Use GetSiteThirdPartyIntegration to inspect credentials and options.
7. Explain what credentials are needed, without asking for secret values in chat.
8. Use CreateSecureForm with form_source = third_party_integration and form_source_id = site_third_party_integration ID.
9. Give the user the Secure Form URL.
10. Wait for user to confirm the Secure Form is completed.
11. Call CreateUserThirdPartyIntegration with name, description, enabled state, site_third_party_integration, and secure_form_id.
12. Store returned user_third_party_integration_id.
13. Use GetUserThirdPartyIntegration.
14. If third_party_options exist:
        a. Review account-specific options/assets.
        b. Have user choose required options.
        c. Call EditUserThirdPartyIntegration with third_party_options.
        d. Use GetUserThirdPartyIntegration again to verify.
15. Enable the integration only when credentials/options are complete.
16. Use the User Third Party Integration ID in the dependent RevCent feature.
```

---

## Integration-Type-Specific Notes

### Tax Integrations

For Tax Profiles, the User Third Party Integration must be backed by:

```text
integration_type = tax
```

Use the created user integration ID in:

```text
CreateTaxProfile.third_party_integration
```

Do not use a Site Third Party Integration ID.

---

### Shipping Integrations

For shipping/tracking integrations, verify:

```text
integration_type = shipping
```

Use the connected integration in the relevant shipping/tracking workflows where RevCent supports native provider behavior.

If the third-party shipping/fulfillment provider is not native, use Functions/webhooks.

---

### Offline Payment Integrations

For alternate payment integrations, verify:

```text
integration_type = offline_payment
```

Use the connected integration when mapping supported alternate payment methods from shops or when RevCent supports details/refund workflows for that provider.

---

### AI Integrations

For AI features, verify:

```text
integration_type = ai
```

These integrations may be used to power AI Assistants or AI-related features where applicable.

Before creating an AI Assistant, AI/MCP should confirm an AI integration exists where required.

---

### AI Voice Integrations

For voice features, verify:

```text
integration_type = ai_voice
```

These integrations may be used to power AI Voice Agents where applicable.

---

## If No Native Site Integration Exists

Site Third Party Integrations are native RevCent integrations.

However, a missing native Site Third Party Integration does not mean the user cannot integrate that provider with RevCent.

If no native integration exists, use RevCent Functions and related tools to create a custom integration.

Correct rule:

```text
Native provider exists:
    Use Site Third Party Integration + User Third Party Integration.

Native provider does not exist:
    Use Functions, webhooks, Function URLs, schedules, API/AI Functions, Email Template Functions, Payment Profile Functions, Key Values, and RevCent API/MCP tools.
```

---

## Custom Integration Via Functions

RevCent Functions can integrate with virtually any third-party system that supports APIs, webhooks, or HTTP callbacks.

Functions can:

- send RevCent event data to external APIs,
- receive third-party webhooks,
- create custom endpoints,
- run scheduled syncs,
- generate custom Email Template data,
- provide AI Assistant custom tools,
- provide AI Voice Agent pre-agent logic,
- run custom payment flow logic,
- store and use encrypted values,
- read and update Key Values,
- call external APIs.

Common Function-based integration patterns:

| Need | Function Pattern |
|---|---|
| Send Sales to CRM | Account Event Function on sale events. |
| Sync customers to helpdesk | Account Event Function on customer created/updated. |
| Receive fulfillment updates | Webhook Function. |
| Build custom partner endpoint | Function URL. |
| Sync inventory nightly | Schedule Function. |
| Add custom email personalization | Email Template Function. |
| Add AI Assistant custom lookup | API/AI Function. |
| Filter AI Voice Agent calls | Filter Function. |
| Add custom risk check | Payment Profile Function. |
| Push subscription failures to retention tool | Account Event Function on subscription/renewal events. |

---

## When to Prefer Functions

Use Functions when:

- no native Site Third Party Integration exists,
- the third-party system has an API,
- the third-party system sends webhooks,
- the user needs custom business logic,
- the user needs custom AI tools,
- the user needs custom payment routing logic,
- the user needs custom email data,
- the user needs scheduled sync/reporting,
- the integration is highly merchant-specific.

Do not force a User Third Party Integration if RevCent has no native Site Third Party Integration for that provider.

Use Functions instead.

---

## Function Security for Custom Integrations

When building custom integrations with Functions:

- validate inbound webhook signatures,
- use shared secrets,
- check headers,
- check IP allowlists where possible,
- use idempotency keys to avoid duplicate processing,
- store secrets in encrypted values or approved secure configuration,
- do not hardcode sensitive secrets in unsafe places,
- avoid returning sensitive data from public Function URLs,
- log only safe diagnostic information,
- limit what AI tools can do,
- use filter Functions to avoid unsafe automation.

Custom integrations are powerful, but they require careful security.

---

## When Not to Use CreateUserThirdPartyIntegration

Do not use `CreateUserThirdPartyIntegration` when:

- no native Site Third Party Integration exists for the provider,
- the user wants a fully custom API/webhook integration,
- the integration is only a one-off Function URL or webhook,
- the desired provider is not represented by `GetSiteThirdPartyIntegrations`,
- the task is better handled by a Function.

Use Functions in those cases.

---

## Validation Checklist Before Creating

Before calling `CreateUserThirdPartyIntegration`, verify:

- user explicitly wants to connect a native third-party integration,
- Site Third Party Integration ID is known,
- integration type matches intended use,
- required credentials were reviewed,
- Secure Form was created,
- user completed the Secure Form if credentials are needed,
- `secure_form_id` is not expired,
- name is unique,
- description is useful,
- enabled state is intentional,
- third-party options were reviewed,
- post-creation option configuration is planned if options exist,
- user understands the User Third Party Integration ID will be used by other RevCent features.

---

## Validation Checklist After Creating

After creation, verify:

- `user_third_party_integration_id` was returned,
- `GetUserThirdPartyIntegration` succeeds,
- credentials appear saved,
- enabled state is correct,
- underlying Site Third Party Integration is correct,
- integration type is correct,
- required third-party options are saved or pending,
- remote third-party assets/options were retrieved if applicable,
- dependent RevCent feature can now use the integration.

---

## Common Mistakes to Avoid

Do not:

- ask users to paste credentials in chat,
- create an integration without checking the Site Third Party Integration first,
- confuse Site Third Party Integration ID with User Third Party Integration ID,
- use a User Third Party Integration ID in `site_third_party_integration`,
- forget to use Secure Form,
- use an expired Secure Form,
- skip `GetUserThirdPartyIntegration` after creation,
- skip required `third_party_options`,
- guess third-party asset selections,
- enable an incomplete integration,
- use the wrong `integration_type`,
- create a native integration when no native Site Third Party Integration exists,
- assume no native integration means integration is impossible,
- forget Functions can implement non-native third-party integrations.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| User wants to connect a native provider | Use `CreateUserThirdPartyIntegration`. |
| Need available native providers | Use `GetSiteThirdPartyIntegrations`. |
| Need credential/option schema | Use `GetSiteThirdPartyIntegration`. |
| Need to collect credentials | Use `CreateSecureForm`. |
| Secure Form completed | Use `secure_form_id` in `CreateUserThirdPartyIntegration`. |
| Site integration has options | Retrieve new user integration, then use `EditUserThirdPartyIntegration`. |
| Option values come from third-party assets | Save credentials first, then retrieve with `GetUserThirdPartyIntegration`. |
| Need to enable after testing | Use `EditUserThirdPartyIntegration`. |
| Feature requires a specific type | Verify `integration_type`. |
| No native site integration exists | Use Functions/custom integration patterns. |
| Need custom webhook receiver | Use a Webhook Function. |
| Need custom API endpoint | Use a Function URL. |
| Need custom AI tool | Use an API/AI Function. |
| Need scheduled sync | Use a Schedule Function. |

---

## Final AI/MCP Instruction

Use `CreateUserThirdPartyIntegration` to create the user's connected instance of a native RevCent Site Third Party Integration.

First list and inspect Site Third Party Integrations. Confirm the selected site's `integration_type` matches the intended RevCent feature. Use Secure Form for credentials; never collect secrets in chat. After creation, retrieve the new User Third Party Integration. If the native Site Third Party Integration has `third_party_options`, configure those options with `EditUserThirdPartyIntegration`. If option values depend on third-party assets, credentials must be saved first so RevCent can retrieve the account-specific options.

If a native Site Third Party Integration does not exist for the provider, do not force `CreateUserThirdPartyIntegration`. Instead, implement the integration using RevCent Functions, webhooks, Function URLs, schedules, API/AI Functions, Email Template Functions, Payment Profile Functions, Key Values, and RevCent API/MCP operations.


---
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.