Connect Integration

curl --request POST \
  --url https://api.example.com/integrations/{integrationType}/connect \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalUserIdentifier": "<string>",
  "passthroughRedirectUri": "<string>",
  "dc": "<string>",
  "scopes": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/integrations/{integrationType}/connect"

payload = {
    "externalUserIdentifier": "<string>",
    "passthroughRedirectUri": "<string>",
    "dc": "<string>",
    "scopes": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalUserIdentifier: '<string>',
    passthroughRedirectUri: '<string>',
    dc: '<string>',
    scopes: ['<string>']
  })
};

fetch('https://api.example.com/integrations/{integrationType}/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/integrations/{integrationType}/connect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalUserIdentifier' => '<string>',
    'passthroughRedirectUri' => '<string>',
    'dc' => '<string>',
    'scopes' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/integrations/{integrationType}/connect"

	payload := strings.NewReader("{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/integrations/{integrationType}/connect")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/integrations/{integrationType}/connect")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "authUrl": "https://api.notion.com/v1/oauth/authorize?client_id=..."
}

POST

integrations

{integrationType}

connect

Connect Integration

curl --request POST \
  --url https://api.example.com/integrations/{integrationType}/connect \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalUserIdentifier": "<string>",
  "passthroughRedirectUri": "<string>",
  "dc": "<string>",
  "scopes": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/integrations/{integrationType}/connect"

payload = {
    "externalUserIdentifier": "<string>",
    "passthroughRedirectUri": "<string>",
    "dc": "<string>",
    "scopes": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalUserIdentifier: '<string>',
    passthroughRedirectUri: '<string>',
    dc: '<string>',
    scopes: ['<string>']
  })
};

fetch('https://api.example.com/integrations/{integrationType}/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/integrations/{integrationType}/connect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalUserIdentifier' => '<string>',
    'passthroughRedirectUri' => '<string>',
    'dc' => '<string>',
    'scopes' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/integrations/{integrationType}/connect"

	payload := strings.NewReader("{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/integrations/{integrationType}/connect")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/integrations/{integrationType}/connect")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalUserIdentifier\": \"<string>\",\n  \"passthroughRedirectUri\": \"<string>\",\n  \"dc\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "authUrl": "https://api.notion.com/v1/oauth/authorize?client_id=..."
}

Start the OAuth flow to connect a third-party integration.

URL Parameters

string

required

The type of integration to connect. Valid values:

google-analytics
notion
slack
zoho
gmail

Request

string

required

Unique identifier for the user in your system

string

required

The URL to redirect to after OAuth completion

string

Data center for Zoho integration (e.g., ‘com’, ‘eu’)

string[]

Additional OAuth scopes for Zoho integration

Response

string

The OAuth authorization URL to redirect the user to

Example

curl -X POST https://suada.ai/api/public/integrations/notion/connect \
  -H "Authorization: Bearer sk-suada-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserIdentifier": "user-123",
    "passthroughRedirectUri": "https://your-app.com/oauth/callback"
  }'

import { Suada } from '@suada/node';

const suada = new Suada({
  apiKey: 'your-api-key'
});

const { authUrl } = await suada.connectIntegration('notion', {
  externalUserIdentifier: 'user-123',
  passthroughRedirectUri: 'https://your-app.com/oauth/callback'
});

// Redirect user to authUrl
window.location.href = authUrl;

from suada import Suada, SuadaConfig

suada = Suada(
    config=SuadaConfig(
        api_key="your-api-key"
    )
)

result = suada.connect_integration(
    integration_type="notion",
    external_user_identifier="user-123",
    passthrough_redirect_uri="https://your-app.com/oauth/callback"
)

# Redirect user to result.auth_url

{
  "authUrl": "https://api.notion.com/v1/oauth/authorize?client_id=..."
}

Integration-Specific Parameters

Google Analytics

No additional parameters required.

Notion

No additional parameters required.

Slack

No additional parameters required.

Zoho

string

default:"com"

Zoho data center:

com - US data center
eu - EU data center
in - India data center
com.cn - China data center
com.au - Australia data center

string[]

List of Zoho API scopes to request. Default scopes include:

ZohoCRM.modules.ALL
ZohoBooks.fullaccess.ALL
ZohoProjects.projects.ALL

Gmail

No additional parameters required.

Error Codes

object

Invalid request

{
  "error": "Missing required parameters"
}

object

Authentication error

{
  "error": "Invalid or expired API key"
}

object

Server error

{
  "error": "Failed to initialize OAuth flow"
}

Notes

The OAuth flow is a multi-step process:
1. Call this endpoint to get the authorization URL
2. Redirect the user to the authorization URL
3. User authorizes your application
4. Integration provider redirects to your callback URL
5. Call the callback endpoint to complete the flow
The passthroughRedirectUri should be a URL in your application that can handle the OAuth callback
Store the externalUserIdentifier to associate the integration with the correct user after the callback

Chat

Integrations

Connect Integration

URL Parameters

Request

Response

Example

Integration-Specific Parameters

Google Analytics

Notion

Slack

Zoho

Gmail

Error Codes

Notes

​URL Parameters

​Request

​Response

​Example

​Integration-Specific Parameters

​Google Analytics

​Notion

​Slack

​Zoho

​Gmail

​Error Codes

​Notes

URL Parameters

Request

Response

Example

Integration-Specific Parameters

Google Analytics

Notion

Slack

Zoho

Gmail

Error Codes

Notes