# RevCent MCP Guide: `GetUserThirdPartyIntegration`

AI/MCP-focused guide for retrieving a User Third Party Integration in RevCent.

This document explains the `GetUserThirdPartyIntegration` operation, how it is used to retrieve saved credentials/options, how it exposes account-specific third-party assets/options after credentials are saved, and when it is appropriate to edit the integration with selected options/assets.

---

## 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/CreateUserThirdPartyIntegration.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 Function-based custom integrations. |
| CreateUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserThirdPartyIntegration.md` | Explains how user integrations are created and why post-creation option configuration may be required. |
| EditUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Used to save selected third-party options/assets or update settings after explicit user request. |
| GetSiteThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Shows the native integration's credential and option schema. |
| GetUserThirdPartyIntegrations | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Lists existing user integrations when the specific integration ID is unknown. |
| CreateSecureForm | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Securely collects credentials before account-specific assets/options can be retrieved. |

---

## Operation Summary

Operation:

```text
GetUserThirdPartyIntegration
```

Title:

```text
Get A User Third Party Integration
```

Purpose:

```text
Retrieve the details of a specific user third party integration.
```

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

Use `GetUserThirdPartyIntegration` to retrieve:

- integration name,
- description,
- enabled state,
- saved credential identifiers,
- saved option identifiers/values,
- associated Site Third Party Integration,
- integration type,
- required credential schema,
- option schema,
- account-specific third-party options/assets where applicable.

---

## Core Use Case

`GetUserThirdPartyIntegration` is especially important after creating a User Third Party Integration.

Some native Site Third Party Integrations define `third_party_options`. These options may require values that are specific to the user's account with the third party.

Those account-specific values may not be available until credentials have been saved.

Correct flow:

```text
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
Review saved credentials
    ↓
Review third_party_options and account-specific assets/options
    ↓
User chooses required values
    ↓
EditUserThirdPartyIntegration saves selected options/assets
    ↓
GetUserThirdPartyIntegration verifies saved options
```

---

## Important Rule: When to Edit Options/Assets

Updating third-party options/assets should only be done in two cases:

1. **Initial integration setup**
   - immediately after `CreateUserThirdPartyIntegration`,
   - when the integration requires `third_party_options`,
   - after account-specific options/assets have been retrieved,
   - after the user chooses the correct option values.

2. **Explicit user-requested settings change**
   - when the user clearly asks to change the integration's options/settings,
   - when the user wants to switch provider account/location/store/service/model/asset,
   - when credentials/options have changed,
   - when the user confirms the existing settings should be modified.

Do not casually edit saved options/assets during normal retrieval.

Do not change third-party options just because different available assets are returned.

Do not overwrite saved options unless the user explicitly wants the settings changed or the integration is still in its initial setup flow.

---

## Why This Rule Matters

Third-party options/assets often control which provider account, store, location, model, service, warehouse, tax configuration, shipping service, voice account, payment account, or other provider resource RevCent uses.

Changing them can affect live behavior.

Potential impact:

- tax calculation provider/account changes,
- shipping/tracking behavior changes,
- AI model/provider settings change,
- AI Voice Agent provider/voice settings change,
- alternate payment behavior changes,
- provider account routing changes,
- production/test account mismatch,
- shop/campaign behavior changes,
- operational outages if wrong asset is selected.

Correct MCP behavior:

```text
Retrieve freely.
Edit only with setup purpose or explicit user intent.
```

---

## Input Schema

`GetUserThirdPartyIntegration` requires:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `user_third_party_integration_id` | string | Yes | 20-character User Third Party Integration ID. |

Example:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU"
}
```

If the user integration ID is unknown, use:

```text
GetUserThirdPartyIntegrations
```

first.

---

## Output Schema Overview

The output can include:

| Field | Meaning |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | Response code. `1` indicates success. |
| `id` | 20-character User Third Party Integration ID. |
| `name` | User integration name. |
| `description` | User integration description. |
| `enabled` | Whether the integration is enabled. |
| `third_party_credentials_saved` | Credential IDs that have been saved successfully. |
| `third_party_options_saved` | Option IDs/fields/values that have been saved. |
| `site_third_party_integration` | Associated native Site Third Party Integration. |

The `site_third_party_integration` object is important because it includes the integration type and the option/credential schema.

---

## `third_party_credentials_saved`

The response includes:

