openapi: 3.1.0
info:
  title: Slack Migration API
  description: "Slack\x19s Migration API is a Web API used during Enterprise Grid migrations to translate legacy, workspace-scoped identifiers into their new, canonical IDs so apps keep working after a
    workspace moves or merges. By calling its migration.exchange method, developers and admins can map old user and channel IDs to the new values that Slack assigns in an Enterprise Grid org, allowing databases,
    webhooks, event subscriptions, and app configurations to be updated without losing references. It complements Admin and SCIM APIs in a migration runbook, but it doesn\x19t move content or provision
    accounts\x14it strictly provides ID remapping to preserve continuity."
paths:
  /migration.exchange:
    get:
      tags:
      - Exchange
      - Get
      - Migrations
      description: For Enterprise Grid workspaces, map local user IDs to global user IDs
      externalDocs:
        description: API method documentation
        url: https://api.slack.com/methods/migration.exchange
      operationId: getMigrationExchange
      parameters:
      - name: token
        in: query
        description: 'Authentication token. Requires scope: `tokens.basic`'
        required: true
        schema:
          type: string
      - name: users
        in: query
        description: A comma-separated list of user ids, up to 400 per request
        required: true
        schema:
          type: string
      - name: team_id
        in: query
        description: Specify team_id starts with `T` in case of Org Token
        schema:
          type: string
      - name: to_old
        in: query
        description: >-
          Specify `true` to convert `W` global user IDs to workspace-specific
          `U` IDs. Defaults to `false`.
        schema:
          type: boolean
      responses:
        '200':
          description: >-
            Typical success response when mappings exist for the specified user
            IDs
          content:
            application/json:
              schema:
                title: migration.exchange success schema
                required:
                - enterprise_id
                - ok
                - team_id
                type: object
                properties:
                  enterprise_id:
                    title: >-
                      The enterprise grid organization ID containing the
                      workspace/team.
                    type: string
                  invalid_user_ids:
                    title: A list of User IDs that cannot be mapped or found
                    type: array
                    items:
                      type: string
                  ok:
                    $ref: '#/components/schemas/defs_ok_true'
                  team_id:
                    $ref: '#/components/schemas/defs_team'
                  user_id_map:
                    title: A mapping of provided user IDs with mapped user IDs
                    type: object
                    additionalProperties: true
                additionalProperties: true
                description: Schema for successful response from migration.exchange method
              example:
                enterprise_id: E1KQTNXE1
                invalid_user_ids:
                - U21ABZZXX
                ok: true
                team_id: T1KR7PE1W
                user_id_map:
                  U06UBSUN5: W06M56XJM
                  U06UBSVB3: W06PUUDLY
                  U06UBSVDX: W06PUUDMW
                  U06UEB62U: W06PTT6GH
                  W06UAZ65Q: W06UAZ65Q
        default:
          description: Typical error response when there are no mappings to provide
          content:
            application/json:
              schema:
                title: migration.exchange error schema
                required:
                - error
                - ok
                type: object
                properties:
                  callstack:
                    type: string
                    description: 'Note: PHP callstack is only visible in dev/qa'
                  error:
                    type: string
                    enum:
                    - not_enterprise_team
                    - too_many_users
                    - not_authed
                    - invalid_auth
                    - account_inactive
                    - token_revoked
                    - no_permission
                    - org_login_required
                    - invalid_arg_name
                    - invalid_array_arg
                    - invalid_charset
                    - invalid_form_data
                    - invalid_post_type
                    - missing_post_type
                    - team_added_to_org
                    - invalid_json
                    - json_not_object
                    - request_timeout
                    - upgrade_required
                    - fatal_error
                  ok:
                    $ref: '#/components/schemas/defs_ok_false'
                additionalProperties: false
                description: Schema for error response from migration.exchange method
              example:
                error: not_enterprise_team
                ok: false
      security:
      - slackAuth:
        - tokens.basic
      summary: Slack Get Migration Exchange
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas: {}
tags:
- name: Exchange
- name: Get
- name: Migrations