> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations API Reference for Nymble Commerce

> REST API reference for Nymble Commerce integrations — create, list, test, update, and delete third-party provider connections including payment and accounting systems.

The Integrations API lets you manage connections to payment gateways, accounting software, and other third-party providers. Credentials are stored encrypted — secrets are write-only and are **never returned in GET responses**. All integration endpoints require the **Admin** role.

<Note>
  Secrets fields (marked `isSecret` in templates) are write-only. Once saved, they cannot be retrieved by any GET endpoint. To replace a secret, use the [rotate-secrets](#post-apiorganizationsorganizationidintegrationsintegrationidrotate-secrets) endpoint.
</Note>

***

## Integration types

The `integrationType` field uses the following enumeration values:

| Value | Description |
| ----- | ----------- |
| `1`   | Payment     |
| `2`   | Accounting  |
| `3`   | Shipping    |
| `4`   | Email       |
| `5`   | Sms         |
| `6`   | Analytics   |
| `7`   | Crm         |
| `8`   | Inventory   |

***

## GET /api/integration-templates

Returns all available integration templates. Use templates to understand which fields are required before creating an integration. For OAuth providers (e.g. QuickBooks), the response includes the `callbackUrl` you must register with the external service.

**Security:** Admin policy

### Query parameters

<ParamField query="integrationType" type="integer">
  Filter templates by integration type. See the [Integration types](#integration-types) table for valid values. Omit to return all templates.
</ParamField>

### Response

<ResponseField name="templates" type="array">
  Array of integration template objects.

  <Expandable title="IntegrationTemplate object">
    <ResponseField name="type" type="integer">
      Integration type enum value.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Provider identifier (e.g. `AuthorizeNet`, `QuickBooks`).
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Human-readable provider name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of what the integration does.
    </ResponseField>

    <ResponseField name="requiresOAuth" type="boolean">
      Whether the provider uses OAuth for authentication.
    </ResponseField>

    <ResponseField name="callbackUrl" type="string">
      OAuth callback URL to register with the external provider. Only present when `requiresOAuth` is `true`.
    </ResponseField>

    <ResponseField name="documentationUrl" type="string">
      Link to provider documentation.
    </ResponseField>

    <ResponseField name="logoUrl" type="string">
      URL of the provider's logo image.
    </ResponseField>

    <ResponseField name="supportedFeatures" type="string[]">
      List of features supported by this integration.
    </ResponseField>

    <ResponseField name="configurationFields" type="array">
      Non-sensitive configuration fields for this provider.

      <Expandable title="ConfigurationField object" />
    </ResponseField>

    <ResponseField name="secretFields" type="array">
      Sensitive credential fields. Values submitted for these fields are stored encrypted and never returned.

      <Expandable title="SecretField object" />
    </ResponseField>
  </Expandable>
</ResponseField>

```json title="Example response" theme={null}
{
  "templates": [
    {
      "type": 1,
      "provider": "AuthorizeNet",
      "displayName": "Authorize.Net",
      "description": "Accept credit card payments through Authorize.Net payment gateway",
      "requiresOAuth": false,
      "documentationUrl": "https://developer.authorize.net/",
      "supportedFeatures": ["payments", "refunds"],
      "configurationFields": [
        {
          "key": "IsSandbox",
          "displayName": "Sandbox Mode",
          "description": "Enable sandbox/test mode",
          "type": 3,
          "required": true,
          "defaultValue": "true"
        }
      ],
      "secretFields": [
        {
          "key": "ApiLoginId",
          "displayName": "API Login ID",
          "description": "Your Authorize.Net API Login ID",
          "required": true,
          "isSensitive": true
        },
        {
          "key": "TransactionKey",
          "displayName": "Transaction Key",
          "description": "Your Authorize.Net Transaction Key",
          "required": true,
          "isSensitive": true
        }
      ]
    },
    {
      "type": 2,
      "provider": "QuickBooks",
      "displayName": "QuickBooks Online",
      "description": "Sync customer and product data with QuickBooks Online",
      "requiresOAuth": true,
      "callbackUrl": "https://api.achievemomentum.com/api/integrations/QuickBooks/callback",
      "configurationFields": [],
      "secretFields": []
    }
  ]
}
```

```bash title="curl example — all templates" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/integration-templates" \
  -H "Authorization: Bearer <your_token>"
```

```bash title="curl example — filter by type" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/integration-templates?integrationType=1" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/integrations/available

Returns all available integration templates enriched with the current configuration and connection status for your organization. Results are grouped by integration type.

**Security:** Admin policy

### Response

<ResponseField name="organizationId" type="string">
  Your organization's identifier.
</ResponseField>

<ResponseField name="totalAvailable" type="integer">
  Total number of available integrations.
</ResponseField>

<ResponseField name="configuredCount" type="integer">
  Number of integrations you have configured.
</ResponseField>

<ResponseField name="enabledCount" type="integer">
  Number of integrations that are currently enabled.
</ResponseField>

<ResponseField name="integrationsByType" type="object">
  Dictionary keyed by integration type, where each value is an array of `AvailableIntegration` objects.

  <Expandable title="AvailableIntegration object" />
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/integrations/available" \
  -H "Authorization: Bearer <your_token>"
```

***

## POST /api/organizations/{organizationId}/integrations

Creates a new integration for the specified organization. Pass non-sensitive settings in `configuration` and sensitive credentials in `secrets` — secrets are encrypted at rest and are never returned by any GET endpoint.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

### Request body

<ParamField body="integrationType" type="integer" required>
  Integration type. See the [Integration types](#integration-types) table.
</ParamField>

<ParamField body="provider" type="string" required>
  Provider identifier, e.g. `AuthorizeNet` or `QuickBooks`. Must match a template provider value.
</ParamField>

<ParamField body="displayName" type="string" required>
  A human-readable name for this integration instance (e.g. `Main Payment Gateway`).
</ParamField>

<ParamField body="isEnabled" default="true" type="boolean">
  Whether the integration should be enabled immediately.
</ParamField>

<ParamField body="configuration" type="object">
  Key-value pairs of non-sensitive configuration settings. Keys must match the `configurationFields` keys from the provider's template.
</ParamField>

<ParamField body="secrets" type="object">
  Key-value pairs of sensitive credentials. Keys must match the `secretFields` keys from the provider's template. Values are stored encrypted and are never returned.
</ParamField>

### Response

<ResponseField name="integrationId" type="string">
  Unique identifier of the newly created integration.
</ResponseField>

<ResponseField name="organizationId" type="string">
  Your organization's identifier.
</ResponseField>

<ResponseField name="integrationType" type="integer">
  Integration type.
</ResponseField>

<ResponseField name="provider" type="string">
  Provider identifier.
</ResponseField>

<ResponseField name="displayName" type="string">
  Display name of the integration.
</ResponseField>

<ResponseField name="isEnabled" type="boolean">
  Whether the integration is enabled.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the integration was created.
</ResponseField>

```json title="Example request — Authorize.Net" theme={null}
{
  "integrationType": 1,
  "provider": "AuthorizeNet",
  "displayName": "Main Payment Gateway",
  "isEnabled": true,
  "configuration": {
    "IsSandbox": "true"
  },
  "secrets": {
    "ApiLoginId": "your-api-login-id",
    "TransactionKey": "your-transaction-key"
  }
}
```

```json title="Example response" theme={null}
{
  "integrationId": "int_123456789",
  "organizationId": "org123",
  "integrationType": 1,
  "provider": "AuthorizeNet",
  "displayName": "Main Payment Gateway",
  "isEnabled": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
```

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/organizations/org123/integrations" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationType": 1,
    "provider": "AuthorizeNet",
    "displayName": "Main Payment Gateway",
    "isEnabled": true,
    "configuration": { "IsSandbox": "true" },
    "secrets": {
      "ApiLoginId": "your-api-login-id",
      "TransactionKey": "your-transaction-key"
    }
  }'
```

***

## GET /api/organizations/{organizationId}/integrations

Returns all integrations configured for the specified organization. Secrets are never included in the response.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

### Query parameters

<ParamField query="integrationType" type="integer">
  Filter results by integration type. See the [Integration types](#integration-types) table.
</ParamField>

<ParamField query="isEnabled" type="boolean">
  Filter results by enabled status. Omit to return all.
</ParamField>

### Response

<ResponseField name="integrations" type="array">
  Array of integration summary objects (secrets omitted).

  <Expandable title="IntegrationSummary object" />
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/organizations/org123/integrations" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/organizations/{organizationId}/integrations/{integrationId}

Returns detailed information about a specific integration, including its configuration and the list of available fields from the provider template. Secrets are never included.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Response

<ResponseField name="integrationId" type="string">
  Unique integration identifier.
</ResponseField>

<ResponseField name="organizationId" type="string">
  Organization identifier.
</ResponseField>

<ResponseField name="integrationType" type="integer">
  Integration type.
</ResponseField>

<ResponseField name="provider" type="string">
  Provider identifier.
</ResponseField>

<ResponseField name="displayName" type="string">
  Display name.
</ResponseField>

<ResponseField name="isEnabled" type="boolean">
  Whether the integration is enabled.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 last-updated timestamp.
</ResponseField>

<ResponseField name="configuration" type="object">
  Non-sensitive configuration key-value pairs. Secrets are excluded.
</ResponseField>

<ResponseField name="createdBy" type="string">
  Identity of the user who created the integration.
</ResponseField>

<ResponseField name="availableFields" type="object">
  Fields available for this provider from the template, including `configurationFields`, `secretFields`, `requiresOAuth`, `documentationUrl`, and `supportedFeatures`.
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789" \
  -H "Authorization: Bearer <your_token>"
```

***

## PUT /api/organizations/{organizationId}/integrations/{integrationId}

Updates an existing integration's display name, enabled status, configuration, and/or secrets. If you update secrets, the API flags that a connection test is recommended.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Request body

<ParamField body="displayName" type="string">
  New display name for the integration.
</ParamField>

<ParamField body="isEnabled" type="boolean">
  Enable or disable the integration.
</ParamField>

<ParamField body="configuration" type="object">
  Updated non-sensitive configuration key-value pairs. Merged with existing configuration.
</ParamField>

<ParamField body="secrets" type="object">
  Updated secret key-value pairs. Values are encrypted and overwrite existing secrets for the supplied keys. Cannot be retrieved after saving.
</ParamField>

### Response

<ResponseField name="testConnectionRequired" type="boolean">
  `true` if secrets or critical configuration keys (e.g. `IsSandbox`, `Environment`) were changed. Run a connection test to verify.
</ResponseField>

```bash title="curl example" theme={null}
curl -X PUT \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production Payment Gateway",
    "isEnabled": true,
    "configuration": { "IsSandbox": "false" }
  }'
```

***

## POST /api/organizations/{organizationId}/integrations/{integrationId}/test

Tests connectivity and authentication for the specified integration. The result is recorded on the integration and reflected in the `testStatus` field of subsequent list/get responses.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Response

<ResponseField name="integrationId" type="string">
  The integration that was tested.
</ResponseField>

<ResponseField name="isSuccessful" type="boolean">
  `true` if the connection test passed.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result message (e.g. `Connection test successful`).
</ResponseField>

<ResponseField name="testedAt" type="string">
  ISO 8601 timestamp of when the test was performed.
</ResponseField>

```json title="Example response" theme={null}
{
  "integrationId": "int_123456789",
  "isSuccessful": true,
  "message": "Connection test successful",
  "testedAt": "2024-01-15T14:22:00Z"
}
```

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789/test" \
  -H "Authorization: Bearer <your_token>"
```

***

## POST /api/organizations/{organizationId}/integrations/{integrationId}/connect

Initiates an OAuth authorization flow for OAuth-based providers (e.g. QuickBooks). Returns an `authorizationUrl` that you redirect the user to. The OAuth URL expires after 15 minutes.

**Security:** Admin policy

<Tip>
  Before calling this endpoint, ensure you have registered the `callbackUrl` from the integration template with the external provider's developer console.
</Tip>

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier. Resolved from the JWT `OrganizationId` claim.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Request body

<ParamField body="state" type="string" required>
  An opaque string (typically your application's return URL) that Nymble Commerce encodes into the OAuth state parameter and returns to your callback. Use this to redirect the user back to the correct page after authorization.
</ParamField>

### Response

<ResponseField name="authorizationUrl" type="string">
  The OAuth authorization URL. Redirect your user to this URL to begin the OAuth flow.
</ResponseField>

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789/connect" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{ "state": "https://yourapp.com/integrations/callback" }'
```

***

## POST /api/organizations/{organizationId}/integrations/{integrationId}/rotate-secrets

Rotates (replaces) the secrets for the specified integration. Optionally runs a connection test after rotation to validate the new credentials. Use this endpoint for periodic security compliance key rotation.

**Security:** Admin policy

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Request body

<ParamField body="newSecrets" type="object" required>
  Key-value pairs of new secret values. Keys must match the `secretFields` keys from the provider's template. Values are encrypted at rest and are never returned.
</ParamField>

<ParamField body="testConnectionAfterRotation" default="true" type="boolean">
  Whether to automatically run a connection test after updating the secrets. Strongly recommended.
</ParamField>

### Response

<ResponseField name="testConnectionSuccessful" type="boolean">
  `true` if the post-rotation connection test passed. Only meaningful when `testConnectionAfterRotation` was `true`.
</ResponseField>

```json title="Example request" theme={null}
{
  "newSecrets": {
    "ApiLoginId": "new-rotated-api-login-id",
    "TransactionKey": "new-rotated-transaction-key"
  },
  "testConnectionAfterRotation": true
}
```

```json title="Example response" theme={null}
{
  "integrationId": "int_123456789",
  "organizationId": "org123",
  "rotationSuccessful": true,
  "testConnectionSuccessful": true,
  "message": "Secrets rotated successfully and connection test passed",
  "rotatedAt": "2024-01-15T15:00:00Z",
  "rotatedSecretKeys": ["ApiLoginId", "TransactionKey"]
}
```

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789/rotate-secrets" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "newSecrets": {
      "ApiLoginId": "new-rotated-api-login-id",
      "TransactionKey": "new-rotated-transaction-key"
    },
    "testConnectionAfterRotation": true
  }'
```

***

## DELETE /api/organizations/{organizationId}/integrations/{integrationId}

Permanently deletes an integration and all associated configuration and encrypted credentials.

**Security:** Admin policy

<Warning>
  This action permanently removes the integration, including all stored credentials. It cannot be undone. If an integration is actively used by payment methods or other services, disable it first or contact support before deleting.
</Warning>

### Path parameters

<ParamField path="organizationId" type="string" required>
  Your organization's unique identifier.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration's unique identifier.
</ParamField>

### Response

```bash title="curl example" theme={null}
curl -X DELETE \
  "https://api.achievemomentum.com/api/organizations/org123/integrations/int_123456789" \
  -H "Authorization: Bearer <your_token>"
```