```text
third_party_credentials_saved
```

This is an array containing IDs of the credential groups that have been saved.

These IDs correspond to:

```text
site_third_party_integration.third_party_credentials.id
```

Use this to determine whether credentials appear to have been saved.

Important:

```text
Credentials are not returned directly.
Only saved credential identifiers are returned.
```

AI/MCP must not expect to read secret values.

If credentials need to be changed, use:

```text
CreateSecureForm
EditUserThirdPartyIntegration
```

Do not ask the user to paste credentials into chat.

---

## `third_party_options_saved`

The response includes:

```text
third_party_options_saved
```

This shows options and fields already saved in RevCent.

Each saved option can include:

```text
id
fields
fields.id
fields.value
```

The option ID corresponds to:

```text
site_third_party_integration.third_party_options[id]
```

The field ID corresponds to:

```text
site_third_party_integration.third_party_options.fields[id]
```

The `value` is always an array.

For a single-value input or single-select field:

```json
"value": [
  "one_value"
]
```

For a multi-select field:

```json
"value": [
  "value_one",
  "value_two"
]
```

Use `third_party_options_saved` to verify whether required options have already been configured.

---

## Site Third Party Integration Object

The response includes the associated:

```text
site_third_party_integration
```

This object can include:

- site integration ID,
- name,
- description,
- integration type,
- credential schema,
- third-party option schema,
- field definitions,
- select settings,
- third-party asset options where available.

This lets AI/MCP understand:

```text
What kind of integration this is.
What credentials were expected.
What options may need to be configured.
Which option/field IDs must be used when editing.
```

Do not modify options without reading this object.

---

## Integration Type

The Site Third Party Integration object includes:

```text
integration_type
```

Known values:

| Type | Purpose |
|---|---|
| `ai` | AI chat / AI Assistant integrations. |
| `ai_voice` | AI Voice Agent integrations. |
| `offline_payment` | Alternate/offline payment integrations. |
| `tax` | Tax calculation integrations. |
| `shipping` | Shipment tracking/status integrations. |

Use integration type to verify the integration is appropriate for the intended feature.

Examples:

```text
Tax Profile requires integration_type = tax.
AI Voice Agent requires ai_voice where applicable.
AI Assistant may require ai where applicable.
Shipping/tracking workflows may require shipping.
Offline payment workflows may require offline_payment.
```

---

## Third Party Options on Retrieval

`GetUserThirdPartyIntegration` is where account-specific option values may become visible after credentials are saved.

The Site Third Party Integration can define `third_party_options`.

Each option can include:

- option ID,
- option name,
- option description,
- required flag,
- fields,
- field IDs,
- field type,
- select settings,
- available static options,
- available account-specific third-party asset options.

Use this information to decide whether post-creation option editing is required.

---

## Third Party Assets

Third-party assets are option values pulled from the third-party provider's API.

They are specific to the user's account.

Examples may include:

- tax provider accounts,
- tax company profiles,
- tax nexus/configuration entities,
- shipping carrier accounts,
- warehouses,
- stores,
- locations,
- services,
- AI models,
- voice agent provider assets,
- payment provider accounts,
- provider-specific resources.

Important:

```text
Third-party assets can only be retrieved after credentials are saved.
```

This is why the post-creation workflow is:

```text
Create User Integration with credentials
    ↓
Get User Integration
    ↓
RevCent pulls account-specific third-party assets
    ↓
User chooses correct assets
    ↓
Edit User Integration saves selected options
```

---

## Select Fields and Third Party Assets

An option field can have:

```text
field_type = "select"
```

The field may use:

```text
select_settings.third_party_asset = true
```

When this is true:

```text
The available options are pulled from the third-party API and are only available after credentials have been saved.
```

If:

```text
select_settings.third_party_asset = false
```

then the options are static and should be present directly in the field's `select_settings.options`.

If:

```text
select_settings.multiple = true
```

the user can choose multiple values.

If:

```text
select_settings.multiple = false
```

the user should choose one value.

---

## Input Fields vs Select Fields

Option fields can be:

| Field Type | Meaning |
|---|---|
| `input` | User provides a typed value. |
| `select` | User chooses from available options. |

For `input` fields:

```text
Ask the user for the value, unless it is secret/sensitive.
```

For `select` fields:

```text
Show available options and have the user choose.
```

For select fields using third-party assets:

