Contingent Worker Lookup API

Overview

Use the Contingent Worker (CW) Search API to query for data about CWs who have been confirmed in the CCW system. Search criteria such as candidate first/last names, status, start/end dates, and more, can be requested via the CW Search API. Any CW data matching the specific search criteria is returned.

The base URL to access the CW Search API is: https://<instance>/api/contingent_workers

Refer to the CCW API Overview to learn how to authenticate and submit POST requests to CCW APIs. Requests should include the following elements:

Request Headers

Request headers are required for authentication purposes. See Request Headers section of CCW's API Overview documentation for details.

Request Body

Meta and Data objects both must be passed in the API request body:

Example Request

POST /api/contingent_workers
HOST: <CCW FQDN>
Authorization: Bearer <token>
Accept: "application/json"
Correlation-Id: Z098Jth56Nkio343YY1vXt

{
    "meta":{
        "limit":"number",
        "offset":"number"
    }
    "data":{
        "id":"number",
        "cw_number":"string",
        "first_name":"string",
        "last_name":"string",
        "hiring_manager_email":"string",
        "status":"string",
        "organization_name":"string",
        "cost_center_name":"string",
        "department_name":"string",
        "service_method_name":"string",
    }
}

API Response 

CW(s) matching all search parameters sent in the API request body are returned. The following table defines all parameters that may be included with CWs in the response to a successful API request:

Example Responses

Following are example responses:

• No CW matched the search criteria
  • HTTP Response: 200
  • Response Body: empty payload representing no content matching search criteria
• One or more CWs matched the search criteria (number of CW's matching the criteria is less than the limit, set to 50)
  • HTTP Response: 200
  • Response includes CWs who match the criteria used, limit is not met
• One or more CWs matched the search criteria (number of CW's matching the criteria is more than the limit, set to 50)
  • HTTP Response: 200
  • Response includes CWs who match the criteria used, meeting the limit
  • If an offset was provided, then the lookup API returns results per offset position and returned results are less than or equal to the limit (this is applied until there are no records to return)

Notes:

• total_count: overall number of CWs that matched the search criteria in the API request
• has_more: true or false, indicating if there are more CWs that match the search criteria, in addition to those included in the response

{
    "data": [
        {
            "current_contract": {
                "cost_center_code": "10001",
                "cost_center_name": "10001",
                "department_code": "1",
                "department_name": "",
                "end_date": "2021-12-31T05:00:00Z",
                "gl_code": "RRGelextn1",
                "gl_name": "RRGel1",
                "hiring_manager_email": "avvalidation1@coupa.com",
                "hiring_manager_first_name": "avvalidation",
                "hiring_manager_last_name": "1",
                "hiring_manager_user_name": "avvalidation1@coupa.com",
                "labor_class_code": "1",
                "labor_class_name": "Labor class1",
                "matrix_code": "Matrix Number1",
                "matrix_name": null,
                "organization_code": "1001",
                "organization_name": "1001",
                "profit_center_code": "1006",
                "profit_center_name": "1006",
                "program_code": "",
                "program_name": "RRRPrg2",
                "project_code": "",
                "project_name": "RRRPrj2",
                "service_method_code": "",
                "service_method_name": "",
                "site_location_code": "",
                "site_location_name": "",
                "start_date": "2021-01-02T05:00:00Z",
                "type_of_service_code": "",
                "type_of_service_name": "IT",
                "supplier": {
                    "id": 912065,
                    "name": "MCOA",
                    "number": null,
                    "contact": {
                        "first_name": "McOa",
                        "last_name": "Supplier",
                        "email_address": "mcoasupplier1@coupa.com"
                    }
                }
            },
            "customer_tracking_number": "6868888",
            "cw_number": "COA-CW-0000060",
            "email": "Keshav@hcmondemand.net",
            "end_date": "2021-12-31T05:00:00Z",
            "first_name": "Keshav",
            "id": 221338,
            "active": true,
            "last_name": "V",
            "start_date": "2021-01-02T05:00:00Z",
            "status": "extension-cancelled"
        }
    ],
    "meta": {
        "total_count": 1,
        "has_more": false
    }
}

 Following is an example of a response where no CWs met the lookup criteria:

{   
  "meta": {     
    "total_count": 0,     
    "has_more": false   
  },   
  "data":[] 
}

Valid CW Statuses

Following are the valid CW status values that may be passed in a request to the CW Lookup API:

Error Codes

When an API request fails, the response will include one of the following error codes: