openapi: 3.2.0
info:
  contact:
    name: Lavanya Appa
    email: LAVANYA.APPA@ADP.COM
  description: The Applicant Onboarding v2 APIs are used to manage the process of transfering the applicant data into HCM systems, including reading the API metadata.
  title: Applicant Onboarding Onboarding API Metadata API
  version: 2.0.1
  x-apievangelist-source: https://api-library-marketplace.adp.com/hcm-offrg-wfn/hcm/applicant-onboarding/v2/applicant-onboarding-swagger_v2-merged.json
  x-apievangelist-product: ADP Workforce Now (hcm-offrg-wfn)
  x-apievangelist-resource-path: hcm/applicant-onboarding/v2/applicant-onboarding
servers:
- url: https://api.adp.com
  description: 'ADP production API gateway (mutual-TLS). Source: https://developers.adp.com/getting-started/key-concepts/access-tokens'
- url: https://api.eu.adp.com
  description: ADP European API gateway
- url: https://uat-api.adp.com
  description: ADP UAT / sandbox gateway
tags:
- name: Onboarding API Metadata
  description: APIs to obtain the applicant onboarding APIs metadata
paths:
  /hcm/v2/applicant.onboard/meta:
    x-adpPathData:
      uriTranslationIndicator: false
      featureCode: applicantOnboardingManagement
      functionCode: onboardingProcessManagement
      serviceCode: integrationManagement
      serviceCategoryCode: hcm
      canonicalName: Applicant Onboarding API Metadata
    get:
      summary: Initiate New Applicant Onboarding Metadata
      x-adpOperationData:
        operationStateCode: active
        grantTypes:
        - authorization_code
        - urn:ietf:params:oauth:grant-type:saml2-bearer
        - urn:ietf:params:oauth:grant-type:jwt-bearer
        - client_credential
        asaFeatureCodes:
        - MobilePSSApplicantOnboard
        - MobileADMApplicantOnboard
        sorRequestTimeoutPolicies:
          cachedTimeout: 3
          notCachedTimeout: 10
        canonicalUri: hcm/integrationManagement/applicantOnboardingManagement/onboardingProcessManagement/applicant.onboard.meta.read
        operationCode: applicant.onboard.meta.read
        operationId: de9a8c8b-fb90-4737-b068-ff96b2cc3283
        performAuthIndicator: true
        roleCodes:
        - practitioner
        - administrator
        scenarios:
        - summary: <p><span>Returns an applicant&#39;s metadata for Canada Template.</span></p><p><span>Important:</span></p><p>1. Whenever there is a change or update to any of the existing Custom template setup at ADP WorkForce Now side, the respective template Code&nbsp;in the API meta response gets updated.</p><p>2. It is recommended to call meta API (/hcm/v2/applicant.onboard/meta) to verify the template Codes before trying to onboard an employee using custom templates.</p>
          headers:
            ADP-Context-ExpressionID: country=CA
          name: 2. Returns an applicant's metadata for CANADA template.
          responses:
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: Returns an API metadata including the list of minimum fields to create an in progress hire and the list of client hire templates
            content:
              application/json:
                externalValue: ./examples/2._Returns_an_applicant's_metadata_for_CANADA_template._Custom_Example_applicant.onboard.meta.read_200_353696.json
          - headers:
              ADP-Acting-Session-Expires: ''
              Cache-Control: ''
              sm_transactionid: ''
              ETag: ''
              ADP-Acting-SessionID: ''
              Content-Type: ''
            code: '200'
            description: Retrieves the template code available for the US client. /hcm/v2/applicant.onboard/meta?$filter=meta/applicantOnboarding/onboardingTemplateCode/code eq '{ItemID}'
            content:
              application/json:
                externalValue: ./examples/2._Returns_an_applicant's_metadata_for_CANADA_template._Custom_Example_applicant.onboard.meta.read_200_353697.json
          description: <p><span>Returns an applicant&#39;s metadata for Canada Template.</span></p><p><span>Important:</span></p><p>1. Whenever there is a change or update to any of the existing Custom template setup at ADP WorkForce Now side, the respective template Code&nbsp;in the API meta response gets updated.</p><p>2. It is recommended to call meta API (/hcm/v2/applicant.onboard/meta) to verify the template Codes before trying to onboard an employee using custom templates.</p>
        - summary: For time product TLM example meta response
          name: 5. TLM Meta response
          responses:
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: Meta response for time product TLM
            content:
              application/json:
                externalValue: ./examples/5._TLM_Meta_response_Custom_Example_applicant.onboard.meta.read_200_619207.json
          description: For time product TLM example meta response
        - summary: <span>Returns an applicant&#39;s metadata for International Client</span>
          headers:
            ADP-Context-ExpressionID: country=INT
          name: 3. Returning an applicant's metadata for International Client
          responses:
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: 'Retrieves the template code available for the US client. /hcm/v2/applicant.onboard/meta?$filter=meta/applicantOnboarding/onboardingTemplateCode/code eq ''{ItemID}''


              In this example country code passed was ''GB'''
            content:
              application/json:
                externalValue: ./examples/3._Returning_an_applicant's_metadata_for_International_Client_Custom_Example_applicant.onboard.meta.read_200_353701.json
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: 'Retrieves the template code available for the International client.

              /hcm/v2/applicant.onboard/meta?$filter=meta/applicantOnboarding/onboardingTemplateCode/code eq ''{templateCode}'' and meta/applicantOnboarding/countryCode eq ''{countryCode}'''
            content:
              application/json:
                externalValue: ./examples/3._Returning_an_applicant's_metadata_for_International_Client_Custom_Example_applicant.onboard.meta.read_200_353700.json
          description: <span>Returns an applicant&#39;s metadata for International Client</span>
          parameters:
            $filter: meta/applicantOnboarding/onboardingTemplateCode/code eq '9360972_1439' and meta/applicantOnboarding/countryCode eq 'GB'
        - summary: If your template has custom fields for personal and employment will get a meta response similar to below, to fetch the custom fields ids and information can use<br>For Personal<br>/hcm/v1/validation-tables/person-custom-fields<br>For employment<br>/hcm/v1/validation-tables/worker-custom-fields<br><br>and to fetch on individual code list use the itemID for the list and send to similar api like<br>for personal<br>/hcm/v1/validation-tables/person-custom-fields/{itemID}<br>for employment<br>hcm/v1/validation-tables/worker-custom-fields/{itemID}
          name: 6. Custom fields template
          responses:
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: Example of a US client with custom fields attached
            content:
              application/json:
                externalValue: ./examples/6._Custom_fields_template_Custom_Example_applicant.onboard.meta.read_200_640857.json
          description: If your template has custom fields for personal and employment will get a meta response similar to below, to fetch the custom fields ids and information can use<br>For Personal<br>/hcm/v1/validation-tables/person-custom-fields<br>For employment<br>/hcm/v1/validation-tables/worker-custom-fields<br><br>and to fetch on individual code list use the itemID for the list and send to similar api like<br>for personal<br>/hcm/v1/validation-tables/person-custom-fields/{itemID}<br>for employment<br>hcm/v1/validation-tables/worker-custom-fields/{itemID}
        - summary: <p><span>Returns an applicant&#39;s metadata for US client.</span></p><p><span>Important:</span></p><p>1. Whenever there is a change or update to any of the existing Custom template setup at ADP WorkForce Now side, the respective template Code&nbsp;in the API meta response gets updated.</p><p>2. It is recommended to call meta API (/hcm/v2/applicant.onboard/meta) to verify the template Codes before trying to onboard an employee using custom templates.</p>
          name: 1. Returning an applicant's metadata for US Client
          responses:
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: 'Retrieves the template code available for the US client.

              /hcm/v2/applicant.onboard/meta?$filter=meta/applicantOnboarding/onboardingTemplateCode/code eq ''{ItemID}'''
            content:
              application/json:
                externalValue: ./examples/1._Returning_an_applicant's_metadata_for_US_Client_Provide_Example_applicant.onboard.meta.read_200_44558.json
          - headers:
              ADP-Acting-Session-Expires: unset
              Cache-Control: unset
              sm_transactionid: unset
              ETag: unset
              ADP-Acting-SessionID: unset
              Content-Type: unset
            code: '200'
            description: Returns an API metadata for US Client
            content:
              application/json:
                externalValue: ./examples/1._Returning_an_applicant's_metadata_for_US_Client_Provide_Example_applicant.onboard.meta.read_200_44555.json
          description: <p><span>Returns an applicant&#39;s metadata for US client.</span></p><p><span>Important:</span></p><p>1. Whenever there is a change or update to any of the existing Custom template setup at ADP WorkForce Now side, the respective template Code&nbsp;in the API meta response gets updated.</p><p>2. It is recommended to call meta API (/hcm/v2/applicant.onboard/meta) to verify the template Codes before trying to onboard an employee using custom templates.</p>
          parameters:
            $filter: meta/applicantOnboarding/onboardingTemplateCode/code eq '{{onboardingTemplateCode}}'
        - summary: ETime Meta response
          name: 4. ETime Meta response
          responses:
          - headers:
              ADP-Acting-Session-Expires: ''
              Cache-Control: ''
              sm_transactionid: ''
              ETag: ''
              ADP-Acting-SessionID: ''
              Content-Type: ''
            code: '200'
            description: Meta response for a client setup in Enhanced Time
            content:
              application/json:
                externalValue: ./examples/4._ETime_Meta_response_Custom_Example_applicant.onboard.meta.read_200_602070.json
          description: ETime Meta response
        visibilityCodes:
        - internal
        - external
        globalViewDevPortalIndicator: true
      responses:
        '200':
          headers:
            ADP-Acting-Session-Expires:
              schema:
                type: string
              description: Specifies the date and time the representational state of the resource is considered stale in 'Act-As' and act 'On-Behalf-Of' scenarios
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
            sm_transactionid:
              schema:
                type: string
              description: 'SiteMinder transaction ID.  Required for requests where conversation was initiated from a service consumer, external to ADP, and that consumer was authenticated by SMS. Example - sm_transactionid: 1aaf14ac-7083-54c0186f-4680c940-82b33ca3'
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
            Cache-Control:
              schema:
                type: string
              description: Specifies directives that must be obeyed by all caching mechanisms along the request/response chain.
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
            ETag:
              schema:
                type: string
              description: Defines the entity tag for use with the If-Match and If-None-Match request headers.
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
            ADP-Acting-SessionID:
              schema:
                type: string
              description: Session ID for the acting session in 'Act-As' and act 'On-Behalf-Of' scenarios
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
            Content-Type:
              schema:
                type: string
              description: 'Content-Type'' '': '' type ''/'' subtype. Describes the media type and subtype of an entity-body.'
              x-adpParameterData:
                visibilityCodes:
                - internal
                - external
              required: false
          description: Returns an API metadata
          content:
            application/json:
              schema:
                $ref: ./schemas/applicant-onboarding-meta-schema_v02.json
        '400':
          $ref: '#/components/responses/400'
        '412':
          $ref: '#/components/responses/412'
        '500':
          $ref: '#/components/responses/500'
        '413':
          $ref: '#/components/responses/413'
        '304':
          $ref: '#/components/responses/304'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '503':
          $ref: '#/components/responses/503'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      description: Returns an API metadata
      operationId: de9a8c8b-fb90-4737-b068-ff96b2cc3283
      parameters:
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-Acting-SessionID
        description: Session ID for the acting session in 'Act-As' and act 'On-Behalf-Of' scenarios
        x-adpParameterData:
          visibilityCodes:
          - internal
          - external
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: SOR
        description: SOR where the call is routed to.  Set up / overwritten by the infrastructure (API PRoxy) based on the user profile settings.
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: Authorization
        description: Provides the client's authorization token to access the resource representation at a URI
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-Consumer-ApplicationID
        description: Identifier of the application sending a request - not intended to be used as a correlation id for messages across systems participating in a collaboration
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: query
        name: $filter
        description: The OData $filter parameter MUST be used to specify the filter criteria. The usage sample is below. Various criteria could be combined using and/or operands and () to set the operand precedence. Please refer "RESTful Web API Design Standard" for more details
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          type: string
        in: header
        name: associateoid
        description: Associate OID of the requestor
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: true
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-On-Behalf-Of-AssociateOID
        description: Associate OID for the associate that is the actor in ' On Behalf Of' as provisioned by the ADP Registry
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          type: string
        in: header
        name: roleCode
        description: 'The role the user is playing during the transaction.  Possible values: employee,manager,practitioner,administrator,supervisor.  The roleCode header should be set by the API consumer otherwise it will be defaulted to the lowest value based on the user profile settings.'
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: true
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-Context-ExpressionID
        description: Geopolitical context, typically country, region, e.g. country=CA;subdivision=Quebec
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: ConsumerAppOID
        description: Identifier for the service consumer application.  This header is required, if the actor (Service Consumer) is an application or the actor is internal to ADP
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-Act-As-OrgOID
        description: Org OID for organization of the associate that is the actor in 'Acting As' as provisioned by the ADP Registry
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          type: string
        in: header
        name: orgoid
        description: Organization OID of the requestor
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: true
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-Act-As-AssociateOID
        description: Associate OID of the associate that is the actor in 'Acting As' as provisioned by the ADP Registry
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: Accept-Language
        description: Accept-Language:language|*;q=qvalue. Specifies the language(s) that are acceptable for the response. The optional qvalue represents a quality level for acceptable languages.
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: ADP-On-Behalf-Of-OrgOID
        description: Org OID for organization of the associate that is the actor in ' On Behalf Of' as provisioned by the ADP Registry
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      - schema:
          default: ''
          type: string
        in: header
        name: SORContext
        description: Context within an SOR that the call should be routed to.  Set up / overwritten by the infrastructure (API PRoxy) based on the user profile settings.
        x-adpParameterData:
          visibilityCodes:
          - internal
        required: false
      tags:
      - Onboarding API Metadata
components:
  responses:
    '429':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '406':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Not Acceptable
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '403':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '405':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '304':
      description: Not Modified
    '400':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '503':
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '412':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
    '413':
      headers:
        Content-Language:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
        Last-Modified:
          schema:
            type: string
          x-adpParameterData:
            visibilityCodes:
            - internal
          required: false
      description: Request Entity Too Large
      content:
        application/json:
          schema:
            $ref: ../../../common/shared/confirm-message-schema_v03.json
x-adpSpecData:
  domain: HCM
  specId: a0d18d20-3d21-482e-b257-7e59c9a33feb
  canonicalSpecId: 1d8a3771-a45c-45d2-9d55-8e59a91e177a
  specStatusCode: publishing
  specTypeCode: REST
  specStateCode: active
  nonStandardIndicator: false
  visibilityCodes:
  - internal
  - external
  filename: applicant-onboarding-swagger_v2-merged.json
  serviceProviderId: WFN
  resourcePath: hcm/applicant-onboarding/v2
  libraryVersion: ''
  testCaseCollection:
    example:
      href: ApplicantOnboarding_WFNCurrentGen.postman_collection.json
    description: Applicant Onboard Postman Collection
  publicationContext:
    products:
    - productId: hcm-offrg-wfn
      productName: workforce now
      marketplaceProductName: ADP Workforce Now®
  specCategoryCode: ''