```text
Retrieve account-specific options first with GetUserThirdPartyIntegration.
```

---

## Correct Option-Editing Workflow After Retrieval

If options/assets need to be saved, use:

```text
EditUserThirdPartyIntegration
```

with:

```text
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:

- use option IDs from the retrieved `site_third_party_integration.third_party_options`,
- use field IDs from the option's `fields`,
- use selected values from the available options/assets,
- `value` must be an array,
- do not guess IDs,
- do not guess account-specific third-party assets,
- verify after editing with `GetUserThirdPartyIntegration`.

---

## When to Edit After GetUserThirdPartyIntegration

Edit options/assets after retrieval only when:

### Initial Creation Setup

The integration was just created and the native Site Third Party Integration requires options.

Correct:

```text
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
User chooses required options/assets
    ↓
EditUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
```

### Explicit User-Requested Settings Change

The user explicitly says they want to change integration settings/options.

Examples:

```text
Change the connected tax company/profile.
Change the shipping provider service option.
Switch to a different store/location/warehouse.
Change the AI model option.
Change the voice provider asset.
Change alternate payment configuration.
Update integration settings.
```

Correct:

```text
GetUserThirdPartyIntegration
    ↓
Show current saved options and available options
    ↓
User confirms desired change
    ↓
EditUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
```

---

## When Not to Edit Options/Assets

Do not edit options/assets when:

- the user only asked to view the integration,
- the user only asked whether it is configured,
- the integration is already configured and no setting change was requested,
- new available assets appear but the user did not request a change,
- an AI workflow is only checking integration health,
- another RevCent operation only needs the User Third Party Integration ID,
- the change would alter production behavior without confirmation.

Safe read-only behavior:

```text
GetUserThirdPartyIntegration
    ↓
Summarize current configuration
    ↓
Do not edit
```

---

## Editing Credentials Is Separate From Editing Options

Credentials and options are different.

| Change Needed | Correct Process |
|---|---|
| Change credentials/API keys/tokens | Create Secure Form, then `EditUserThirdPartyIntegration` with `secure_form_id`. |
| Change options/assets/settings | Use `EditUserThirdPartyIntegration` with `third_party_options`. |
| Change name/description/enabled | Use `EditUserThirdPartyIntegration` with only those fields. |

Never collect raw credentials in chat.

Credentials are handled through Secure Form.

Options/assets are selected from retrieved option data or user-provided non-secret values.

---

## Example: Initial Creation With Third Party Assets

Scenario:

```text
User creates a tax integration.
Tax provider credentials are saved.
The tax provider has multiple company profiles/accounts.
The correct company profile must be selected.
```

Flow:

```text
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
Review third_party_options
    ↓
Find select field where third_party_asset = true
    ↓
Show user available account-specific company/profile options
    ↓
User chooses correct profile
    ↓
EditUserThirdPartyIntegration with selected option
    ↓
GetUserThirdPartyIntegration verifies option saved
```

---

## Example: Editing Only When User Requests Change

User says:

```text
Switch this shipping integration to use a different warehouse/location.
```

Correct flow:

```text
GetUserThirdPartyIntegration
    ↓
Show current saved warehouse/location option
    ↓
Show available account-specific options
    ↓
User selects new warehouse/location
    ↓
EditUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration verifies update
```

Wrong behavior:

```text
GetUserThirdPartyIntegration
    ↓
AI sees a different available option
    ↓
AI changes the saved option without user request
```

Do not do that.

---

## Example: Read-Only Retrieval

User says:

```text
Is my tax integration configured?
```

Correct flow:

```text
GetUserThirdPartyIntegration
    ↓
Review enabled state
    ↓
Review credentials saved
    ↓
Review required options saved
    ↓
