# RevCent MCP Guide: `GetSecureForm`

AI/MCP-focused guide for retrieving a Secure Form in RevCent.

This document explains the `GetSecureForm` operation, why it exists, how to use it to check Secure Form completion/expiration, and how it fits between `CreateSecureForm` and credential-dependent follow-up operations such as creating or editing SMTP Profiles, User Third Party Integrations, gateways, fulfillment centers, shops, and PayPal accounts.

---

## Related Documentation

AI/MCP clients should also read:

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

Related operation guides:

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| CreateSecureForm | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Creates the temporary Secure Form and returns the `secure_form_id` and `form_url`. |
| CreateUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserThirdPartyIntegration.md` | Uses `secure_form_id` to securely save third-party integration credentials. |
| EditUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Uses `secure_form_id` when changing existing third-party integration credentials. |
| CreateSMTPProfile | `https://revcent.com/documentation/markdown/mcp/operation/CreateSMTPProfile.md` | Uses `secure_form_id` to securely save SMTP credentials. |
| EditSMTPProfile | `https://revcent.com/documentation/markdown/mcp/operation/EditSMTPProfile.md` | Uses `secure_form_id` when changing SMTP credentials. |
| Third Party Integration Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Explains native and user third-party integrations that often require Secure Forms. |
| SMTP Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSMTPProfile.md` | Explains SMTP Profiles and secure credential setup. |

---

## Operation Summary

Operation:

```text
GetSecureForm
```

Title:

```text
Get A Secure Form
```

Purpose:

```text
Retrieve the details of a specific Secure Form.
```

Use `GetSecureForm` to check the state of a Secure Form after it has been created.

It can tell AI/MCP:

- whether the Secure Form exists,
- whether the user completed the form,
- whether the form has expired,
- which source the form was created for,
- which source ID it belongs to when applicable,
- what form URL was generated,
- when it was created/updated.

---

## Why `GetSecureForm` Exists

`CreateSecureForm` creates a temporary form so users can securely submit sensitive credentials without exposing secrets in AI chat, API request bodies, logs, or conversation history.

`GetSecureForm` exists to verify the state of that temporary form before the AI/MCP client uses the `secure_form_id` in a follow-up operation.

Simple flow:

```text
CreateSecureForm
    ↓
User opens form_url and enters sensitive credentials
    ↓
GetSecureForm checks whether completed = true
    ↓
If completed:
        use secure_form_id in follow-up operation
    ↓
If not completed:
        ask user to complete the form
    ↓
If expired/error:
        create a new Secure Form
