Citi Submit Action API

openapi: 3.2.0
info:
  title: ACES ETF OrderApproval Submit Action API
  version: '1.0'
  description: The ACES ETF Order Approval API receives order action requests from Citi ETF Sponsor clients.
  x-ibm-name: aces-order-approval
  contact:
    name: ACES L2 Support Team
    email: funds.l2productionsupport@imceu.eu.ssmb.com
servers:
- url: https://sit.b2b.tts.icgservices.citi.com/tts
  description: SIT Environment URL
- url: https://qa.b2b.tts.icgservices.citi.com/tts
  description: QA Environment URL
- url: https://uat.b2b.tts.icgservices.citi.com/tts
  description: UAT Environment URL
- url: https://tts.sandbox.apib2b.citi.com/tts
  description: CTE Environment URL
security:
- Authorization: []
tags:
- name: submitAction
  description: Operations related to ETF Order Approval processing
paths:
  /etf/api/v1/order/submitAction:
    post:
      tags:
      - submitAction
      description: Posts an action request - Approve, Reject, or Cancel, allowing a PM/CM/D to approve or reject orders on the ACES Dealing Portal.
      operationId: submitAction
      summary: Request action on an order
      parameters:
      - name: Content-Type
        in: header
        description: Supports \"application/json\".
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: The OAuth Token prefixed with "Bearer" and space in between.
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        required: true
        description: This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation
        schema:
          type: string
      requestBody:
        description: Order Submit Action Object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/submitAction'
      responses:
        '200':
          description: OK.  Returns a confirmation of the action submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ackResponse'
        '400':
          description: Bad Request Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nackResponse'
              examples:
                InvalidOrderId:
                  summary: Invalid Order ID
                  value:
                    orderResponse:
                      clientRefId: ABC1234
                      orderId: '100021822'
                      responseTimeStamp: 2025-07-26 10:30:10EST
                      respStatus: Failed
                      respCode: '400'
                      error: Invalid Order ID.
                InvalidAction:
                  summary: Invalid Order ID
                  value:
                    orderResponse:
                      clientRefId: ABC1234
                      orderId: '100021822'
                      responseTimeStamp: 2025-07-26 10:30:10EST
                      respStatus: Failed
                      respCode: '400'
                      error: Invalid action performed for the order.
                InvalidRole:
                  summary: Invalid Role
                  value:
                    orderResponse:
                      clientRefId: ABC1234
                      orderId: '100021822'
                      responseTimeStamp: 2025-07-26 10:30:10EST
                      respStatus: Failed
                      respCode: '400'
                      error: Invalid Role.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nackResponse'
              example:
                orderResponse:
                  clientRefId: ABC1234
                  orderId: '100021822'
                  responseTimeStamp: 2025-07-26 10:30:10EST
                  respStatus: Failed
                  respCode: '500'
                  error: Unable to serve your request at this moment. Please try again later.
components:
  schemas:
    nackResponse:
      title: Order Action NACK Response Object
      type: object
      properties:
        orderResponse:
          type: object
          properties:
            clientRefId:
              title: Client Reference ID
              type: string
              description: Unique Client assigned identifier for each api request and response..
              example: ABC1234
            orderId:
              title: Order ID
              type: string
              description: ACES Dealing Portal Order ID for which action is submitted.
              example: '100021822'
            responseTimeStamp:
              title: Response Timestamp
              type: string
              description: Timestamp of the response in EST (Format:-"yyyy-MM-dd HH:mm:ssEST")..
              example: 2025-07-26 10:30:10EST
            respStatus:
              title: Response Status
              type: string
              description: Status of the request (e.g.,"Failed" for any failures).
              example: Failed
            respCode:
              title: Response Code
              type: string
              description: Error response Code.
              example: '400'
            error:
              type: string
              description: Description of the error encountered.
              example: Invalid Order ID.
    submitAction:
      title: Order Action Request Object
      type: object
      properties:
        orderRequest:
          type: object
          required:
          - clientRefId
          - orderId
          - citiVelocityUserId
          - requestTimestamp
          - role
          - statusUpdate
          - basketType
          properties:
            clientRefId:
              title: Client Reference ID
              type: string
              description: Unique Client assigned identifier for each api request and response.
              example: ABC1234
            orderId:
              title: Order ID
              type: string
              description: ACES Dealing Portal Order Id for which action is being submitted.
              example: '100021822'
            citiVelocityUserId:
              title: Citi Velocity User ID
              type: string
              description: ACES User Id for authentication.
              example: ps90033
            requestTimestamp:
              title: Request Timestamp
              type: string
              description: Timestamp of the request in EST (Format:-"yyyy-MM-dd HH:mm:ssEST").
            role:
              title: User Role
              type: string
              description: Role of the user submitting the action.
              enum:
              - PM
              - CMD
              example: PM
            statusUpdate:
              title: Status Update
              description: The action to be applied to the order (for example "APPROVED", REJECTED", "CANCEL_APPROVED", "CANCEL_REJECTED").
              type: string
              format: date
            basketType:
              title: Basket Type
              type: string
              enum:
              - STANDARD
              - CUSTOM
              description: Specifies the BasketType of the order. Can be applied by PM.
              example: STANDARD
            comments:
              title: Comments
              type: string
              description: Optional comments regarding the action.
              example: Portfolio Manager ok with the order.
    ackResponse:
      title: Order Action ACK Response Object
      type: object
      properties:
        orderResponse:
          type: object
          properties:
            clientRefId:
              title: Client Reference ID
              type: string
              description: Unique Client assigned identifier for each api request and response..
              example: ABC1234
            orderId:
              title: Order ID
              type: string
              description: ACES Dealing Portal Order ID for which action is submitted.
              example: '100021822'
            responseTimeStamp:
              title: Response Timestamp
              type: string
              description: Timestamp of the response in EST (Format:-"yyyy-MM-dd HH:mm:ssEST")..
              example: 2025-07-26 10:30:10EST
            respStatus:
              title: Response Status
              type: string
              description: Status of the request (e.g., "Success" for successfully processed).
              example: Success
            respCode:
              title: Response Code
              type: string
              description: Successful response Code.
              example: '200'
  securitySchemes:
    Authorization:
      description: "Client applications must supply an\n authentication token with every request, and therefore must first\n authenticate before it can proceed. A client can use the OAuth 2 client\n credential grant flow to obtain a time limited access token. To get an\n access token send a HTTP Post request to the token endpoint using basic\n authentication with the client key and secret.<br><br>**Request**<br><br>```POST {baseURL}/tts/api/v1/oauth2/token HTTPS/1.1\n Authorization: Basic base64(key:secret) \n Content-Type:application/x-www-form-urlencoded\n {\n  scope=/api&grant_type=client_credentials\n }```<br><br>\n **Response**<br><br>```\n   {\n     \"token_type\": \"bearer\", \n     \"access_token\": <access token>, \n     \"expires_in\": <seconds until expiry>, \n     \"consented_on\":<timestamp>, \n     \"scope\": \"api\"\n   }```    <br><br>The bearer token is valid for 1800 seconds (30 minutes) after which it will expire. At this point, you would need to re-authenticate.<br><br>\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /tts/api/v1/oauth2/token
          scopes:
            /api: Access to ETF Order API