Product UpdatesStatus PageAutomation Institute
English
Embedded API
Resources

# Workato API - Connections

WHO CAN USE THESE ENDPOINTS?

The endpoints in this guide are Embedded Vendor APIs and require the oem_vendor privilege. Contact your Workato representative to enable this privilege in your account.

The Connections resource enables you to programmatically manage connections for Embedded customers.

# Quick Reference

Type Resource Description
GET /api/managed_users/:managed_user_id/connections Returns a list of connections in Embedded user's account.
POST /api/managed_users/:id/connections Allows the Embedded partner to add a shell connection in a customer's account.
PUT /api/managed_users/:id/connections/:connection_id Updates a connection in a customer workspace.
POST /api/managed_users/:id/connections/:connection_id/disconnect Disconnects a connection in a customer workspace.
DELETE /api/managed_users/:id/connections/:connection_id Deletes a disconnected connection in a customer workspace.

# List Connections

Returns all connections and associated data for the Embedded customer workspace.

GET /api/managed_users/:managed_user_id/connections

# URL Parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (ex: EA2300) and the resulting ID should be URL encoded.

# Payload

Include the following properties in the request body to filter results:

Name Type Description
provider string
optional		 The application type of the connection. For example: salesforce
folder_id string
optional		 The ID of the project or folder containing the connection.
parent_id string
optional		 The ID of the parent connection. The parent connection must be the same provider type. Learn more.
external_id string
optional		 The external ID assigned to the connection, usually given to the user who owns the connection.
include_runtime_connections string
optional		 When "true" is supplied, all runtime user connections are also returned.

# Sample Request

curl  -X GET https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>'

# Response

{
 "result": [
   {
     "id": 36,
     "name": "ACME Production Salesforce connection",
     "provider": "salesforce",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": null,
     "parent_id": 22316
   },
   {
     "id": 37,
     "name": "ACME google sheet account",
     "provider": "google_sheets",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": null,
     "parent_id": 22317
   },
   {
     "id": 51234,
     "name": "ACME Quickbooks account",
     "provider": "quickbooks",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": "acme@workato.com/1029384756102938",
     "parent_id": 22317
   }
 ]
}

Retrieve Quickbooks Realm ID

Retrieve your company's Quickbooks Realm ID using the List connections API. Disconnect and reconnect your Quickbooks connection in Workato before calling the API. The Realm ID is returned in the identity field in the response following your email address. In the preceding example, ACME's Realm ID is 1029384756102938. For other connections, the identity field is returned as null.

# Create A Connection

Creates a connection in a customer's account. This endpoint supports the following in customer workspaces:

  • Adding a shell connection, OR
  • Adding and authenticating a connection
POST /api/managed_users/:managed_user_id/connections

# URL Parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (ex: EA2300) and the resulting ID should be URL encoded.

# Payload

Name Type Description
name string
optional		 Name of the connection. Eg: Prod Salesforce connection
provider string
optional		 The application type of the connection. For example: salesforce
parent_id string
optional		 The ID of the parent connection. The parent connection must be the same provider type. Learn more.
folder_id string
optional		 The ID of the project or folder containing the connection.
external_id string
optional		 The external ID assigned to the connection, usually given to the user who owns the connection.
input Object
optional		 Connection parameters.

For a list of providers and connection parameters, refer to the Platform API Connection Parameter Reference.

# Sample Requests

# Shell connection request

This creates a connection in a Disconnected state.

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "folder_id": 1892,
            "external_id": "128904"
          }'

# Connection with credentials

This creates and authenticates a connection.

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

# Response

{
   "id":36,
   "name":"jira_connection",
   "provider":"jira",
   "authorized_at":"2015-05-26T22:53:52.528Z",
   "authorization_status":"success",
   "authorization_error":null,
   "created_at":"2015-05-26T22:53:52.532Z",
   "updated_at":"2015-05-26T22:53:52.532Z",
   "external_id":"U12904",
   "folder_id":4515,
   "parent_id":22318
}

# Update A Connection

Updates a connection in a customer workspace.

PUT /api/managed_users/:managed_user_id/connections/:connection_id

# URL Parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (ex: EA2300) and the resulting ID should be URL encoded.
connection_id string
required		 The ID of the connection.

# Payload

Name Type Description
name string
optional		 Name of the connection. Ex: Prod Salesforce connection
parent_id string
optional		 The ID of the parent connection. Learn more.
folder_id string
optional		 The ID of the project or folder containing the connection.
external_id string
optional		 An external ID assigned to the connection. This value could reference a record in another of your applications.
input object
optional		 Connection parameters.

For a list of providers and connection parameters, refer to the Platform API Connection Parameter Reference.

# Sample Requests

# Update a Jira connection

curl  -X PUT https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection_latest",
            "folder_id": 28940,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

# Response

{
   "id":36,
   "name":"jira_connection",
   "provider":"jira",
   "authorized_at":"2015-05-26T22:53:52.528Z",
   "authorization_status":"success",
   "authorization_error":null,
   "created_at":"2015-05-26T22:53:52.532Z",
   "updated_at":"2015-05-26T22:53:52.532Z",
   "external_id":"U12904",
   "folder_id":4515,
   "parent_id":22318
}

# Update an Outreach connection

curl  -X PUT https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Outreach scope connection",
            "provider": "outreach",
            "input": {
              "advanced_settings": {
                "scopes": "sequences.all phoneNumbers.all"
              }
        }
    }'

# Disconnect a Connection

Disconnects an active connection in a customer workspace. If the connection is already disconnected, then no action is taken.

POST /api/managed_users/:managed_user_id/connections/:connection_id/disconnect

# URL Parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (ex: EA2300) and the resulting ID should be URL encoded.
connection_id string
required		 The ID of the connection.
force boolean
optional		 Value must be true to forcefully disconnect an active connection used by active recipes. Defaults to false.

# Payload

No payload is expected

# Sample Request

curl  -X POST https://www.workato.com/api/managed_users/98178/connections/1678/disconnect?force=true \
      -H 'Authorization: Bearer <api_token>'

# Response

  • Successfully disconnected an active connection or connection already disconnected.
{
   "result": {
    "success": true,
    "status": "disconnected"
   }
}
  • Provided connection id does not exist
{
   "message": "Not found"
}

# Delete a Connection

Deletes a disconnected connection in a customer workspace. If the connection is active or used by active recipes, this API request will fail.

DELETE /api/managed_users/:managed_user_id/connections/:connection_id

# URL Parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (ex: EA2300) and the resulting ID should be URL encoded.
connection_id string
required		 The ID of the connection.

# Sample Request

curl  -X DELETE https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>'

# Response

  • Successfully disconnected an active connection or connection already disconnected.
{
   "result": {
    "success": true,
    "status": "deleted"
   }
}
  • Provided connection is active
{
   "success": false,
   "status": "rejected",
   "message": "You can't delete a an active connection"
}
  • Provided connection is used in active recipes
{
   "success": false,
   "status": "rejected",
   "message": "You can't delete a connection used by active recipes"
}
  • Provided connection id does not exist
{
   "message": "Not found"
}
← Refresh token/secret
Connection parameters reference →


Last updated: 4/25/2024, 5:58:27 PM

On this page