Report configuration status
```

Do not edit options unless the user then asks to change or complete setup.

---

## Verifying Configuration Completeness

After retrieving the integration, AI/MCP should check:

- `enabled`,
- `third_party_credentials_saved`,
- required credentials from `site_third_party_integration.third_party_credentials`,
- `third_party_options_saved`,
- required options from `site_third_party_integration.third_party_options`,
- whether required select fields have saved values,
- whether third-party asset options are visible,
- whether the integration type matches the intended feature.

Potential statuses:

| Status | Meaning |
|---|---|
| Complete | Credentials and required options appear saved. |
| Credentials missing | Secure Form / credential update needed. |
| Options missing | Edit options after user chooses values. |
| Disabled | Integration exists but is not active. |
| Wrong type | Integration cannot be used for intended feature. |
| Needs user choice | Multiple account-specific assets exist and user must choose. |

---

## Integration Type Examples

### Tax

A Tax Profile needs a User Third Party Integration where:

```text
site_third_party_integration.integration_type = "tax"
```

Use `GetUserThirdPartyIntegration` to verify before creating or editing the Tax Profile.

If the tax provider exposes account-specific company/profile assets, retrieve them here and save selected options with `EditUserThirdPartyIntegration`.

### Shipping

A shipping/tracking workflow needs an integration where:

```text
integration_type = "shipping"
```

If provider assets include services, locations, or carrier accounts, retrieve and save the chosen options only during setup or explicit changes.

### AI

AI features may use integrations where:

```text
integration_type = "ai"
```

If provider assets include models/accounts/options, retrieve and save the intended settings only during setup or explicit changes.

### AI Voice

AI Voice Agents may use integrations where:

```text
integration_type = "ai_voice"
```

If provider assets include phone numbers, voice profiles, agents, accounts, or models, do not change them without explicit user intent.

### Offline Payment

Alternate payment workflows may use integrations where:

```text
integration_type = "offline_payment"
```

If provider assets include accounts or payment method settings, edit only during setup or explicit changes.

---

## Best Practices

1. Use `GetUserThirdPartyIntegration` after `CreateUserThirdPartyIntegration`.
2. Use it to retrieve account-specific third-party assets/options.
3. Use it to verify credentials and options are saved.
4. Use it before using an integration in another RevCent feature.
5. Use it before editing an integration's options/settings.
6. Only edit options/assets during initial setup or explicit user-requested changes.
7. Show the user current saved options before changing them.
8. Ask the user to choose when multiple third-party assets are available.
9. Do not guess option IDs, field IDs, or asset values.
10. Verify after editing with another `GetUserThirdPartyIntegration` call.
11. Keep read-only retrieval separate from mutation/edit operations.
12. Use Secure Form for credential changes.
13. Do not expose or request raw credentials in chat.
14. Confirm integration type before using it for Tax, Shipping, AI, Voice, or Offline Payment features.

---

## Common Mistakes to Avoid

Do not:

- edit options when the user only asked to retrieve/view the integration,
- overwrite saved options just because new assets are available,
- change production integration settings without explicit confirmation,
- confuse credentials with options,
- collect credentials in chat,
- guess remote asset values,
- guess option IDs or field IDs,
- use a Site Third Party Integration ID where a User Third Party Integration ID is required,
- assume the top/first third-party asset is correct,
- ignore required options after initial creation,
- forget to retrieve the integration after creation,
- forget to verify after editing,
- use a User Third Party Integration for the wrong feature type.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| Need details for one connected integration | Use `GetUserThirdPartyIntegration`. |
| Need to check credentials were saved | Inspect `third_party_credentials_saved`. |
| Need to check options were saved | Inspect `third_party_options_saved`. |
| Need account-specific third-party assets | Use `GetUserThirdPartyIntegration` after credentials are saved. |
| Integration was just created and options are required | Retrieve, have user choose options/assets, then edit. |
| User explicitly wants to change settings/options | Retrieve, show current/available options, confirm, then edit. |
| User only asks to view/check integration | Retrieve only; do not edit. |
| Credentials need update | Use Secure Form, then `EditUserThirdPartyIntegration` with `secure_form_id`. |
| Options/assets need update | Use `EditUserThirdPartyIntegration` with `third_party_options`. |
| Need to verify after edit | Run `GetUserThirdPartyIntegration` again. |

---

## Final AI/MCP Instruction

Use `GetUserThirdPartyIntegration` to retrieve the full details of a connected User Third Party Integration.

This operation is essential after creating a user integration because it can expose account-specific third-party options/assets once credentials have been saved. Those options/assets may need to be selected and saved with `EditUserThirdPartyIntegration`.

Only update options/assets during initial integration setup or when the user explicitly asks to change the integration's options/settings. Otherwise, treat `GetUserThirdPartyIntegration` as a read-only retrieval/verification operation.

Never change saved third-party options/assets casually, because those settings may control live provider accounts, stores, locations, models, shipping services, tax profiles, payment accounts, or voice/AI behavior.


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