API docs by Redocly

Workday Strategic Sourcing Contracts API (1.1)

Download OpenAPI specification:

Customer Support

We've provided detailed documentation below to guide you. However, if you need additional assistance, here's how you can get the support you need:

  • Community Discussions: Join the conversation on our Workday Community Discussion Boards (found under the "Collaborate" section in community). Connect with other users, share best practices, and get answers to your configuration questions.
  • Expert Configuration Assistance (Professional Services): For tailored, hands-on support with your specific project, our Professional Services team is available.
    • Looking for personalized guidance? Workday Success Plan customers can submit an "Ask" for expert insights on configuration and best practices.
    • Need custom solutions? Consider Expert Assist, our consulting service for detailed changes and project support.
  • Reporting System Issues: If you suspect a problem with the Workday system itself, please connect with our dedicated support team. Your company's Named Support Contact (NSC) can log a Product Support Defect case. We'll review the issue based on its impact and Workday's service level agreement (SLA).

API Specification

The API conforms to the JSON API Specification.

The current version of this service is indicated by the X-Api-Version header.

Sample version header: X-Api-Version: 1.1.

Date and Time Fields

Our API adheres to the ISO 8601 standard when accepting and formatting Date and Time fields. All Date and Time fields returned by this API will be in the UTC timezone.

Date and Time fields sent to this API can be in any timezone, provided they adhere to the ISO 8601 standard.

Authentication

The Workday Strategic Sourcing API uses API keys to authenticate requests. Every request will require all 3 HTTP headers:

HTTP Header Description
X-Api-Key a company-wide API key
X-User-Token a user-specific API token
X-User-Email user email

You can generate all of those from the API tokens section of your Profile page.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Rate Limiting

Rate limit windows are per second and are shared by all API Keys for a company.

The rate limit is 5 requests per second.

When request submissions exceed the limits, the limit-exceeding requests return 429 Too Many Requests error responses to the client.

Upon receiving a 429 response, it is recommended to retry the request in compliance with the rate limit. One example would be to add a sleep function for 1 second and retry.

External Identifiers (IDs)

The external_id field exists on many of the Workday Strategic Sourcing resources. This optional and mutable extension is intended to store foreign keys of the corresponding resource from a third party system. These IDs are not considered Sourcing Data and may be logged in external systems. Do not include any sensitive or personal data in IDs.

The purpose of external IDs is to:

  • Prevent duplicate record creation
  • Allow resources in Workday Strategic Sourcing and a third party system to share the same identifier
  • Allow for records to be queried or updated without requiring knowledge of the Workday Strategic Sourcing generated IDs

Pagination

Paginated endpoints may return a subset of the total results for a GET request that returns multiple resources. Endpoints that support pagination will include usage details in the Query Parameters section for the resource.

The paginated results can be configured using the page query parameter to configure the number of returned results. The default pagination size is 10 results and the maximum pagination size is 100 results per request.

Endpoints that support pagination may return "self" and "next" sections within the "links" section that navigate to the current and next pages respectively.

Example Paginated Request

Request Query Parameter Format

/projects?page[size]=25

Response Schema

The paginated response will also include the following schema

object

Result set metadata.

object (PaginationLinks)

List of related links.

{}

Filters

The results can be filtered to a subset of the total set of results using filter query parameters.

Endpoints that support filtering will include usage details in the Query Parameters section for the resource.

Most filters that end in equals support a Query Parameter array format to filter by multiple values.

Example:

?filter[status_equals][]=submitted&filter[status_equals][]=resubmitted

Contracts

Use the contracts API to create, update, and query the contracts in Workday Strategic Sourcing.

Contract Object

type
required
string (ContractTypeValue)

Object type, should always be contracts.

id
required
integer (ContractId)

Contract identifier string.

object

Contract attributes.

object (ContractRelationship)

Contract relationship.

object (ResourceLinks)

List of related links.

{
  • "data": {
    }
}

Docusign Envelope Object

type
required
string (DocusignEnvelopeType)

Object type, should always be docusign_envelopes.

id
required
integer (DocusignEnvelopeId)

Docusign envelope identifier string.

object (DocusignEnvelopeAttributes)

Docusign envelope attributes

object (Docusign envelope relationships)
{
  • "type": "docusign_envelopes",
  • "id": 1,
  • "attributes": {
    },
  • "relationships": {
    }
}

Adobe Sign Agreement Object

type
required
string (AdobeSignAgreementType)

Object type, should always be adobe_sign_agreements

id
required
integer (AdobeSignAgreementId)

Adobe Sign Agreement identifier string

object (AdobeSignAgreementAttributes)

Adobe Sign Agreement attributes

object (Adobe Sign Agreement relationships)
{
  • "type": "adobe_sign_agreements",
  • "id": 1,
  • "attributes": {
    },
  • "relationships": {
    }
}

Adobe Sign Document Object

type
required
string (AdobeSignDocumentType)

Object type, should always be adobe_sign_documents

id
required
integer (AdobeSignDocumentId)

Adobe Sign Document identifier string

object (AdobeSignDocumentAttributes)

Adobe Sign Document attributes

object (Adobe Sign Document relationships)
{
  • "type": "adobe_sign_documents",
  • "id": 1,
  • "attributes": {
    },
  • "relationships": {
    }
}

List Contracts

Returns a list of contracts for the specified criteria.

Authorizations:
(api_keyuser_tokenuser_email)
query Parameters
object (ContractInputFilter)

Filter contracts by multiple criteria. Only one filter per attribute is supported. For best performance, we recommend 5 or less filters.

include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

To reduce the number of HTTP requests, related resources can be requested along with the requested primary resources. Such responses are called "compound documents". In a compound document, all included resources will be represented as an array of resource objects in a top-level included member.

