# Manage customer accounts

All API endpoints listed here are Workato Embedded Vendor APIs and require the oem_vendor privilege. Talk to your Workato representative to enable this privilege in your account.

# Quick reference

Type Resource Description
POST /api/managed_users Create customer account.
PUT /api/managed_users Update customer account.
GET /api/managed_users/:id Get customer account.
GET /api/managed_users/ Get a list of all customer accounts.
GET /api/managed_users/members Get a list of all members in a customer account.
GET /api/managed_users/members Get a list of all members in a customer account.
POST /api/managed_users/:id/members Add member to customer account.
DELETE /api/managed_users/:id/members/:member_id Remove member from customer account.
GET /api/managed_users/:id/connections List customer connections.
GET /api/managed_users/usage Get task usage of all customer accounts by month.
PUT /api/managed_users/:id/upgrade Upgrade customer account. (Deprecated)
PUT /api/managed_users/:id/downgrade Downgrade customer account. (Deprecated)
POST /api/managed_users/:id/member Add member to customer account. (Deprecated)
DELETE /api/managed_users/:id/member Remove member from customer account. (Deprecated)

Deprecated endpoints

Deprecated endpoints will continue to work but are not supported with the newest updates going forward.

# Create customer account

Create a new Workato Embedded customer account.

POST /api/managed_users

# Payload

Name Type Description
name string
required
Full name of the user.
notification_email string
required
Email for error notifications.
plan_id string
optional
Plan id. Default plan id is used when not provided.
external_id string
optional
External identifier for the Workato Embedded customer.
origin_url string
optional
Applies to embedded Workato Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page(E.g. customer specifc custom domains etc). Defaults to the origin configured at the account level.
time_zone string
optional
Timezone name. View this document for a list of timezones. Defaults to PST if not specified.

# Sample request

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Kevin Leary",
            "notification_email": "kevinl@acme.com",
            "external_id": "UU0239093498",
            "time_zone": "Central Time (US & Canada)"
          }'

# Response

{
  "id": 3498583,
  "external_id": "UU0239093498",
  "name": "Kevin Leary",
  "notification_email": "kevinl@acme.com",
  "plan_id": "oem_plan",
  "origin_url": null,
  "in_trial": true,
  "created_at": "2020-03-06T01:56:20.208Z",
  "updated_at": "2020-03-06T01:56:20.625Z",
  "time_zone": "Central Time (US & Canada)"
}

# Update customer account

PUT /api/managed_users/:id

Update an existing Workato Embedded customer account's:

  • Name
  • External ID
  • Error notification email address
  • Plan
  • Trial state

Additional notes:

  • For customers in task-based plans, use this endpoint to update the task limit override and make a one-time adjustment.
  • For partners using Workato embedded, use this endpoint to update the custom origin URL of a specific customer

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.

# Payload

Name Type Description
name string
optional
Full name of the user.
notification_email string
optional
Email for error notifications.
external_id string
optional
External identifier for the Workato Embedded customer.
origin_url string
optional
Applies to embedded Workato Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page(E.g. customer specifc custom domains etc). Defaults to the origin configured at the account level.
plan_id string
optional
The ID of the plan
in_trial boolean
optional
Downgrade or upgrade the user to/from a free plan and subscription plan
task_limit_adjustment string
optional
Task limit adjustment for current accounting period. Only valid for task-based plans. This adjustment will not apply to subsequent periods. Make a negative adjustment by adding "-" (eg. "-5000").
custom_task_limit string
optional
Overrides the current plan limit.
time_zone string
optional
Timezone name. View this document for a list of timezones. Defaults to PST if not specified.

User property is updated only if the payload contains the property. To clear the value of a property, set the property to null in the payload.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/3498583 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Kevin K Leary",
            "notification_email": "kevinl+workatodevops@acme.com"
          }'

# Response

{
    "id": 3498583,
    "external_id": "",
    "name": "Kevin K Leary",
    "notification_email": "kevinl+workatodevops@acme.com",
    "plan_id": "task_plan_1",
    "origin_url": null,
    "trial": false,
    "in_trial": false,
    "created_at": "2019-05-16T21:21:48.320-07:00",
    "updated_at": "2020-10-02T02:49:42.644-07:00",
    "current_billing_period_start": "2020-09-22T19:15:11.372-07:00",
    "current_billing_period_end": "2020-10-22T19:15:11.372-07:00",
    "task_limit_adjustment": null,
    "task_limit": 20000,
    "task_count": 0,
    "active_connection_limit": 0,
    "active_connection_count": 8,
    "active_recipe_count": 0,
    "time_zone": "Alaska"
}

# Get customer account

Get Workato Embedded customer account details.

GET /api/managed_users/:id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/27819 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "id": 4243,
    "external_id": "",
    "name": "Abstergo Industries",
    "notification_email": "ann@abstergo.com",
    "plan_id": "tbp_wrike_monthly_1",
    "origin_url": null,
    "trial": false,
    "in_trial": false,
    "created_at": "2019-05-16T21:21:48.320-07:00",
    "updated_at": "2020-09-23T04:01:26.844-07:00"
}

# Get list of customer accounts

Get a list of all customer accounts. This endpoint returns the data in the customer table of the admin console.

GET /api/managed_users/

TIP

The task count returned here refers to the tasks done in the billing period of the customer.

