SAP Emarsys Administrator API

openapi: 3.2.0
info:
  title: Emarsys Core API - Accounts endpoint batch Administrator API
  description: In this batch you may find endpoints related to accounts.
  version: v2
servers:
- url: https://api.emarsys.net/api
tags:
- name: Administrator
paths:
  v2/administrator:
    post:
      summary: Create an Administrator Account
      description: 'Creates a new administrator account.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: createAdministratorAccount
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      id:
                        type: integer
                        description: The identifier of the administrator.
                      username:
                        type: string
                        description: The user name of the administrator.
                      email:
                        type: string
                        description: The password of the administrator.
                      first_name:
                        type: string
                        description: The first name of the administrator.
                      last_name:
                        type: string
                        description: The last name of the administrator.
                      interface_language:
                        type: string
                        description: The ISO code of the current language used in the Emarsys application.
                      default_upages_lang:
                        type: string
                        description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                      access_level:
                        type: integer
                        description: The identifier of the administrator role. See [List Access Levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                      position:
                        type: string
                        description: The role or position of the administrator.
                      title:
                        type: string
                        description: The title of the administrator.
                      tz:
                        type: string
                        description: The time zone where the administrator is located.
                      mobile_phone:
                        type: string
                        description: The phone number of the administrator.
                      pwd_update_interval:
                        type: integer
                        description: The password expiration date in days.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: 'The username of the administrator.


                    **Tip:** Use actual names for easier maintenance.'
                password:
                  type: string
                  description: 'The password of the administrator.


                    **Requirements**

                    - 10 or more characters

                    - Must contain uppercase and lowercase letters as well as numbers'
                pwd_update_interval:
                  type: integer
                  description: The password expiration date in days.
                email:
                  type: string
                  description: The email address of the administrator.
                  format: email
                access_level:
                  type: integer
                  description: The identifier of the administrator role. See [List access levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                interface_language:
                  type: string
                  description: The ISO code of the current language used in the Emarsys application. See [Get user interface languages](/reference/openapi.json/paths/~1v2~1administrator~1getinterfacelanguages/get) for details.
                  pattern: ^[a-z]{2}
                  minLength: 2
                  maxLength: 2
                default_upages_lang:
                  type: string
                  description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                first_name:
                  type: string
                  description: The first name of the administrator.
                last_name:
                  type: string
                  description: The last name of the administrator.
                mobile_phone:
                  type: string
                  description: The phone number of the administrator.
                position:
                  type: string
                  description: The role or position of the administrator.
                title:
                  type: string
                  description: The title of the administrator.
                tz:
                  type: string
                  description: The time zone where the administrator is located.
                last_verification_action_date:
                  type: string
                  description: 'For internal use only.


                    **Note:** Dates must be defined in CET.'
                last_invitation_action_date:
                  type: string
                  description: 'For internal use only.


                    **Note:** Dates must be defined in CET.'
                actual_login:
                  type: string
                  description: 'The date of the last login.


                    **Note:** Dates must be defined in CET.'
                disabled:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: 'The status of the account.

                    0: Locked

                    1: Unlocked'
                superadmin:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: 'The access level of the administrator.

                    0: Standard

                    1: Superadmin


                    **Note:** Superadmins can create, modify, and configure administrators for the account.'
                start_page:
                  type: string
                  description: The page to redirect the administrator after login.
                  format: uri
              required:
              - username
              - password
              - access_level
              - interface_language
              x-examples:
              - username: black_panther
                password: Black891+Panther
                pwd_update_interval: 30
                email: black.panther@emarsys.com
                access_level: 1
                interface_language: en
                default_upages_lang: en
                first_name: Black
                last_name: Panther
                mobile_phone: 36-304445555
                position: superhero
                last_verification_action_date: '2015-05-14 11:24:09'
                actual_login: '2015-06-10 09:45:54'
                disabled: 0
                superadmin: 0
      tags:
      - Administrator
    get:
      summary: List Administrator Accounts
      description: 'Returns a list of administrator users of the customer''s account.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: listAdministratorAccounts
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  replyCode:
                    type: integer
                  replyText:
                    type: string
                  data:
                    type: array
                    description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The identifier of the administrator.
                        username:
                          type: string
                          description: The user name of the administrator.
                        email:
                          type: string
                          description: The password of the administrator.
                        first_name:
                          type: string
                          description: The first name of the administrator.
                        last_name:
                          type: string
                          description: The last name of the administrator.
                        interface_language:
                          type: string
                          description: The ISO code of the current language used in the Emarsys application.
                        default_upages_lang:
                          type: string
                          description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                        access_level:
                          type: integer
                          description: The identifier of the administrator role. See [List Access Levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                        position:
                          type: string
                          description: The role or position of the administrator.
                        title:
                          type: string
                          description: The title of the administrator.
                        tz:
                          type: string
                          description: The time zone where the administrator is located.
                        mobile_phone:
                          type: string
                          description: The phone number of the administrator.
                        pwd_update_interval:
                          type: integer
                          description: The password expiration date in days.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Administrator
  /v2/administrator/{administratorId}:
    get:
      summary: Get Administrator Details
      description: 'Returns the details of an admininstrator user of the customer''s account.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: Get Administrator Details
      parameters:
      - name: administratorId
        in: path
        description: The identifier of the administrator.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      id:
                        type: integer
                        description: The identifier of the administrator.
                      username:
                        type: string
                        description: The user name of the administrator.
                      email:
                        type: string
                        description: The password of the administrator.
                      first_name:
                        type: string
                        description: The first name of the administrator.
                      last_name:
                        type: string
                        description: The last name of the administrator.
                      interface_language:
                        type: string
                        description: The ISO code of the current language used in the Emarsys application.
                      default_upages_lang:
                        type: string
                        description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                      access_level:
                        type: integer
                        description: The identifier of the administrator role. See [List Access Levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                      position:
                        type: string
                        description: The role or position of the administrator.
                      title:
                        type: string
                        description: The title of the administrator.
                      tz:
                        type: string
                        description: The time zone where the administrator is located.
                      mobile_phone:
                        type: string
                        description: The phone number of the administrator.
                      pwd_update_interval:
                        type: integer
                        description: The password expiration date in days.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Administrator
  /v2/administrator/{administratorId}/patch:
    post:
      summary: Update an Administrator Account
      description: 'Modifies the properties of an administrator account.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: updateAdministratorAccount
      parameters:
      - name: administratorId
        in: path
        description: The identifier of the adminstrator.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      id:
                        type: integer
                        description: The identifier of the administrator.
                      username:
                        type: string
                        description: The user name of the administrator.
                      email:
                        type: string
                        description: The password of the administrator.
                      first_name:
                        type: string
                        description: The first name of the administrator.
                      last_name:
                        type: string
                        description: The last name of the administrator.
                      interface_language:
                        type: string
                        description: The ISO code of the current language used in the Emarsys application.
                      default_upages_lang:
                        type: string
                        description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                      access_level:
                        type: integer
                        description: The identifier of the administrator role. See [List Access Levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                      position:
                        type: string
                        description: The role or position of the administrator.
                      title:
                        type: string
                        description: The title of the administrator.
                      tz:
                        type: string
                        description: The time zone where the administrator is located.
                      mobile_phone:
                        type: string
                        description: The phone number of the administrator.
                      pwd_update_interval:
                        type: integer
                        description: The password expiration date in days.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: 'The user name of the administrator.


                    **Tip:** Use actual names for easier maintenance.'
                password:
                  type: string
                  description: 'The password of the administrator.


                    **Requirements**

                    - 10 or more characters

                    - Must contain uppercase and lowercase letters as well as numbers'
                pwd_update_interval:
                  type: integer
                  description: The password expiration date in days.
                email:
                  type: string
                  description: The email address of the administrator.
                  format: email
                access_level:
                  type: integer
                  description: The identifier of the administrator role. See [List access levels](/reference/openapi.json/paths/~1v2~1administrator~1getaccesslevels/get) for details.
                interface_language:
                  type: string
                  description: The ISO code of the current language used in the Emarsys application. See  [Get user interface languages](/reference/openapi.json/paths/~1v2~1administrator~1getinterfacelanguages/get)  for details.
                  pattern: ^[a-z]{2}
                  minLength: 2
                  maxLength: 2
                default_upages_lang:
                  type: string
                  description: The default language of the www.emarsys.net/u/… links of the launched email campaigns.
                first_name:
                  type: string
                  description: The first name of the administrator.
                last_name:
                  type: string
                  description: The last name of the administrator.
                mobile_phone:
                  type: string
                  description: The phone number of the administrator.
                position:
                  type: string
                  description: The role or position of the administrator.
                title:
                  type: string
                  description: The title of the administrator.
                tz:
                  type: string
                  description: The time zone where the administrator is located.
                last_invitation_action_date:
                  type: string
                  description: 'For internal use only.


                    **Note:** Dates must be defined in CET.'
                start_page:
                  type: string
                  description: The page to redirect the administrator after login.
                  format: uri
              x-examples:
              - administratorId: '111111111'
                username: b_panther
      tags:
      - Administrator
  /v2/administrator/getaccesslevels:
    get:
      summary: List Access Levels
      description: 'Returns the list of available access levels for the customer''s account.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: listAccessLevels
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The requested data.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The identifier of the role.
                        name:
                          type: string
                          description: The name of the role.
                        type:
                          type: string
                          enum:
                          - custom
                          - default
                          description: The type of the role.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Administrator
  /v2/administrator/{administratorId}/session:
    post:
      summary: Create a Session for an Administrator Account
      description: 'Creates a session for administrators for logging in users from outside the Emarsys application, such as implementing Single Sign-On (SSO).


        **Note:** This feature is in the pilot phase and currently available for a limited number of clients only. If you are interested in participating, contact Emarsys support.


        **Important:** This feature is in the pilot phase and currently available for a limited number of clients only. If you are interested in participating, contact Emarsys support.'
      operationId: createSessionForAdministratorAccount
      parameters:
      - name: administratorId
        in: path
        description: 'The identifier of the administrator.


          **Note:** Get available administrators at the [List Administrator Accounts](/reference/openapi.json/paths/~1v2~1administrator/get) endpoint.'
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      url:
                        type: string
                        description: The session URL.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '412':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                target:
                  type: string
                  enum:
                  - email_campaigns/list
                  - email_campaigns/edit
                  - email_analysis/list
                  - email_analysis/details
                  - contact_lists/details
                  - administrators/profile
                  description: 'Controls the page that the administrator first sees in the Emarsys application.


                    Define the following parameters in the `target_params` property.


                    | Value | Possible Parameters |

                    | --- | --- |

                    | email_campaigns/list | - |

                    | email_campaigns/edit | `campaign_id` |

                    | email_analysis/list | - |

                    | email_analysis/details | `campaign_id`, `launch_id` |

                    | contact_lists/details | `contact_list_id` |

                    | administrators/profile | `admin_id` |

                    '
                target_params:
                  type: object
                  properties:
                    contact_list_id:
                      type: string
                      description: The identifier of the contact list.
                    campaign_id:
                      type: string
                      description: The identifier of the email campaign.
                    launch_id:
                      type: string
                      description: The identifier of the email campaign launch.
                    admin_id:
                      type: string
                      description: The identifier of the administrator.
              required:
              - target
              - target_params
              x-examples:
              - target: contact_lists/details
                target_params:
                  contact_list_id: '577064194'
      tags:
      - Administrator
  /v2/administrator/getinterfacelanguages:
    get:
      summary: Get User Interface Languages
      description: 'Returns the list of available user interface languages of the Emarsys application.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: getUserInterfaceLanguages
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The list of supported two-latter language codes.
                    uniqueItems: true
                    items:
                      type: string
                      pattern: ^[a-z]{2}
                      minLength: 2
                      maxLength: 2
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Administrator
  /v2/administrator/getstartpages:
    get:
      summary: List Administrator Start Pages
      description: 'Lists the start pages where administrators are redirected to on login.


        **Important:** Access to administrative endpoints is restricted. If you need access, contact Emarsys support.'
      operationId: listAdministratorStartPages
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The list of start pages.
                    items:
                      type: string
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Administrator
components:
  schemas:
    default-response:
      type: object
      title: Default Response
      description: 'See the following documents for details on the error codes:


        - [HTTP 200 errors](docs/response-codes/http-200-responses.md)

        - [HTTP 400 errors](docs/response-codes/http-400-errors.md)

        - [HTTP 401-429 errors](docs/response-codes/http-401-429-errors.md)

        - [HTTP 500 errors](docs/response-codes/http-500-errors.md)'
      properties:
        replyCode:
          type: integer
          description: The Emarsys response code. Successful requests return *0*; otherwise, see [errors](docs/response-codes/http-400-errors.md).
          default: 0
        replyText:
          type: string
          description: Additional information on the status of the request.
        data:
          description: Contains the request

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-administrator-api-openapi.yml