Create Account Integration

Beta

POST/v1/settings/integrations

Idempotent with Idempotency-Key header. Learn more

Connects a third-party provider to the account, or replaces the name and credentials of the provider's existing connection.

An account can have at most one integration per provider, so calling this again for a provider that is already connected rotates its credentials in place and returns the same integration rather than creating a second one. Credentials are checked for the provider's expected key format, encrypted at rest, and never returned in API responses.

Role type requiredValues:admin

Only API keys or agents whose role has this type can call this endpoint.

namestring

Display name of the integration.

providerstringenumValues:stripeshippohubspot

Integration provider code.

stripe: Stripe payment processing.
shippo: Shippo shipping and label generation.
hubspot: HubSpot CRM.

credentialsstring

JSON string containing the provider's credentials.

Required keys depend on the provider:

stripe: private_key (sk_...), publishable_key (pk_...), and webhook_secret (whsec_...).
shippo: api_key (shippo_live_... or shippo_test_...).
hubspot: access_token (pat-...).

For Stripe and Shippo, sandbox accounts must supply test keys and production accounts must supply live keys; credentials that do not match are rejected. HubSpot tokens make no such distinction.

idstring

Account integration ID.

objectstringenumValues:account_integration

Resource type identifier.

namestring

Display name of the integration.

providerstringenumValues:stripeshippohubspot

Integration provider code.

stripe: Stripe payment processing.
shippo: Shippo shipping and label generation.
hubspot: HubSpot CRM.

statusstringenumValues:activeinactive

Lifecycle status of the integration.

Integrations are created active. Setting an integration to inactive keeps its stored credentials but stops it from being used (for example, the Stripe publishable key cannot be retrieved while the Stripe integration is inactive).

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

201

Successful response for Create Account Integration

Create Account Integration

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const accountIntegration = await client.settings.integrations.create({
  credentials:
    '{"private_key":"sk_test_...","publishable_key":"pk_test_...","webhook_secret":"whsec_..."}',
  name: 'My Stripe Integration',
  provider: 'stripe',
});

console.log(accountIntegration.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const accountIntegration = await client.settings.integrations.create({
  credentials:
    '{"private_key":"sk_test_...","publishable_key":"pk_test_...","webhook_secret":"whsec_..."}',
  name: 'My Stripe Integration',
  provider: 'stripe',
});

console.log(accountIntegration.id);

201 example

{
  "id": "acig_5ilahyezrs63",
  "object": "account_integration",
  "name": "My Stripe Integration",
  "provider": "stripe",
  "status": "active",
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "acig_5ilahyezrs63",
  "object": "account_integration",
  "name": "My Stripe Integration",
  "provider": "stripe",
  "status": "active",
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Create Account Integration

Authorization

Request Body

Returns

Responses