Name Type Description
page integer Page number. Defaults to 1.
per_page integer Page size. Defaults to 100 (maximum is 100).

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/ \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "result": [
        {
            "id": 4243,
            "external_id": "",
            "name": "Abstergo",
            "notification_email": "ann@abstergo.com",
            "plan_id": "plan_tier1",
            "origin_url": null,
            "trial": false,
            "in_trial": false,
            "created_at": "2019-05-16T21:21:48.320-07:00",
            "updated_at": "2020-10-01T02:59:32.845-07:00",
            "current_billing_period_start": "2020-09-18T05:34:50.215-07:00",
            "current_billing_period_end": "2020-10-18T05:34:50.215-07:00",
            "task_limit_adjustment": null,
            "task_limit": 20000,
            "task_count": 16777,
            "active_connection_limit": 0,
            "active_connection_count": 8,
            "active_recipe_count": 0
        },
        {
            "id": 4772,
            "external_id": "101",
            "name": "Carly's Company",
            "notification_email": "carly.frederick@w.com",
            "plan_id": "business_yearly",
            "origin_url": null,
            "trial": false,
            "in_trial": false,
            "created_at": "2019-07-30T12:39:59.895-07:00",
            "updated_at": "2020-07-20T15:30:07.168-07:00",
            "time_zone": "Pacific Time (US & Canada)",
            "current_billing_period_start": "2020-09-30T12:39:59.936-07:00",
            "current_billing_period_end": "2020-10-30T12:39:59.936-07:00",
            "task_count": 0,
            "active_connection_limit": 0,
            "active_connection_count": 0,
            "active_recipe_count": 0
        }
      ]
}

# Get list of customer account members

Get a full list of team members in a customer account. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, time_zone of the all the members.

GET /api/managed_users/:id/members

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/124125/members \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

[
    {
        "id": 1680,
        "grant_type": "team",
        "role_name": "Admin",
        "external_id": null,
        "name": "James Bourne",
        "email": "jason_bourne@workato.com",
        "time_zone": "Pacific Time (US & Canada)"
    },
    {
        "id": 2641,
        "grant_type": "customer_manager",
        "role_name": "Admin",
        "external_id": null,
        "name": "Jason Bond",
        "email": "jason_bond@workato.com",
        "time_zone": "Eastern Time (US & Canada)"
    }
]

# Get customer account member

Get information for a specific team member in a customer account. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, time_zone of the specified member.

GET /api/managed_users/:id/members/:member_id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.
member_id string
required
The ID of the member.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/124/members/1680 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "id": 1680,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": null,
    "name": "James Bourne",
    "email": "jason_bourne@workato.com",
    "time_zone": "Pacific Time (US & Canada)"
}

# Add member to customer account

Add a member to the Workato Embedded customer account.

POST /api/managed_users/:id/members

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.

# Payload

Name Type Description
name string
required
Full name of the user.
oauth_id string
optional
Identifier used for OAuth.
role_name string
optional
Role name.
external_id string
optional
External identifier for the member.
time_zone string
optional
Timezone name. View this document for a list of timezones. Defaults to PST if not specified.

# Sample request

curl  -X POST https://www.workato.com/api/managed_users/27819/members \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "role_name": "Admin",
            "external_id": "UU0239093499"
          }'

# Response

{
  "id": 3498583,
  "plan_id": "oem_plan",
  "trial": false,
  "time_zone": "Pacific Time (US & Canada)"
}

# Remove member from customer account

Remove a member from the Workato Embedded customer's account. This does not permanently delete a customer team member's Workato account, it removes the member from the team.

DELETE /api/managed_users/:id/members/:member_id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.
member_id string
required
Member id

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/27819/members/12314' \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Response

{
  "id": 3485434779
}

# List customer connections

Get the list of connections in Workato Embedded customer's account.

GET /api/managed_users/:id/connections

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External id should be prefixed with a E(eg: EA2300) and the resulting id should be URL encoded.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/27819/connections \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
  "result": [
    {
      "id": 6132,
      "name": "My Box account",
      "provider": "box",
      "authorization_status": "success",
      "authorized_at": "2019-09-10T18:20:08.854-07:00",
      "created_at": "2019-09-10T18:19:57.437-07:00",
      "updated_at": "2019-09-10T18:20:08.859-07:00"
    },
    {
      "id": 6131,
      "name": "My Salesforce account",
      "provider": "salesforce",
      "authorization_status": "success",
      "authorized_at": "2019-09-10T18:19:43.018-07:00",
      "created_at": "2019-09-10T18:19:12.902-07:00",
      "updated_at": "2019-09-10T18:19:43.021-07:00"
    }
  ]
}

# Get monthly usage

Get a list of monthly usage for all customers for the last 12 months. Task data is currently the only data available.

GET /api/managed_users/usage

TIP

The task count by customer returned here is the total of all tasks done in that calendar month. If the plan of the customer has changed and the billing date/usage is reset, the total usage across plans will still be obtained here.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/usage \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

This response below has been truncated from 12 to 3 months.

{
   "result":{
      "data":[
         {
            "user_id": 7443,
            "intervals":[
               {
                  "start_datetime": "2019-10-01T00:00:00.000-07:00",
                  "task_count": null
               },
               {
                  "start_datetime": "2019-11-01T00:00:00.000-07:00",
                  "task_count": null
               },
               {
                  "start_datetime": "2020-10-01T00:00:00.000-07:00",
                  "task_count": 0
               }
            ]
         }
      ],
      "generated_at":"2020-10-02T05:41:29.232-07:00"
   }
}