> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Identity Service Accounts

> Create, read and update Identity Service Accounts through the Moveworks Configuration API: endpoints, fields and examples.

`platform.identity.service-accounts`

Manually-defined service/admin accounts (user-profile fields + per-system ITSM/IDM/channel identities).

* **Endpoint:** `/platform/identity/service-accounts`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch. Send only the fields you change, plus `version: {num, change_description}` with the `num` from your last read. Lists and maps you send replace the stored ones whole.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                       | Endpoint reference                                                                                                       |
| ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `GET`   | `/platform/identity/service-accounts`      | [List service accounts](/api-reference/configuration-api/platform-org/identity-service-accounts/list-service-accounts)   |
| `POST`  | `/platform/identity/service-accounts`      | [Create service account](/api-reference/configuration-api/platform-org/identity-service-accounts/create-service-account) |
| `GET`   | `/platform/identity/service-accounts/{id}` | [Get service account](/api-reference/configuration-api/platform-org/identity-service-accounts/get-service-account)       |
| `PATCH` | `/platform/identity/service-accounts/{id}` | [Update service account](/api-reference/configuration-api/platform-org/identity-service-accounts/update-service-account) |

### Fields

| Field                    | Type                  | Required  | Notes                                                                                                                                                                                                                                       |
| ------------------------ | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | string                | read-only | Unique identifier of the service account, assigned by the server.                                                                                                                                                                           |
| `email_addr`             | string                |           | Email address of the user in your primary identity system.                                                                                                                                                                                  |
| `record_id`              | string                | ✅         | Value that identifies this user across your systems, typically the email address. Must match your organization's joining key and be unique across service accounts. Required on create.                                                     |
| `full_name`              | string                |           | Full name of the user.                                                                                                                                                                                                                      |
| `user_name`              | string                |           | Username of the user.                                                                                                                                                                                                                       |
| `first_name`             | string                |           | First name of the user.                                                                                                                                                                                                                     |
| `last_name`              | string                |           | Last name of the user.                                                                                                                                                                                                                      |
| `role`                   | string                |           | Role or job title of the user.                                                                                                                                                                                                              |
| `manager_email_addr`     | string                |           | Email address of the user's manager.                                                                                                                                                                                                        |
| `department`             | string                |           | Department of the user.                                                                                                                                                                                                                     |
| `location`               | string                |           | Location of the user.                                                                                                                                                                                                                       |
| `country_code`           | string                |           | Country code of the user.                                                                                                                                                                                                                   |
| `city`                   | string                |           | City of the user.                                                                                                                                                                                                                           |
| `region`                 | string                |           | Region of the user.                                                                                                                                                                                                                         |
| `division`               | string                |           | Division of the user.                                                                                                                                                                                                                       |
| `timezone`               | string                |           | Timezone of the user.                                                                                                                                                                                                                       |
| `employee_id`            | string                |           | Employee ID of the user.                                                                                                                                                                                                                    |
| `cost_center_name`       | string                |           | Cost center name of the user.                                                                                                                                                                                                               |
| `work_status`            | string                |           | Employment classification of the user. One of: CONTINGENT, INTERN, FULL_TIME.                                                                                                                                                               |
| `additional_email_addrs` | array\<string>        |           | Additional email addresses that identify this user.                                                                                                                                                                                         |
| `channel_id_info`        | array\<ChannelIdInfo> |           | Identities of the user in each connected chat system.                                                                                                                                                                                       |
| `itsm_id_info`           | array\<ITSMIdInfo>    |           | Identities of the user in each connected ITSM system. Each entry enables built-in ticketing for that system.                                                                                                                                |
| `idm_id_info`            | array\<IDMIdInfo>     |           | Identities of the user in each connected identity management system. Each entry enables access requests for that system.                                                                                                                    |
| `tags`                   | array\<enum>          |           | Moveworks user tags assigned to the user, e.g. VIP, IT_AGENT, TESTER or SERVICE_ACCOUNT. One of: `BASIC_USER`, `VIP`, `FIELD_AGENT`, `KNOWLEDGE_WORKER`, `IT_AGENT`, `TESTER`, `SUPPORTED_LANGUAGE_USER`, `SERVICE_ACCOUNT`, … (16 values). |
| `custom_attributes`      | object                |           | Custom attributes attached to the user. Replaced as a whole on update.                                                                                                                                                                      |
| `updated_time`           | string                | read-only | When the configuration was last updated.                                                                                                                                                                                                    |
| `updated_by`             | string                | read-only | Who last updated the configuration.                                                                                                                                                                                                         |
| `version`                | Version               | ✅         | Document version. On update, send back the num from your last read.                                                                                                                                                                         |

### Example create body

```json
{
  "email_addr": "user@example.com",
  "record_id": "<id>",
  "full_name": "example-name",
  "user_name": "example-name",
  "first_name": "example-name",
  "last_name": "example-name",
  "role": "<string>",
  "manager_email_addr": "user@example.com",
  "department": "<string>",
  "version": {
    "change_description": "Create service account"
  }
}
```