The value of the include parameter must be a comma-separated list of relationships from the list of available relationships.

/contracts?include=contract_type,supplier_company

In the response, relationships will be represented as normal linkage objects (containing id and type), and full related resource details will be presented in the included section as resource objects (with attributes, links, and potentially relationships).

object (PageInput)

Customize pagination results with size.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts"

Response samples

Content type
application/vnd.api+json
Example
{
  • "meta": {
    },
  • "data": [
    ],
  • "links": {}
}

Create a Contract

Create a contract with given attributes.

Authorizations:
(api_keyuser_tokenuser_email)
query Parameters
include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

Use the include parameter to request related resources along with the primary resource.

Request Body schema: application/vnd.api+json
object (ContractCreate)

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Get a Contract

Retrieves the details of an existing contract. You need to supply the unique contract identifier that was returned upon contract creation.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique Contract identifier.

query Parameters
include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

Use the include parameter to request related resources along with the primary resource.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts/1"

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Update a Contract

Updates the details of an existing contract. You need to supply the unique supplier contract that was returned upon contract creation.

Please note, that request body must include an id attribute with the value of your contract unique identifier (the same one you passed in the URL).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique Contract identifier.

query Parameters
include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

Use the include parameter to request related resources along with the primary resource.

Request Body schema: application/vnd.api+json
object (ContractUpdate)

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Delete a Contract

Deletes a contract. You need to supply the unique contract identifier that was returned upon contract creation.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique Contract identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     -X DELETE \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts/1"

Get a Contract by External ID

Retrieves the details of an existing contract. You need to supply the unique contract external identifier (the one you used when created the contract).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: 1234-5678-abcd-efgh

Contract external identifier.

query Parameters
include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

Use the include parameter to request related resources along with the primary resource.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts/SUP-1234/external_id"

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a Contract by External ID

Updates the details of an existing contract. You need to supply the unique contract external identifier (the one you used when created the contract).

Please note, that request body must include an id attribute with the value of your contract external identifier (the same one you passed in the URL).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: 1234-5678-abcd-efgh

Contract external identifier.

query Parameters
include
string (ContractRelatedResources)
Enum: "contract_type" "spend_category" "supplier_company" "docusign_envelopes" "adobe_sign_agreements"

Use the include parameter to request related resources along with the primary resource.

Request Body schema: application/vnd.api+json
object (ContractUpdate)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a Contract by External ID

Deletes a contract. You need to supply the unique contract external identifier (the one you used when created the contract).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: 1234-5678-abcd-efgh

Contract external identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     -X DELETE \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts/SUP-1234/external_id"

Describe Contract object

Returns a list of fields for the contract object.

Authorizations:
(api_keyuser_tokenuser_email)

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contracts/describe"

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    },
  • "data": [
    ],
  • "links": { }
}

Contract Types

Use the contract types API to query the contract types in Workday Strategic Sourcing.

Contract Types are used in the contract resource. On POST and PATCH related endpoints for this resource a contract_type_id can be added to set the contract type. The contract_type_id is a foreign key for the contract_types resource's id.

Contract Type Object

type
required
string (ContractTypeType)

Object type, should always be contract_types.

id
required
integer (ContractTypeId)

Contract type identifier string.

object (ContractTypeAttributes)

Contract type attributes.

{
  • "type": "contract_types",
  • "id": 1,
  • "attributes": {
    }
}

List Contract Types

Returns a list of all contract types.

Authorizations:
(api_keyuser_tokenuser_email)

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contract_types"

Response samples

Content type
application/vnd.api+json
{}

Create a Contract Type

Create a contract type with given parameters.

Authorizations:
(api_keyuser_tokenuser_email)
Request Body schema: application/vnd.api+json
object (ContractTypeCreate)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get a Contract Type

Retrieves the details of an existing contract type.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique contract type identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contract_types/1"

Response samples

Content type
application/vnd.api+json
{}

Update a Contract Type

Updates the details of an existing contract type. You need to supply the unique identifier that was returned upon contract type creation.

Please note, that request body must include an id attribute with the value of your contract type unique identifier (the same one you passed in the URL).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique contract type identifier.

Request Body schema: application/vnd.api+json
object (ContractTypeUpdate)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete a Contract Type

Deletes a contract type. You need to supply the unique contract type identifier that was returned upon contract type creation.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
id
required
integer
Example: 1

Unique contract type identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     -X DELETE \
     "https://api.us.workdayspend.com/services/contracts/v1/contract_types/1"

Get a Contract Type by External ID

Retrieves the details of an existing contract type.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: CTR$1

Unique contract type external identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     "https://api.us.workdayspend.com/services/contracts/v1/contract_types/CTR$1/external_id"

Response samples

Content type
application/vnd.api+json
{}

Update a Contract Type by External ID

Updates the details of an existing contract type. You need to supply the unique external identifier assigned to the contract type on creation.

Please note, that request body must include an id attribute with the value of your contract type unique identifier (the same one you passed in the URL).

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: CTR$1

Unique contract type external identifier.

Request Body schema: application/vnd.api+json
object (ContractTypeUpdate)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete a Contract Type by External ID

Deletes a contract type. You need to supply the unique contract type external identifier assigned to the contract type on creation.

Authorizations:
(api_keyuser_tokenuser_email)
path Parameters
external_id
required
string
Example: CTR$1

Unique contract type external identifier.

Responses

Request samples 

curl -H "X-Api-Key: ${COMPANY_KEY}" \
     -H "X-User-Token: ${USER_TOKEN}" \
     -H "X-User-Email: ${USER_EMAIL}" \
     -H "Content-Type: application/vnd.api+json" \
     -X DELETE \
     "https://api.us.workdayspend.com/services/contracts/v1/contract_types/CTR$1/external_id"