openapi: 3.1.0
info:
  title: Tango MAC Request Outbound API
  version: "1.1"
  description: |
    Async **delta** REST API: client retrieves MAC requests created or
    updated in Tango since the last integration run. Two-call pattern with
    gu_id and pagination (5000/page). Updates to `tango_request_id` do NOT
    trigger export.
  x-direction: outbound
  x-source: Tango
  x-destination: Client System
servers:
  - url: https://api.tangoanalytics.com
    description: Production
  - url: https://testapi.tangoanalytics.com
    description: Test (SIT/UAT)
tags: [{name: MAC Requests (Delta)}, {name: Status}]
paths:
  /v1/spacemgmt/delta/moverequests:
    get:
      summary: Initiate delta MAC request export (async)
      operationId: getMacRequestsDelta
      tags: [MAC Requests (Delta)]
      parameters:
        - $ref: "#/components/parameters/XClient"
        - $ref: "#/components/parameters/XApiKey"
      responses:
        "200":
          description: Async ack.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptedResponse"
  /v1/batch/status:
    get:
      summary: Retrieve paginated MAC request records by gu_id
      operationId: getMacRequestsByGuId
      tags: [Status]
      parameters:
        - $ref: "#/components/parameters/XClient"
        - $ref: "#/components/parameters/XApiKey"
        - in: query
          name: gu_id
          required: true
          schema: { type: string, format: uuid }
        - in: query
          name: page_no
          required: false
          schema: { type: integer, minimum: 1 }
      responses:
        "200":
          description: Paginated records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MacRequestPage"
components:
  securitySchemes:
    xClientHeader: { type: apiKey, in: header, name: x-client }
    xApiKeyHeader: { type: apiKey, in: header, name: x-api-key }
  parameters:
    XClient: { name: x-client, in: header, required: true, schema: { type: string } }
    XApiKey: { name: x-api-key, in: header, required: true, schema: { type: string } }
  schemas:
    AcceptedResponse:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [OK, Error] }
        status_message: { type: string }
        gu_id: { type: string, format: uuid }
    MacRequestPage:
      type: object
      required: [status, records]
      properties:
        status: { type: string, enum: [PROCESSING, COMPLETED, ERROR] }
        total_records: { type: integer }
        total_pages: { type: integer }
        page_size: { type: integer, default: 5000 }
        page_no: { type: integer }
        records:
          type: array
          items:
            $ref: "#/components/schemas/MacRequestRecord"
    MacRequestRecord:
      type: object
      properties:
        request_type: { type: string, description: "Lookup. e.g., NEW_HIRE." }
        tango_request_id: { type: number }
        request_number: { type: string, description: 'Client Label "MAC Number".' }
        ext_request_number: { type: string, description: "Client Integration ID." }
        requested_by: { type: string, description: "Employee number of the creator." }
        requested_date: { type: string, description: "DATE; sample shows `01-FEB-21` (DD-MON-YY)." }
        requested_for: { type: string, description: "Employee number of the subject person." }
        from_property: { type: string }
        from_building: { type: string }
        from_floor: { type: string }
        from_space: { type: string }
        from_area: { type: string }
        to_property: { type: string }
        to_building: { type: string }
        to_floor: { type: string }
        to_space: { type: string }
        to_area: { type: string }
        from_locker: { type: string }
        to_locker: { type: string }
        first_name: { type: string, description: "First name of the requested-for person." }
        last_name: { type: string, description: "Last name of the requested-for person." }
        effective_date: { type: string, description: "DATE." }
        justification: { type: string }
        notes: { type: string }
        mac_group: { type: string }
        status:
          type: string
          description: "Request Status. Lookup."
        update_only:
          type: string
          description: "Field present in mapping table with no type/sample. Confirm semantic."
        last_update_date: { type: string, description: "TIMESTAMP. Sample shows ISO 8601 `2025-07-29T09:57:48`." }
        last_updated_by: { type: string }
        c_ext_attr1:  { type: string }
        c_ext_attr2:  { type: string }
        c_ext_attr3:  { type: string }
        c_ext_attr4:  { type: string }
        c_ext_attr5:  { type: string }
        c_ext_attr6:  { type: string }
        c_ext_attr7:  { type: string }
        c_ext_attr8:  { type: string }
        c_ext_attr9:  { type: string }
        c_ext_attr10: { type: string }
        c_ext_lov1: { type: string }
        c_ext_lov2: { type: string }
        c_ext_lov3: { type: string }
        c_ext_lov4: { type: string }
        c_ext_lov5: { type: string }
        n_ext_attr1: { type: number }
        n_ext_attr2: { type: number }
        n_ext_attr3: { type: number }
        n_ext_attr4: { type: number }
        n_ext_attr5: { type: number }
        d_ext_attr1: { type: string, description: "DATE." }
        d_ext_attr2: { type: string, description: "DATE." }
        d_ext_attr3: { type: string, description: "DATE." }
        d_ext_attr4: { type: string, description: "DATE." }
        d_ext_attr5: { type: string, description: "DATE." }
security:
  - xClientHeader: []
    xApiKeyHeader: []