---
title: "Assign a new service along with role to a user"
method: POST
path: "/v1/api/users/{userExternalId}/services"
tags: ["Users"]
---

# Assign a new service along with role to a user

`POST /v1/api/users/{userExternalId}/services`

## Path parameters

- `userExternalId` string, required

## Request body

- string

## Response `200`

OK

- User
  - `_links` Link[]
    - `href` string
    - `method` string
    - `rel` string
  - `disabled` boolean
  - `email` string
  - `external_id` string
  - `features` string
  - `last_logged_in_at` string, date-time
  - `login_counter` integer
  - `otp_key` string
  - `password` string
  - `provisional_otp_key` string
  - `provisional_otp_key_created_at` string, date-time
  - `second_factor` 'SMS' | 'APP'
  - `service_roles` ServiceRole[]
    - `role` Role
      - `description` string
      - `name` 'admin' | 'view-and-refund' | 'view-only' | 'view-and-initiate-moto' | 'view-refund-and-initiate-moto' | 'super-admin'
      - `permissions` Permission[]
        - `description` string
        - `name` string
    - `service` Service
      - `_links` Link[]
        - `href` string
        - `method` string
        - `rel` string
      - `agent_initiated_moto_enabled` boolean
      - `archived` boolean
      - `archived_date` string, date-time
      - `collect_billing_address` boolean
      - `created_date` string, date-time
      - `current_go_live_stage` 'NOT_STARTED' | 'ENTERED_ORGANISATION_NAME' | 'ENTERED_ORGANISATION_ADDRESS' | 'CHOSEN_PSP_ADYEN' | 'CHOSEN_PSP_STRIPE' | 'CHOSEN_PSP_GOV_BANKING_WORLDPAY' | 'GOV_BANKING_MOTO_OPTION_COMPLETED' | 'TERMS_AGREED_ADYEN' | 'TERMS_AGREED_STRIPE' | 'TERMS_AGREED_GOV_BANKING_WORLDPAY' | 'DENIED' | 'LIVE'
      - `current_psp_test_account_stage` 'NOT_STARTED' | 'REQUEST_SUBMITTED' | 'CREATED'
      - `custom_branding` object
      - `default_billing_address_country` string
      - `experimental_features_enabled` boolean
      - `external_id` string
      - `gateway_account_ids` string[]
      - `id` integer
      - `internal` boolean
      - `merchant_details` MerchantDetails
        - `address_city` string
        - `address_country` string
        - `address_line1` string
        - `address_line2` string
        - `address_postcode` string
        - `email` string
        - `name` string
        - `telephone_number` string
        - `url` string
      - `name` string
      - `redirect_to_service_immediately_on_terminal_state` boolean
      - `sector` string
      - `service_features` object
      - `service_name` object
      - `takes_payments_over_phone` boolean
      - `went_live_date` string, date-time
  - `session_version` integer
  - `telephone_number` string

## Other responses

- `400` — Invalid payload
- `404` — User with userExternalId not found
- `409` — User already got access to service

## Changes

- **2026-08-03** `17f1bf916172` — 1 breaking
  - the `service_roles/items/service/service_features` response's property type/format changed from `array`/`` to `object`/`` for status `200`
- **2026-07-21** `1f9978f5e174` — 1 info
  - added the optional property `service_roles/items/service/service_features` to the response with the `200` status
- **2026-06-15** `7c2ffa5bfb93` — 2 warning
  - added the new `CHOSEN_PSP_ADYEN` enum value to the `service_roles/items/service/current_go_live_stage` response property for the response status `200`
  - added the new `TERMS_AGREED_ADYEN` enum value to the `service_roles/items/service/current_go_live_stage` response property for the response status `200`
- **2024-09-18** `d2be8133ead1` — 1 info
  - api operation id `createServiceRole` removed and replaced with `assignServiceAndRoleToUser`
- **2024-09-12** `3f6a3bbb9219` — 6 warning
  - added the new `admin` enum value to the `service_roles/items/role/name` response property for the response status `200`
  - added the new `super-admin` enum value to the `service_roles/items/role/name` response property for the response status `200`
  - added the new `view-and-initiate-moto` enum value to the `service_roles/items/role/name` response property for the response status `200`
  - added the new `view-and-refund` enum value to the `service_roles/items/role/name` response property for the response status `200`
  - …2 more

[Full history](https://skmtc.dev/government-digital-service/apis/adminusers-api/changes/v1/api/users/:userExternalId/services/post.md)

---

[API](https://skmtc.dev/government-digital-service/apis/adminusers-api.md) · [All operations](https://skmtc.dev/government-digital-service/apis/adminusers-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/government-digital-service/adminusers-api/revisions/8f9d543f352b/schema)