Create integration

Create an integration for the current environment the user is based on the API key provided

Enter your API key in the Authorization field like the example shown below:

E.g ApiKey 18d2e625f05d80e

cURL

curl --location 'https://api.novu.co/v1/integrations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
--data '{
    "name": "SES",
    "identifier": "ses-NkIQ5Koy3-123",
    "credentials": {
        "apiKey": "ACCESS_KEY_ID",
        "secretKey": "SECRET_ACCESS_KEY",
        "region": "us-east-2",
        "from": "FROM_EMAIL_ADDRESS",
        "senderName": "SENDER_NAME",
        // ... other credentials as per provider
    },
    "conditions": [],
    "active": true,
    "check": false,
    "providerId": "ses",
    "channel": "email"
}'

Response

{
  "data": {
    "_id": "string",
    "_environmentId": "string",
    "_organizationId": "string",
    "name": "string",
    "identifier": "string",
    "providerId": "string",
    "channel": "in_app",
    "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"
    },
    "active": true,
    "deleted": true,
    "deletedAt": "string",
    "deletedBy": "string",
    "primary": true
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

providerId

string

required

The provider ID for the integration

channel

enum<string>

required

The channel type for the integration

Available options:

in_app,

email,

sms,

chat,

push

name

string

The name of the integration

identifier

string

The unique identifier for the integration

_environmentId

string

The ID of the associated environment

credentials

object

The credentials for the integration

Show child attributes

credentials.apiKey

string

credentials.user

string

credentials.secretKey

string

credentials.domain

string

credentials.password

string

credentials.host

string

credentials.port

string

credentials.secure

boolean

credentials.region

string

credentials.accountSid

string

credentials.messageProfileId

string

credentials.token

string

credentials.from

string

credentials.senderName

string

credentials.projectName

string

credentials.applicationId

string

credentials.clientId

string

credentials.requireTls

boolean

credentials.ignoreTls

boolean

credentials.tlsOptions

object

credentials.baseUrl

string

credentials.webhookUrl

string

credentials.redirectUrl

string

credentials.hmac

boolean

credentials.serviceAccount

string

credentials.ipPoolName

string

credentials.apiKeyRequestHeader

string

credentials.secretKeyRequestHeader

string

credentials.idPath

string

credentials.datePath

string

credentials.apiToken

string

credentials.authenticateByToken

boolean

credentials.authenticationTokenKey

string

credentials.instanceId

string

credentials.alertUid

string

credentials.title

string

credentials.imageUrl

string

credentials.state

string

credentials.externalLink

string

credentials.channelId

string

credentials.phoneNumberIdentification

string

credentials.accessKey

string

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

Show child attributes

conditions.isNegated

boolean

required

conditions.type

enum<string>

required

Available options:

BOOLEAN,

TEXT,

DATE,

NUMBER,

STATEMENT,

LIST,

MULTI_LIST,

GROUP

conditions.value

enum<string>

required

Available options:

AND,

OR

conditions.children

object[]

required

Show child attributes

conditions.children.field

string

required

conditions.children.value

string

required

conditions.children.operator

enum<string>

required

Available options:

LARGER,

SMALLER,

LARGER_EQUAL,

SMALLER_EQUAL,

EQUAL,

NOT_EQUAL,

ALL_IN,

ANY_IN,

NOT_IN,

BETWEEN,

NOT_BETWEEN,

LIKE,

NOT_LIKE,

IN

conditions.children.on

enum<string>

required

Available options:

subscriber,

payload

Response

201

application/json

Created

data

object

Show child attributes

data._environmentId

string

required

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

data._organizationId

string

required

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

data.name

string

required

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

data.identifier

string

required

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

data.providerId

string

required

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

data.channel

enum<string>

required

The channel type for the integration, which defines how the integration communicates (e.g., email, SMS).

Available options:

in_app,

email,

sms,

chat,

push

data.credentials

object

required

The credentials required for the integration to function, including API keys and other sensitive information.

Show child attributes

data.credentials.apiKey

string

data.credentials.user

string

data.credentials.secretKey

string

data.credentials.domain

string

data.credentials.password

string

data.credentials.host

string

data.credentials.port

string

data.credentials.secure

boolean

data.credentials.region

string

data.credentials.accountSid

string

data.credentials.messageProfileId

string

data.credentials.token

string

data.credentials.from

string

data.credentials.senderName

string

data.credentials.projectName

string

data.credentials.applicationId

string

data.credentials.clientId

string

data.credentials.requireTls

boolean

data.credentials.ignoreTls

boolean

data.credentials.tlsOptions

object

data.credentials.baseUrl

string

data.credentials.webhookUrl

string

data.credentials.redirectUrl

string

data.credentials.hmac

boolean

data.credentials.serviceAccount

string

data.credentials.ipPoolName

string

data.credentials.apiKeyRequestHeader

string

data.credentials.secretKeyRequestHeader

string

data.credentials.idPath

string

data.credentials.datePath

string

data.credentials.apiToken

string

data.credentials.authenticateByToken

boolean

data.credentials.authenticationTokenKey

string

data.credentials.instanceId

string

data.credentials.alertUid

string

data.credentials.title

string

data.credentials.imageUrl

string

data.credentials.state

string

data.credentials.externalLink

string

data.credentials.channelId

string

data.credentials.phoneNumberIdentification

string

data.credentials.accessKey

string

data.active

boolean

required

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

data.deleted

boolean

required

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

data.primary

boolean

required

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

data._id

string

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

data.deletedAt

string

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

data.deletedBy

string

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

data.conditions

object[]

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

Show child attributes

data.conditions.isNegated

boolean

required

data.conditions.type

enum<string>

required

Available options:

BOOLEAN,

TEXT,

DATE,

NUMBER,

STATEMENT,

LIST,

MULTI_LIST,

GROUP

data.conditions.value

enum<string>

required

Available options:

AND,

OR

data.conditions.children

object[]

required

Show child attributes

data.conditions.children.field

string

required

data.conditions.children.value

string

required

data.conditions.children.operator

enum<string>

required

Available options:

LARGER,

SMALLER,

LARGER_EQUAL,

SMALLER_EQUAL,

EQUAL,

NOT_EQUAL,

ALL_IN,

ANY_IN,

NOT_IN,

BETWEEN,

NOT_BETWEEN,

LIKE,

NOT_LIKE,

IN

data.conditions.children.on

enum<string>

required

Available options:

subscriber,

payload