openapi: 3.0.0
info:
  title: Contacts API                                       # TITLE OF THE DOCUMENT (REQUIRED)
  description: 'The Contacts API provides programmatic access to manage Active Directory (AD) contact records. The ADManager Plus API offers endpoints to create, update, list, and delete contacts using structured requests with support for filtering, sorting, and pagination. Contact entries typically store information about people or external entities without logon permissions, and the API enables them to be maintained efficiently for address lists, mail routing, and directory organization.'
  contact: {}
  version: 2.0.0
servers:
  -
    url: 'http://admanagerplus:8080'                       # PRODUCT URL
    description: 'Product URL'                            # URL DESCRIPTION
tags:
  -
    name: api-for-ad-contacts                                      # TAG NAME SHOULD BE SAME AS DEFINED IN APP.YML TAGS & SAME AS YML FILE NAME (REQUIRED)
    description: 'Contacts Endpoints'                      # DESCRIPTION ABOUT THE TAG NAME
security:
  - authToken: []
paths:
  /api/v2/contacts:
    get:
      tags:
      - api-for-ad-contacts
      summary: List AD Contacts
      description: |
        This endpoint retrieves AD contact objects. You can refine results using filters, sorting, and pagination, and select only the fields you need. It is useful for generating reports, integrating contacts into other systems, or keeping external directories synchronized.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/date_format'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domains'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      responses:
        "200":
          description: Successful response with AD contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_contacts_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: UnAuthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Read contact action, All contacts management actions
          - delegated-roles
          - All Contacts Report
    post:
      tags:
      - api-for-ad-contacts
      summary: Create AD Contacts
      description: This endpoint creates new AD contact objects. You can use default or custom templates to standardize attributes such as organizational details, contact information, and Exchange settings. It is commonly used when adding external entities to address books or bulk-creating contacts.
      parameters:
        - $ref: '#/components/parameters/domain'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_contacts_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_contacts_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Create contact action, All contacts management actions
          - delegated-roles
          - Create Bulk Contacts
    patch:
      tags:
      - api-for-ad-contacts
      summary: Update AD contacts
      description: This endpoint updates existing AD contacts with the specified payload. You can modify personal details, organizational attributes, Exchange settings, and membership. It is typically used for keeping contact records up to date or applying changes across multiple contacts.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_contacts_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_contacts_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Modify contacts action, All contacts management actions
          - delegated-roles
          - Modify Bulk Contact, Bulk Contact Modification
    delete:
      tags:
      - api-for-ad-contacts
      summary: Delete AD contacts
      description: This endpoint deletes AD contacts that match the specified filters. Deletion removes the object from the directory permanently, making it unavailable for address lists or mail distribution. It is often used for cleaning up unused or outdated contacts.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_contacts_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Delete contact action, All contacts management actions
          - delegated-roles
          - Delete Contacts
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authtoken for the API'
      required: true
      example: '41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'The response format that the client accepts.'
      required: false
      example: 'application/json'
    contentType:
      name: Content-Type
      in: header
      schema:
        type: string
      description: 'The format of data sent to the server. This value is passed in the Content-Type header of the API request.'
      required: false
      example: 'application/json'
    xModule:
      name: X-Module
      in: header
      schema:
        type: string
      description: 'The module name to be recorded in the audit logs. If not provided, the default module is recorded as Rest API.'
      required: false
      example: 'External API'
    from:
      in: query
      name: from
      schema:
        type: integer
        minimum: 1
      description: 'The starting index for pagination. Enables pagination through large result sets.'
      required: false
      example: 1
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        minimum: 1
      description: 'The maximum number of contacts records to return per request.'
      required: false
      example: 50
    domains:
      in: query
      name: domains
      schema:
        type: string
      description: >
        A comma-separated list of domains from which to fetch contacts. 
        <br>
        <strong>Example:</strong>  domain1.com,domain2.com
      required: true
      example: domain1.com
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: 'The attributes to be returned in the response.'
      required: false
      example: 'SAM_ACCOUNT_NAME,EMAIL_ADDRESS,MEMBER_OF'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        A SCIM filter query to refine which objects are returned. See <a href="https://www.manageengine.com/au/products/ad-manager/active-directory-api/v2/filters/#overview">Filter section</a> for details.
        <br>
        <strong>eg:</strong> (FIRST_NAME eq John) and (LAST_NAME eq Doe)
      required: false
      example: (FIRST_NAME eq John) and (LAST_NAME eq Doe)
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
        This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a hyphen (-).
        <br>
        <strong>eg:</strong> FIRST_NAME,-LAST_NAME
      required: false
      example: 'FIRST_NAME,-LAST_NAME'
    refresh:
      in: query
      name: refresh
      description: If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.
      required: false
      schema:
        type: boolean
    date_format :
      name: X-Date-Time-Format
      in: header
      description: "The date-time format to be used for parsing date values returned in the response. If not provided, the default ISO format is used (yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX])."
      required: false
      schema:
        type: string
    domain:
      in: query
      name: domain
      description: >
        The AD domain where the requested operation is performed.
        <br>
        <strong>eg:</strong> domain1.com
      required: true
      schema:
        type: string
      example: domain1.com
  schemas:
    bad_request_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000100"
        detail:
          type: string
          description: Detailed error message
          example: "Some columns given in fields parameter are invalid"
        title:
          type: string
          description: Short error message
          example: "Bad Request."
    unauthorized_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000101"
        detail:
          type: string
          description: Detailed error message
          example: "The given Authtoken is invalid."
        title:
          type: string
          description: Short error message
          example: "Unauthorized."
    internal_server_error_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000000"
        detail:
          type: string
          description: Detailed error message
          example: "An internal server error occurred."
        title:
          type: string
          description: Short error message
          example: "Internal Server Error."

    list_contacts_response: 
      type: object
      properties:
        data:
          type: array
          example:
          - DISTINGUISHED_NAME: "CN=APIContact1,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact1"
            FULL_NAME: "APIContact1"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact1"
          - DISTINGUISHED_NAME: "CN=APIContact2,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact2"
            FULL_NAME: "APIContact2"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact2"
          - DISTINGUISHED_NAME: "CN=APIContact3,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact3"
            FULL_NAME: "APIContact3"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact3"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 100
            total_no_of_objects: 3
    contacts_array:
      type: array
      items:
        example:
          - DISTINGUISHED_NAME: "CN=APIContact1,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact1"
            FULL_NAME: "APIContact1"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact1"
          - DISTINGUISHED_NAME: "CN=APIContact2,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact2"
            FULL_NAME: "APIContact2"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact2"
          - DISTINGUISHED_NAME: "CN=APIContact3,OU=Contacts,DC=xcross,DC=com"
            OU_NAME: "Contacts"
            EMAIL_ADDRESS: "-"
            COMMON_NAME: "APIContact3"
            FULL_NAME: "APIContact3"
            LAST_NAME: "-"
            DOMAIN_NAME: "xcross.com"
            FIRST_NAME: "API"
            DISPLAY_NAME: "Contact3"
    meta:
      type: object
      properties:
        start_index:
          type: integer
        limit:
          type: integer
        total_no_of_objects:
          type: integer
    
    create_contacts_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/create_contacts_data'
          example:
            - object:
                Name: "APIContact1"
                Manager(AD): "Manager 1"
                Manager(Microsoft 365): "Manager 1"
                Description: "Computer created via API"
                Email Address: "test@contact.com"
              status:
                status_code: 1
                status_message: "Successfully created the contact."
            - object:
                Full Name: "APIContact2"
              status:
                status_code: 0
                status_message: "Value for managedBy attribute could not be found in AD. Value for the managedBy attribute must be specified in DN format or mail or displayName"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 2
            total_no_of_objects: 2
    create_contacts_data:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/creation_object_data'
        status:
          $ref: '#/components/schemas/status'
    creation_object_data:
      type: object
      properties:
        Name:
          type: string
        Manager(AD):
          type: string
        Description:
          type: string
        Manager(Microsoft 365):
          type: string
        Email Address:
          type: string
    status:
      type: object
      properties:
        status_code:
          type: integer
        status_message:
          type: string
    create_contacts_body:
      type: object
      properties:
        template:
          $ref: '#/components/schemas/creation_template'
          description: >
            The template to be used for creating the contact. If not specified, the default 
          example:
            template_name: "Contact Creation Template"
        data:
          type: array
          items:
            type: object
            properties:
              attributes:
                $ref: '#/components/schemas/api_attributes'
                description: >
                  The attributes of the contact to be created.
          description: >
            The data and attributes used for contact creation.
          example:
            - attributes:
                displayName: "APIContact1"
                name: "APIContact1"
                memberOf: "Test Group3;Test Group4"
                co: "India"
                exchange: {
                    msExchAdminGroup: "/o=Contact/ou=Exchange Administrative Group (FY0IB0HF2LPDLT)",
                    targetAddress: "APIContact1",
                    mailNickname: "APIContact1"
                }
                manager: "Manager 1"
            - attributes:
                displayName: "APIContact2"
                name: "APIContact2"
                description: "API"
                OUName: "OU=Contacts,DC=xcross,DC=com"
                memberOf: "Test Group3;Test Group4"
                manager: "Manager 1"
    creation_template:
      type: object
      properties:
        template_name:
          type: string
          description: >
            The name of the template used to create the contact.
        template_id:
          type: integer
          description: >
            The ID of the template used to create the contact.
    creation_contact_data:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/api_attributes'
          description: >
            Attributes of the contact to be created.
    
    update_contacts_body:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/update_contacts_body_data'
          description: >
            Data and attributes to be used for the contact modification.
          example:
            attributes:
              name: "UpdatedContact1"
              OUName: "OU=Contacts,DC=test,DC=com"
              description: "Updated description for the contact"
              memberOf: "Updated Group1;Updated Group2"
              managedBy: "Updated Manager"
              extensionAttribute1: "Updated Attribute"

    update_contacts_body_data:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/api_attributes'
          description: >
            Attributes of the contacts to be updated.
    api_attributes:
      type: object
      properties:
        givenName:
          type: string
          description: "First name of the contact."
        sn:
          type: string
          description: "Last name of the contact."
        initials:
          type: string
          description: "Initials of the contact."
        description:
          type: string
          description: "Description of the contact."
        cn:
          type: string
          description: "Common Name of the contact."
        name:
          type: string
          description: "Name of the contact."
        displayNamePrintable:
          type: string
          description: "Printable display name of the contact."
        memberOf:
          type: string
          description: "Groups that the contact is a member of."
        mail:
          type: string
          description: "Email address of the contact."
        postOfficeBox:
          type: string
          description: "Post Office Box of the contact."
        l:
          type: string
          description: "City of the contact."
        st:
          type: string
          description: "State or province of the contact."
        postalCode:
          type: string
          description: "Postal code of the contact."
        country:
          type: string
          description: "Country of the contact."
        telephoneNumber:
          type: string
          description: "Telephone number of the contact."
        homePhone:
          type: string
          description: "Home phone number of the contact."
        pager:
          type: string
          description: "Pager number of the contact."
        mobile:
          type: string
          description: "Mobile number of the contact."
        facsimileTelephoneNumber:
          type: string
          description: "Facsimile (fax) number of the contact."
        ipPhone:
          type: string
          description: "IP phone number of the contact."
        wWWHomePage:
          type: string
          description: "Web page of the contact."
        title:
          type: string
          description: "Title of the contact."
        department:
          type: string
          description: "Department of the contact."
        company:
          type: string
          description: "Company of the contact."
        physicalDeliveryOfficeName:
          type: string
          description: "Office name of the contact."
        manager:
          type: string
          description: "Manager of the contact."
        info:
          type: string
          description: "Notes about the contact."
        streetAddress:
          type: string
          description: "Street address of the contact."
        c:
          type: string
          description: "Two-letter country code of the contact."
        exchange: 
          type: object
          description: "Exchange attributes of the contact."
          properties:
            msExchAdminGroup:
              type: string
              description: "The administrative group associated with Exchange."
            mailNickname:
              type: string
              description: "Email alias of the contact."
            authOrig:
              type: string
              description: "List of senders who can send messages to the contact"
            unauthOrig:
              type: string
              description: "List of senders who cannot send messages to the contact."
            proxyAddresses:
              type: string
              description: "Proxy addresses of the contact."
            targetAddress:
              type: string
              description: "The target address of the contact."

    update_contacts_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/update_contacts_data'
          description: >
            Data and attributes to be used for the contact modification.
          example:
            - object:
                Distinguished Name: "CN=UpdatedContact1,OU=Contacts,DC=test,DC=com"
                Description: "Updated description for the contact"
                Member of: "Updated Group1;Updated Group2"
              status:
                status_code: 1
                status_message: "Successfully updated the contact."
            - object:
                Distinguished Name: "CN=UpdatedContact2,OU=Contacts,DC=test,DC=com"
                Description: "Updated description for the Contacts"
              status:
                status_code: 0
                status_message: "Value for managedBy attribute could not be found in AD. Value for the managedBy attribute must be specified in DN format or mail or displayName"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 2
            total_no_of_objects: 20
    update_contacts_data:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/modification_object_data'
        status:
          $ref: '#/components/schemas/status'
    modification_object_data:
      type: object
      properties:
        Distinguished Name:
          type: string
        Description:
          type: string
        Member of:
          type: string
    
    delete_contacts_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/delete_contacts_data'
          example:
            - object:
                Object GUID: "{C7029F98-E9D8-49B1-B7B4-B7744A730E90}"
                Common Name: "APIContact1"
                Full Name: "APIContact1"
                Distinguished Name: "CN=APIContact1,OU=Contacts,DC=xcross,DC=com"
                Email Address: "-"
                Domain Name: "xcross.com"
              status:
                status_code: 1
                status_message: "Successfully deleted the contact."
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 1
            total_no_of_objects: 10
    delete_contacts_data:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/delete_object_data'
        status:
          $ref: '#/components/schemas/status'
    delete_object_data:
      type: object
      properties:
        Common Name:
          type: string
        Full Name:
          type: string
        Distinguished Name:
          type: string
        Email Address:
          type: string
        Domain Name:
          type: string
        Object GUID:
          type: string
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authorization