```

Without `GetSecureForm`, an AI/MCP client may try to use a `secure_form_id` before the user has submitted credentials, or after the form has expired.

---

## Core Use Cases

Use `GetSecureForm` when:

- the user says they completed a Secure Form and AI/MCP wants to verify it,
- a follow-up operation requires `secure_form_id`,
- AI/MCP needs to check whether the Secure Form is still valid,
- AI/MCP needs to confirm the Secure Form source before using it,
- the user is unsure whether they submitted the form,
- the credential-dependent operation failed and AI/MCP needs to inspect the Secure Form state,
- the AI/MCP client needs to avoid sending an incomplete or expired `secure_form_id`.

---

## Secure Form Lifecycle

A Secure Form lifecycle usually looks like this:

```text
1. CreateSecureForm is called.
2. RevCent returns secure_form_id and form_url.
3. User opens form_url while logged into RevCent.
4. User fills out sensitive fields and submits.
5. Secure form data is encrypted and saved internally.
6. GetSecureForm can verify completed = true.
7. AI/MCP uses secure_form_id in the intended follow-up operation.
```

Important lifecycle facts:

```text
Secure Forms expire after 1 hour.
Completed Secure Forms cannot be modified.
Expired Secure Forms cannot be used.
Incorrect form entries require creating a new Secure Form.
```

---

## Input Schema

`GetSecureForm` requires one field:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `secure_form_id` | string | Yes | 20-character Secure Form ID. |

Example:

```json
{
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

---

## Output Schema

The 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. |
| `created_date_unix` | integer | Unix timestamp when the Secure Form was created. |
| `id` | string | 20-character Secure Form ID. |
| `completed` | boolean | Whether the user completed and submitted the Secure Form. |
| `form_source` | string | Source type used to generate the form. |
| `form_source_id` | string | Source ID for source types that require one. |
| `form_url` | string | Secure form URL the user opens to complete the form. |
| `expiration_date_unix` | integer | Unix timestamp when the Secure Form expires. |
| `updated_date_unix` | integer | Unix timestamp when the Secure Form was last updated. |

---

## `completed`

The most important field is:

```text
completed
```

If:

```json
"completed": true
```

then:

```text
The user filled out the form.
The user submitted the form.
RevCent encrypted and saved the sensitive data internally.
The secure_form_id can be used in the intended follow-up operation.
```

If:

```json
"completed": false
```

then:

```text
The user has not completed the form yet.
Do not use the secure_form_id in a follow-up operation.
Ask the user to open the form_url and submit the form.
```

Important:

```text
Once a Secure Form has been completed, it cannot be modified.
```

If the user entered incorrect credentials, create a new Secure Form.

---

## `expiration_date_unix`

The output includes:

```text
expiration_date_unix
```

This is the Unix timestamp when the Secure Form expires.

Secure Forms are temporary.

Critical rule:

```text
A Secure Form expires after 1 hour.
```

After expiration:

- the form URL is no longer valid,
- the user cannot complete the form,
- attempts to access the form after expiration return an error,
- the form and saved data are deleted.

If the Secure Form is expired or inaccessible, create a new Secure Form.

---

## `form_source`

The output includes:

```text
form_source
```

Allowed values:

```text
third_party_integration
third_party_shop
gateway
fulfillment_center
smtp_profile
paypal_account
```

Use this to confirm the form was created for the correct credential source.

Example:

```json
{
  "form_source": "smtp_profile"
}
```

This means the Secure Form was created for SMTP credentials.

---

## `form_source_id`

The output may include:

```text
form_source_id
```

This applies only to source types that require a source ID:

| `form_source` | `form_source_id` Meaning |
|---|---|
| `third_party_integration` | Site Third Party Integration ID |
| `third_party_shop` | Site Third Party Shop ID |
| `gateway` | Site Gateway ID |
| `fulfillment_center` | Site Fulfillment Center ID |

No `form_source_id` applies to:

```text
smtp_profile
paypal_account
```

Important:

```text
For third_party_integration, form_source_id is the Site Third Party Integration ID, not the User Third Party Integration ID.
```

---

## `form_url`

The output includes:

```text
form_url
```

This is the URL the user opens to complete the Secure Form.

The user must be logged into RevCent to access the Secure Form URL.

If the form is not completed, AI/MCP can give the user the `form_url` again as long as it has not expired.

Do not expose or modify the submitted sensitive values.

---

## Correct Usage Pattern

### Standard Verification Flow

```text
User: I completed the secure form.
    ↓
AI/MCP calls GetSecureForm
    ↓
If completed = true:
        proceed with follow-up operation
    ↓
If completed = false:
        ask user to finish the form
    ↓
If expired/not found/error:
        create a new Secure Form
```

---

## Example: Verify Before Creating User Third Party Integration

```text
CreateSecureForm
    form_source = third_party_integration
    form_source_id = Site Third Party Integration ID
    ↓
User completes form
    ↓
GetSecureForm
    ↓
If completed = true:
        CreateUserThirdPartyIntegration with secure_form_id
```

Follow-up example:

```json
{
  "name": "Main Tax Provider",
  "site_third_party_integration": "SSSSSSSSSSSSSSSSSSSS",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Do not call `CreateUserThirdPartyIntegration` with a Secure Form that is incomplete.

---

## Example: Verify Before Editing User Third Party Integration Credentials

```text
User wants to update third-party credentials
    ↓
CreateSecureForm
    ↓
User completes form
    ↓
GetSecureForm
    ↓
If completed = true:
        EditUserThirdPartyIntegration with secure_form_id
```

Follow-up example:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Only use `secure_form_id` when updating credentials.

---

## Example: Verify Before Creating SMTP Profile

```text
CreateSecureForm
    form_source = smtp_profile
    ↓
User completes form
    ↓
GetSecureForm
    ↓
If completed = true:
        CreateSMTPProfile with secure_form_id
```

Follow-up example:

```json
{
  "name": "Main Store SMTP",
  "host": "smtp.example.com",
  "port": 587,
  "use_ssl": false,
  "require_tls": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

---

## Example: Verify Before Editing SMTP Credentials

```text
User wants to change SMTP credentials
    ↓
CreateSecureForm
    form_source = smtp_profile
    ↓
User completes form
    ↓
GetSecureForm
    ↓
If completed = true:
        EditSMTPProfile with secure_form_id
```

Follow-up example:

```json
{
  "smtp_profile_id": "SSSSSSSSSSSSSSSSSSSS",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Only provide `secure_form_id` when changing SMTP credentials.

---

## What `GetSecureForm` Does Not Do

`GetSecureForm` does not:

- create a Secure Form,
- update a Secure Form,
- extend the expiration time,
- modify a completed form,
- reveal secret values,
- retrieve decrypted credentials,
- create the final integration/profile/account,
- configure third-party options/assets,
- test whether credentials are correct with the provider.

It only retrieves Secure Form metadata and state.

---

## Secure Values Are Never Returned

`GetSecureForm` does not return sensitive values.

It returns state and metadata, such as:

- completed,
- form source,
- expiration timestamp,
- form URL.

It does not return:

- API keys,
- passwords,
- tokens,
- SMTP passwords,
- provider secrets,
- gateway credentials,
- shop secrets,
- PayPal credentials.

AI/MCP should never expect secret values from `GetSecureForm`.

---

## Handling `completed = false`

If `completed = false`:

```text
Do not use secure_form_id yet.
Ask the user to open the form_url and submit the form.
Remind the user the form expires after 1 hour.
```

Recommended AI/MCP response:

```text
The Secure Form is not completed yet. Please open the secure form URL, submit the required fields, and tell me once it is complete.
```

---

## Handling Expiration

If the current time is after `expiration_date_unix`, or the form retrieval/access fails because the form expired:

```text
Create a new Secure Form.
Give the user the new form_url.
Use the new secure_form_id after completion.
```

Do not use the old `secure_form_id`.

Do not tell the user to keep using the old URL.

---

## Handling Wrong Credentials

If the user says the wrong credentials were submitted:

```text
Create a new Secure Form.
Have the user complete the new form.
Use the new secure_form_id.
```

Because completed Secure Forms cannot be modified.

For existing integrations/profiles, use the new `secure_form_id` in the correct edit operation, such as:

- `EditUserThirdPartyIntegration`,
- `EditSMTPProfile`,
- gateway edit operation,
- fulfillment edit operation,
- shop edit operation,
- PayPal edit operation.

---

## `GetSecureForm` vs `CreateSecureForm`

| Need | Correct Operation |
|---|---|
| Generate a new secure credential form | `CreateSecureForm` |
| Get the secure form URL | `CreateSecureForm` or `GetSecureForm` |
| Check whether the user completed the form | `GetSecureForm` |
| Check expiration timestamp | `GetSecureForm` |
| Use credentials in a create/edit operation | Follow-up operation with `secure_form_id` |
| Modify completed form | Not supported; create a new form |
| Retrieve secret values | Not supported |

---

## `GetSecureForm` vs Follow-Up Operations

A Secure Form is not the final object.

Example:

```text
GetSecureForm confirms completed = true
```

does not mean the SMTP Profile or User Third Party Integration has been created.

You still need to call the follow-up operation:

```text
CreateSMTPProfile
CreateUserThirdPartyIntegration
EditSMTPProfile
EditUserThirdPartyIntegration
```

or another credential-dependent operation.

`GetSecureForm` is a checkpoint, not the final setup step.

---

## Best Practices

1. Use `GetSecureForm` after the user says they completed the Secure Form.
2. Verify `completed = true` before using `secure_form_id`.
3. Check `expiration_date_unix` before relying on the form.
4. Confirm `form_source` matches the intended follow-up operation.
5. Confirm `form_source_id` matches the intended site/source ID when applicable.
6. Reuse the same `form_url` only while the form is unexpired.
7. Create a new Secure Form if the old one expires.
8. Create a new Secure Form if the user submitted incorrect credentials.
9. Never expect `GetSecureForm` to return secrets.
10. Do not use `secure_form_id` in unrelated operations.
11. Continue to the follow-up operation after completion is confirmed.
12. Use Secure Forms only for sensitive fields; collect non-sensitive settings normally.

---

## Common Mistakes to Avoid

Do not:

- use a Secure Form before `completed = true`,
- assume the form is completed because it was created,
- reuse an expired `secure_form_id`,
- try to modify a completed Secure Form,
- expect `GetSecureForm` to reveal credentials,
- treat `GetSecureForm` as creating the integration/profile/account,
- use a Secure Form created for one source in a different source operation,
- ignore `form_source_id` mismatches,
- use old Secure Forms after credential mistakes,
- ask users to paste credentials into chat instead of using Secure Forms.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| User says form is complete | Call `GetSecureForm`. |
| `completed = true` | Proceed with intended follow-up operation. |
| `completed = false` | Ask user to complete the form URL. |
| Form expired | Create a new Secure Form. |
| User entered wrong credentials | Create a new Secure Form. |
| Need to see source type | Inspect `form_source`. |
| Need to see source ID | Inspect `form_source_id`. |
| Need secret values | Not possible; never ask for or retrieve secrets. |
| Need final integration/profile created | Use follow-up operation with `secure_form_id`. |

---

## Final AI/MCP Instruction

Use `GetSecureForm` to retrieve and verify a Secure Form before using its `secure_form_id` in a credential-dependent operation.

The operation exists so MCP/AI clients can confirm whether the user has completed the Secure Form, whether it is still valid, and whether it belongs to the correct source. It prevents AI/MCP from using incomplete, expired, or incorrect Secure Forms.

`GetSecureForm` never returns sensitive values and does not create the final integration/profile/account. After `completed = true`, call the intended follow-up operation with `secure_form_id`, such as `CreateUserThirdPartyIntegration`, `EditUserThirdPartyIntegration`, `CreateSMTPProfile`, or `EditSMTPProfile`.

If the form is expired or the user submitted incorrect credentials, create a new Secure Form.


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