Skip to main content
POST
/
poweredby
/
connection
/
create
Create Connection
curl --request POST \
  --url https://cloud.cdata.com/api/poweredby/connection/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataSource": "ExcelOnline",
  "redirectURL": "https://www.google.com",
  "name": "ExcelConnection",
  "externalId": "acme-excel-001"
}
'
{
  "redirectURL": "https://cloud.cdata.com/oem/user/connections/edit?token=eyJhbGciOiJSUzI1NiIs...truncated...&driver=ExcelOnline&redirectUrl=https%3A%2F%2Fwww.google.com"
}
Create Connection requests the Connection Create Flow from the Connect AI Embed product. Create Connection validates the JWT and returns a string containing the URL to redirect the user to. If you include the parameter dataSource, the URL redirects the user to an Add Connection page for the data source. If you omit dataSource, the URL redirects the user to a general Add Connection page where the user can select a connection to add from the connections list. A successful Create Connection has the following flow:
1
A successful Create Connection request generates a URL to the CData-hosted Add Connection page. The redirectURL in the request body maps to the Return to button on the Add Connection page.
2
The user clicks Save & Test. The internal API response includes connection details to the CData-hosted Add Connection page.
3
The user clicks Return to. The connection information is appended to the redirect URL as parameters.The parameters include the following:
  • cdata_connection_id–the connection unique Id.
  • cdata_connection_name–the connection name, such as Salesforce1.
  • cdata_connection_status–the connection status. Values include success, error (connection error), or none (no connection made).
Example 1: URL after successful Save & Test: 
https://www.google.com/?cdata_connection_id=da77460c-7438-4288-be66-ea0059c160ae&cdata_connection_name=OData1&cdata_connection_status=success&zx=1773244250880&no_sw_cr=1
Example 2: URL if the user clicks Return to and does not Save & Test: 
https://www.google.com/?cdata_connection_status=none&zx=1773252769892&no_sw_cr=1
Example 3: URL after save and unsuccessful test: 
https://www.google.com/?cdata_connection_id=507b42e8-94b1-488e-a1d8-5a62d5d74a31&cdata_connection_name=Salesforce1&cdata_connection_status=error&zx=1773252951878&no_sw_cr=1

Authorizations

​
Authorization
string
header
required

JWT token authentication. Include the token in the Authorization header as Bearer {token}. See Authentication [blocked] for more information on creating a token.

Body

application/json
​
redirectURL
string
required

The URL to redirect the customer once the customer has created the connection through the Connect AI UI. This URL maps to the Return to button on the Add Connection page in the Connect AI UI.

​
dataSource
string | null

(Optional) The type of data source (For example: Snowflake, ActOn, or Salesforce). You can obtain data source names from List Connections. If you omit this parameter, the user can select from a list of available data sources.

​
name
string | null

(Optional) If provided, the connection name. By default, this is a suggested default that the end user can change on the Add Connection form. Set editableName to false to lock the field to this value. If name is provided without a dataSource, it is ignored.

​
externalId
string | null

(Optional) Your identifier for this connection in your own system. Must be unique within the sub-account; if a connection with the same externalId already exists under the account, the request returns a conflict error.

​
editableName
boolean
default:true

(Optional) The default value is true. When true, any name you supply is shown as a suggested default value, and the end user can change it. When false, the Connection Name field is rendered read-only, and the server enforces the supplied name on submit. Has no effect when name is omitted.

Response

200 - application/json

A string containing the CData-hosted connection URL to redirect the user to.

​
redirectURL
string
required

A string containing the CData-hosted connection URL to redirect the user to.