openapi: 3.0.3
info:
  title: Engagedly Activities Locations API
  description: 'REST API for the Engagedly people strategy execution platform. Provides endpoints for managing users, departments, locations, job titles, business units, permissions, user attributes, and employee activities such as praises and recognition. Supports performance review workflows, goal management, and organizational data integration using header-based authentication with ClientKey and SecretKey.

    '
  version: beta
  contact:
    url: https://engagedly.com
  license:
    name: Proprietary
servers:
- url: https://api.engagedly.com/beta
  description: Production API server
security:
- clientKeyAuth: []
  secretKeyAuth: []
tags:
- name: Locations
  description: Manage office locations and addresses
paths:
  /locations:
    get:
      operationId: listLocations
      summary: List all locations
      description: Returns a paginated list of all office locations in the organization.
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/sizeParam'
      responses:
        '200':
          description: Paginated list of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLocation
      summary: Create a new location
      description: Creates a new office location in the organization.
      tags:
      - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationRequest'
      responses:
        '201':
          description: Location created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSingleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations/{id}:
    get:
      operationId: getLocation
      summary: Get a single location
      description: Returns details for a single office location.
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      responses:
        '200':
          description: Location details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateLocation
      summary: Update an existing location
      description: Updates details of an existing office location.
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationRequest'
      responses:
        '200':
          description: Location updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteLocation
      summary: Delete a location
      description: Permanently deletes the specified office location.
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      responses:
        '204':
          description: Location deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing ClientKey/SecretKey
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found — resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    LocationListResponse:
      type: object
      properties:
        success:
          type: boolean
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Location'
    Location:
      type: object
      properties:
        id:
          type: string
          example: '1'
        name:
          type: string
          example: Head Office
        address_line1:
          type: string
        address_line2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postal_code:
          type: string
    LocationRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        address_line1:
          type: string
        address_line2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postal_code:
          type: string
    LocationSingleResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Location'
    ErrorResponse:
      type: object
      properties:
        error_type:
          type: string
          enum:
          - api_connection_error
          - authentication_error
          - invalid_request_error
          - validation_error
          example: validation_error
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          example: name
        message:
          type: string
          example: Mandatory attribute missing
        code:
          type: string
          example: missing_field
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        size:
          type: integer
          example: 25
        has_more:
          type: boolean
          example: false
        total_records:
          type: integer
          example: 42
  parameters:
    pageParam:
      name: page
      in: query
      description: Page number (starts at 1)
      schema:
        type: integer
        minimum: 1
        default: 1
    idPathParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource
      schema:
        type: string
    sizeParam:
      name: size
      in: query
      description: Number of records per page (maximum 50)
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 25
  securitySchemes:
    clientKeyAuth:
      type: apiKey
      in: header
      name: ClientKey
      description: Client key obtained from the Engagedly portal under Integrations > Engagedly API
    secretKeyAuth:
      type: apiKey
      in: header
      name: SecretKey
      description: Secret key obtained from the Engagedly portal. Shown only once upon generation.