Skip to main content



Coupa Success Portal

Contingent Worker Lookup API


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:


The Metadata section defines the number of results returned, to ensure faster performance. Includes:

  • Limit: Defines the maximum number of results, between 1 and 50, to be returned in a single API request (i.e., the number of results on a page)
    • Defaults to 50 results if the value for Limit is empty or greater than 50
    • Returns an error if the value for Limit is less than 1
  • Offset: Defines the record at which the request should start; for example, limit=30, offset=51 returns the next 30 records starting with record 51.
    • Defaults to 0 if the value for Offset is empty
    • Returns an error if the value for Offset is less than 0


One or more specific search parameters to be requested (at least one non-empty parameter must be sent).

The following table defines all Data parameters that can be passed within the CW Lookup API request body:

Attribute Data type Required? Unique? Values Description
limit number No No 1-50 Number of records to be returned per API call
offset number No No any Specific record number at which results should start
id number No Yes any Unique id of the worker in CCW
cw_number string(100) No Yes any

System-generated number displayed within CCW for the contingent worker

first_name string(100) No No any CW first name
last_name string(100) No No any CW last name
status string(50) No No One of CCW's valid statuses See Valid CW Statuses table below.
start_date date No No any CW's start date, formatted as YYYY-MM-DD (ISO 8601 standard formatting)
end_date date No No any CW's end date, formatted as YYYY-MM-DD
customer_tracking_number_1 string(400) No No any ID assigned to the CW by the customer
hiring_manager_email string(400)   No any Email address of the CW's hiring manager
email string(400) No Yes any The CW's email address
active boolean No No 0,1 Flag which indicates whether this is an active or inactive CW
type_of_service_name string(40) No No any Type of Service Name
type_of_service_code string(1000) No No any Type of Service Code
organization_name string(40) No No any Organization Name
organization_code string(1000) No No any Organization Code
cost_center_name string(40) No No any Cost Center Name
cost_center_code string(1000) No No any Cost Center Code
depatment_name string(40) No No any Department Name
depatment_code string(1000) No No any Department Code
service_method_name string(40) No No any Service Method Name
service_method_code string(1000) No No any Service Method Code
labor_class_name string(40) No No any Labor Class Name
labor_class_code string(1000) No No any Labor Class Code
gl_name string(40) No No any GL Name
gl_code string(1000) No No any GL Code
program_name string(40) No No any Program Name
program_code string(1000) No No any Program Code
project_name string(40) No No any Project Name
project_code string(1000) No No any Project Code
profit_center_name string(40) No No any Profit Center Name
profit_center_code string(1000) No No any Profit Center Code
matrix_name string(40) No No any Matrix Name
matrix_code string(1000) No No any Matrix Code
site_location_name string(40) No No any Site Location Name
site_location_code string(1000) No No any Site Location Code

Example Request

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


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:

Attribute Request body object Data type Description
total_count meta number Number of records that matched the lookup criteria
has_more meta Boolean True or False - to indicate if there are more candidates that meet the lookup criteria
cost_center_code data string(1000) Cost Center Code
cost_center_name data string(40) Cost Center Name
department_code data string(1000) Department Code
department_name data string(40)

Department Name

end_date data date Contract end date, formatted as YYYY-MM-DDT24HHMMSSZ
gl_code data string(1000) General Ledger Code
gl_name data string(40) General Ledger Name
hiring_manager_email data string(100) Hiring manager's email address
hiring_manager_first_name data string(100) Hiring manager first name
hiring_manager_last_name data string(100) Hiring manager last name
hiring_manager_user_name data string(512) Hiring manager user name
labor_class_code data string(1000) Labor Class Code
labor_class_name data string(40) Labor Class Name
matrix_code data string(1000) Matrix Code
matrix_name data string(40) Matrix Name
organization_code data string(1000) Organization Code
organization_name data string(40) Organization Name
profit_center_code data string(1000) Profit Center Code
profit_center_name data string(40) Profit Center Name 
program_code data string(1000) Program Code
program_name data string(40) Program Name
project_code data string(1000) Project Code
project_name data string(40) Project Name
service_method_code data string(1000) Service Method Code
service_method_name data string(40) Service Method Name
site_location_code data string(1000) Site Location Code
site_location_name data string(40) Site Location Name
start_date data date Contract start date, formatted as YYYY-MM-DDT24HHMMSSZ
type_of_service_code data string(1000) Type of Service Code
type_of_service_name data string(40) Type of Service Name
id data.supplier number Unique ID assigned to supplier in CCW
name data.supplier string(400) Supplier name
number data.supplier string(400) Unique number assigned to supplier in CCW
first_name string(100) Supplier contact first name
last_name string(100) Supplier contact last name
email string(400) Supplier contact email
customer_tracking_number data string(400) Custom field
cw_number data string(100) CW number assigned to the worker
email data string(400) CW email address
end_date data date Contract end date, formatted as YYYY-MM-DDT24HHMMSSZ
first_name data string(100) Worker's first name
id data number Unique id assigned to worker in CCW
active data boolean Indicates if this is an Active worker
last_name data string(100) Worker's last name
start_date data date Contract start date, formatted as YYYY-MM-DDT24HHMMSSZ
status data string(50) See Valid CW Statuses table below

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)


  • 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": "",
                "hiring_manager_first_name": "avvalidation",
                "hiring_manager_last_name": "1",
                "hiring_manager_user_name": "",
                "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": ""
            "customer_tracking_number": "6868888",
            "cw_number": "COA-CW-0000060",
            "email": "",
            "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   

Valid CW Statuses

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

ID Status name Status code
1 Onboarding Complete onboarding-complete
2 New Release new-release
3 Release Complete release-complete
4 Release Canceled release-canceled
5 New Extension new-extension
6 Extension Complete extension-complete
7 Extension Canceled extension-canceled
8 New Rate Change new-rate-change
9 Rate Change Complete rate-change-complete
10 Rate Change Canceled rate-change-canceled

Error Codes

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

HTTP Status Code Error Code Error Sub Code Error Message
400  E4000000 E4000001 Bad request. Missing one or more of the mandatory HTTP headers
400 E4000000 E4000002 Bad request. Invalid query parameter
400  E4000000 E4000003 Input body is not as per expected schema
400  E4000000 E4000004 Invalid {field name} value
400 E4000000 E4000040 The CW status did not meet the termination criteria
400 E4000000 E4000041 Invalid relation between type of termination and termination reason.
400 E4000000 E4000042 Reminder after number of months is required.
400 E4000000 E4000043 Add to Do Not Rehire list is required.
400 E4000000 E4000044 Do Not Rehire Reason is required.
400 E4000000 E4000045 Release date is prior to start date.
400 E4000000 E4000046 Timesheets/Expenses exists beyond the selected release date.
401  E4010000 E4010001 Authentication failed. Check the credentials associated with your consumer app
401  E4010000 E4010002 Authentication failed. Access token is invalid or expired
403  E4030000 E4030001 Not Authorized. The user does not have the rights to perform the action
403  E4030000 E4030002 Not Authorized. Invalid scope
403  E4030000 E4030003 Not Authorized. The API user is invalid. Ensure user is active and set as an API user
404  E4040000 E4040001 Not found
405  E4050000 E4050001 Method Not Supported. Service does not support the requested HTTP method
500  E5000000 E5000001 A system or application error occurred, Please contact Coupa CW Admin
  • Was this article helpful?