Custom connectors

WHO CAN USE THESE ENDPOINTS?

The endpoints in this guide are Embedded APIs and require an Embedded workspace. Contact your Workato representative for more information.

The Custom connectors resource enables you to programmatically manage your shared connectors.

Rate limits

Custom connector resources have the following rate limit:

Type	Resource	Limit
All	All Custom connectors endpoints	60 requests per minute

Quick Reference

The Custom Connectors resource contains the following endpoints:

Type	Resource	Description
GET	/api/custom_connectors	Get custom connectors.
GET	/api/custom_connectors/:id	Get custom connector by ID.
POST	/api/custom_connectors/:id/oem_share/:version	Create or update a shared connector.
POST	/api/managed_users/:managed_user_id/recipes/:recipe_id/share	Share/publish a recipe containing a custom connector.
DELETE	/api/custom_connectors/:id/suppress_oem_version	Remove a shared connector.

---

Search Custom Connectors

List custom adapters in your Workspace.

GET /api/custom_connectors

URL parameters

Name	Type	Description
title	string optional	Search for connectors by their titles. Partial matches will be returned.
oem_shared	boolean optional	Search for connectors that are shared from your OEM master account.

Sample Request

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

Response

{
    "result": [
        {
            "id": 3067,
            "name": "new_connector_1_connector_4771_1626869205",
            "title": "Foobar",
            "latest_released_version": null,
            "latest_released_version_note": null,
            "oem_shared_version": null,
            "oem_shared_at": null,
            "released_versions": []
        },
        {
            "id": 3066,
            "name": "new_connector_1_connector_4771_1626869114",
            "title": "Acme Connector",
            "latest_released_version": 4,
            "latest_released_version_note": null,
            "oem_shared_version": 2,
            "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
            "released_versions": [
                {
                    "version": 4,
                    "version_note": null,
                    "created_at": "2022-08-11T07:24:58.890-07:00",
                    "released_at": "2021-09-26T21:33:41.713-07:00"
                },
                {
                    "version": 2,
                    "version_note": "hello",
                    "created_at": "2021-07-21T05:05:34.136-07:00",
                    "released_at": "2021-09-26T21:33:41.713-07:00"
                }
            ]
        }
    ]
}

---

Get Custom Connector by ID

Retrieve a specific custom connector by ID.

GET /api/custom_connectors/:id

Path parameters

Name	Type	Description
id	integer required	The ID of the connector in your Workspace.

Sample Request

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

Response

{
    "result": [
        {
            "id": 3066,
            "name": "new_connector_1_connector_4771_1626869114",
            "title": "Acme Connector",
            "latest_released_version": 2,
            "latest_released_version_note": "V2",
            "oem_shared_version": 2,
            "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
            "released_versions": [
                {
                    "version": 2,
                    "version_note": "V2",
                    "created_at": "2021-07-21T05:05:34.136-07:00",
                    "released_at": "2021-09-26T21:33:41.713-07:00"
                }
            ]
        }
    ]
}

---

Upsert version of Shared Connector

Creates or updates the version of a Shared Connector in an OEM Master Account.

• If the connector is not currently shared, this creates a new shared connector at the specified version.
• If the connector is currently shared, this updates the version currently shared for this connector.

IMPORTANT

The version shared must be a released version.

POST /api/custom_connectors/:id/share_oem_version/:version

Path parameters

Name	Type	Description
id	integer required	The ID of the connector in your Workspace to share.
version	integer required	The version of the connector in your Workspace to share. This must be a released version.

Sample Request

curl  -X POST https://www.workato.com/api/custom_connectors/3066/share_oem_version/4 \
      -H 'Authorization: Bearer <api_token>'

Response

• New shared connector created:

{
    "result": {
        "success": true,
        "status": "created"
    }
}

• Existing shared connector version updated:

{
    "result": {
        "success": true,
        "status": "updated"
    }
}

---

Publish/share a recipe containing a Custom Connector

Allows you to publish a recipe containing a custom connector to your Private Community or share it with customers you specify.

IMPORTANT

You must share your custom connector with the Embedded customer/ Private Community using the /api/custom_connectors/:id/oem_share/:version endpoint prior to using this endpoint. Otherwise, Workato displays an error message.

POST api/managed_users/:managed_user_id/recipes/:recipe_id/share

Path parameters

Name	Type	Description
managed_user_id	string required	The account ID/external ID of the Embedded customer. The external should be prefixed with a E(ex.: EA2300) and the resulting ID should be URL encoded.
recipe_id	string required	The ID of the recipe you plan to share/publish.

Sample request

curl  -X POST https://www.workato.com/api/managed_users/12345/recipes/123/share \
      -H 'Authorization: Bearer <api_token>'

Response

{
    "result": {
        "success": true
    }
}

---

Remove Shared Connector

Removes a shared connector. This does not delete the custom connector from your workspace.

IMPORTANT

Using this API whilst there are customers accounts using this connector will impact their recipes.

DELETE /api/custom_connectors/:id/suppress_oem_version

Path parameters

Name	Type	Description
id	integer required	The ID of the shared connector in your Workspace to remove.

Sample Request

curl  -X DELETE https://www.workato.com/api/custom_connectors/3066/suppress_oem_version \
      -H 'Authorization: Bearer <api_token>'

Response

• New shared connector created:

{
    "result": {
        "success": true,
        "status": "suppressed"
    }
}

---