Skip to main content
POST
/
v1
/
integrations
PHP
declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity(
        'YOUR_SECRET_KEY_HERE'
    )
    ->build();

$createIntegrationRequestDto = new Components\CreateIntegrationRequestDto();

$response = $sdk->integrations->create(
    createIntegrationRequestDto: $createIntegrationRequestDto
);

if ($response->integrationResponseDto !== null) {
    // handle response
}
{
  "_environmentId": "<string>",
  "_organizationId": "<string>",
  "name": "<string>",
  "identifier": "<string>",
  "providerId": "<string>",
  "active": true,
  "deleted": true,
  "primary": true,
  "_id": "<string>",
  "credentials": {
    "apiKey": "<string>",
    "user": "<string>",
    "secretKey": "<string>",
    "domain": "<string>",
    "password": "<string>",
    "host": "<string>",
    "port": "<string>",
    "secure": true,
    "region": "<string>",
    "accountSid": "<string>",
    "messageProfileId": "<string>",
    "token": "<string>",
    "from": "<string>",
    "senderName": "<string>",
    "projectName": "<string>",
    "applicationId": "<string>",
    "clientId": "<string>",
    "requireTls": true,
    "ignoreTls": true,
    "tlsOptions": {},
    "baseUrl": "<string>",
    "webhookUrl": "<string>",
    "redirectUrl": "<string>",
    "hmac": true,
    "serviceAccount": "<string>",
    "ipPoolName": "<string>",
    "apiKeyRequestHeader": "<string>",
    "secretKeyRequestHeader": "<string>",
    "idPath": "<string>",
    "datePath": "<string>",
    "apiToken": "<string>",
    "authenticateByToken": true,
    "authenticationTokenKey": "<string>",
    "instanceId": "<string>",
    "alertUid": "<string>",
    "title": "<string>",
    "imageUrl": "<string>",
    "state": "<string>",
    "externalLink": "<string>",
    "channelId": "<string>",
    "phoneNumberIdentification": "<string>",
    "accessKey": "<string>",
    "appSid": "<string>",
    "senderId": "<string>",
    "tenantId": "<string>",
    "AppIOBaseUrl": "<string>",
    "signingSecret": "<string>",
    "outboundIntegrationId": "<string>",
    "useFromAddressOverride": true,
    "fromAddressOverride": "<string>",
    "emailSlugPrefix": "<string>",
    "externalEnvironmentId": "<string>",
    "externalVaultId": "<string>",
    "externalWorkspaceId": "<string>"
  },
  "configurations": {
    "inboundWebhookEnabled": true,
    "inboundWebhookSigningKey": "<string>"
  },
  "deletedAt": "<string>",
  "deletedBy": "<string>",
  "conditions": [
    {
      "isNegated": true,
      "children": [
        {
          "field": "<string>",
          "value": "<string>"
        }
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

​
idempotency-key
string

A header for idempotency purposes

Body

application/json
​
name
string

The name of the integration

​
identifier
string

The unique identifier for the integration

​
_environmentId
string<uuid>

The ID of the associated environment

​
providerId
string

The provider ID for the integration

​
channel
enum<string>

The channel type for the integration. Not required for agent-kind integrations.

Available options:
in_app,
email,
sms,
chat,
push
​
kind
enum<string>

Distinguishes delivery integrations from agent-runtime integrations. Defaults to "delivery". Agent integrations do not require a channel.

Available options:
delivery,
agent
​
credentials
object

The credentials for the integration

​
active
boolean

If the integration is active, the validation on the credentials field will run

​
check
boolean

Flag to check the integration status

​
conditions
object[]

Conditions for the integration

​
configurations
object

Configurations for the integration

Response

Created

​
_environmentId
string
required

The unique identifier for the environment associated with this integration. This links to the Environment collection.

​
_organizationId
string
required

The unique identifier for the organization that owns this integration. This links to the Organization collection.

​
name
string
required

The name of the integration, which is used to identify it in the user interface.

​
identifier
string
required

A unique string identifier for the integration, often used for API calls or internal references.

​
providerId
string
required

The identifier for the provider of the integration (e.g., "mailgun", "twilio").

​
active
boolean
required

Indicates whether the integration is currently active. An active integration will process events and messages.

​
deleted
boolean
required

Indicates whether the integration has been marked as deleted (soft delete).

​
primary
boolean
required

Indicates whether this integration is marked as primary. A primary integration is often the default choice for processing.

​
_id
string

The unique identifier of the integration record in the database. This is automatically generated.

​
channel
enum<string>

The channel type for the integration, which defines how it communicates (e.g., email, SMS). Not set for agent-kind integrations.

Available options:
in_app,
email,
sms,
chat,
push
​
kind
enum<string>

Distinguishes delivery integrations from agent-runtime integrations. Defaults to "delivery". Agent integrations do not have a channel.

Available options:
delivery,
agent
​
credentials
object

The decrypted credentials required for the integration to function (e.g. provider API keys, signing secrets). Only returned to dashboard/session-token callers; API-key authenticated callers receive the integration metadata without this field to avoid amplifying API-key leaks into provider-credential leaks.

​
configurations
object

The configurations required for enabling the additional configurations of the integration.

​
deletedAt
string

The timestamp indicating when the integration was deleted. This is set when the integration is soft deleted.

​
deletedBy
string

The identifier of the user who performed the deletion of this integration. Useful for audit trails.

​
conditions
object[]

An array of conditions associated with the integration that may influence its behavior or processing logic.