Use of the Supplier Data API with Pagination vendorDataRequests Endpoint

The Supplier Data API with Pagination vendorDataRequests endpoint uses the POST method to send a JSON request to your site. The request specifies query and filter parameters in the URL, authentication in the header, and filters and output format in the body.

Method

Endpoint

Pagination limit per page

Description

POST

{{runtime_URL}}/supplierdatapagination/v4/prod/vendorDataRequests

1000

Returns the data specified in request body filters for all suppliers, with or without IDs for their associated questionnaires.

Refer to Supplier Data API with Pagination Header Parameters for information on header parameters and Supplier Data API with Pagination Query and Filter Parameters for information on query and filter parameters.

Request Filter and Output Values for the vendorDataRequests Endpoint

The JSON request that the vendorDataRequests endpoint of the Supplier Data API with Pagination sends to your site uses name/value pairs or arrays to specify the data you want to return in output.

The following table describes the valid values for name/value pairs and arrays in request body.

Name/Value Pair or Array

Valid Values

businessUnitList

One or more of the business unit or department IDs loaded in your site as master data and used in supplier management projects, separated by commas.

categoryList

One or more of the category IDs loaded in your site as master data and used in supplier management projects, separated by commas.

outputFormat

Either CSV or JSON.

withQuestionnaire

TRUE to include the titles, IDs, and types of any questionnaires associated with the suppliers returned in results; otherwise, FALSE.

withDisqualifications

TRUE to include the exact process type in the disqualification information response when you disqualify a process.; otherwise, FALSE.

smVendorIds

One or more valid SM vendor IDs for suppliers in your site, separated by commas.

pageLimit

A number between 1 and 500. This output filter is only applicate in requests with "withQuestionnaire": true. This filter specifies the n umber of results to include per page of output and sets a maximum of 500 results per page to prevent requests that include questionnaire data from timing out. If you do not set a value, or if the value you set is greater than 500, the default value is 500.

withGenericCustomFields

TRUE to include all custom field data associated with the suppliers returned in results; otherwise, FALSE.

This filter returns data in fields in the following classes, grouped by class:
  • vendor.supplier.GenericCustomField

  • vendor.businessPartnerGenericCustomField

  • vendor.CompanyCode.customFieldApis

  • vendor.bankInfos.customFieldApis

preferredLevelList

One or more numbers between 1 and 5, separated by commas. 1 is the highest preferred level and 5 is the lowest.

qualificationStatusList

One or more of the following values, separated by commas:

Cancelled, QualificationRejected, Disqualified, QualificationExpired,PendingDisqualificationApproval, QualificationStarted, InQualification, PendingQualificationApproval, PendingQualificationResubmit, QualificationRestricted, QualifiedWithException, Qualified

For process qualifications, use standard qualification lifecycle status that corresponds to the custom qualification process status for which you want output.

regionList

One or more of the region codes loaded in your site as master data and used in supplier management projects, separated by commas.

registrationStatusList

One or more of the following values, separated by commas:

RegistrationDenied, InExternalApprovalForCreation, NotInvited, Invited, InRegistration, PendingApproval, PendingResubmit, Registered

The following sample request body retrieves questionnaire titles, IDs, and types for two specific suppliers in JSON format:
{
	"outputFormat":"JSON",
	"withQuestionnaire":true,
	"smVendorIds":["S1004848","S1004834"]
}
The following sample request body retrieves questionnaire names, IDs, and types and custom field data for all suppliers in JSON format, limiting results to 250 per page:
{
	"outputFormat":"JSON",
	"withQuestionnaire":true,
	"pageLimit":250,
	"withGenericCustomFields":true
}
The following sample request body retrieves the exact process type in the disqualification information response when you disqualify a process:
{
	"outputFormat":"JSON",
	"withQuestionnaire":false,
	"pageLimit":250,
	"withGenericCustomFields":true,
	"withDisqualifications":true
}

Additional Parameters in Request Body of the vendorDataRequests Endpoint

The JSON request that the vendorDataRequests endpoint of the Supplier Data API with Pagination sends to your site uses name/value pairs or arrays to specify the data you want to return in output.

The following table describes valid values for name/value pairs and arrays in the request body. The parameters list below shows only those that are introduced as part of the current enhancements to the vendorDataRequests endpoint:

Name/Value Pair or Array

Valid Values

erpVendorIds

One or more valid ERP vendor IDs for suppliers in your site, separated by commas. For more information, see Supplier IDs in SAP Ariba Supplier Lifecycle and Performance.

withBankDetail

TRUE to include all bank related data associated with the suppliers returned in results; otherwise, FALSE.

withTaxDetail

TRUE to include all tax related data associated with the suppliers returned in results; otherwise, FALSE.

withCompanyCodeDetail

TRUE to include all company code details associated with the suppliers returned in results; otherwise, FALSE.

The following sample request body retrieves bank details, tax details, and company code details for a specific supplier in JSON format, limiting results to 500 per page:
{
	"smVendorIds": ["S10109602"],
	"erpVendorIds": ["1351015"],
	"withBankDetail":true,
	"withTaxDetail":true,
	"withCompanyCodeDetail":true,
	"pageLimit":500,
	"outputFormat":"JSON"
}

Output Fields

The response for a vendorDataRequests requests includes anchor fields, which are included in every response, and optional output fields that can be configured in your site, in the specified JSON or CSV format.

JSON responses can include the following fields:

Field

Anchor Field?

Notes

Supplier Name

Yes

 

ERP Vendor ID

Yes

 

SM Vendor ID

Yes

 

An Id

Yes

 

ACM ID

Yes

 

Registration Status

Yes

 

Qualification Status

Yes

Qualification status can be from either a supplier disqualification or a process disqualification.

Integrated to ERP

Yes

 

Duplicate SM Vendor Id

No

 

Last Integration State

No

 

Last Confirmation State

No

 

Source System

No

 

Master Vendor Id

No

 

Form of Address Code

No

 

name2

No

 

name3

No

 

name4

No

 

Duns Id

No

 

Industry Code

No

 

Record Created Date

No

 

Creator

No

 

Blocked Status

No

 

Last Review Date

No

 

Last Update Date

No

 

Last Status Change Date

No

 

Primary Supplier Manager

No

 

Relationship Established

No

 

Alternate Supplier Manager

No

 

Approved

No

 

Transactional Supplier

No

 

Transactional Supplier Request Status

No

 

Main Vendor Type

No

 

Address - Line1

Yes

 

Address - City

Yes

 

Address - Country Code

Yes

 

Address - Region Code

Yes

 

Address - Postal Code

Yes

 

Primary contact first name

No

 

Primary contact middle name

No

 

Primary contact last name

No

 

Primary contact email

No

 

qualifications

No

qualifications covers both qualifications (either supplier qualifications or process qualifications) and preferred category statuses and includes:

  • Qualification Status

  • Preferred Status

  • Category

  • Region

  • Business Unit

  • Process Type

For process qualifications, the Process Type field includes the type of the qualification process as defined by process type data in your site.

questionnaires

No

The fields related to questionnaires are included in JSON output if your request specifies "withQuestionnaire" : "TRUE". They are:
  • questionnaireId

  • questionnaireTitle

  • workspaceType

  • workspaceId

  • matrixInfo

genericCustomFields

No

Custom fields are included in JSON output if your request specifies "withGenericCustomFields" : "TRUE".

CSV responses can include the following fields:
  • Supplier Name

  • ERP Vendor ID

  • SM Vendor ID

  • An Id

  • Acm Id

  • Registration Status

  • Integrated to ERP

  • Address - Line 1

  • Address - Line 2

  • Address - Line 3

  • Address - City

  • Address - Country Code

  • Address - Region Code

  • Address - PO Box

  • Address - Postal Code

  • Qualification Status

  • Preferred Status

  • Category

  • Region

  • Business Unit

For both types of output, values for registration and qualification statuses are the unique names for those statuses. The supported values for preferred levels are the numbers 1-5. Output that uses your company's customized labels for these statuses and levels is not currently supported. The output uses the same values as the request filters.

Additional Output Fields in Response Body of the vendorDataRequests Endpoint

The response for the vendorDataRequests endpoint generates optional output fields in the specified JSON.

The existing endpoint returns several fields in the response JSON. Note that the list below shows only those response fields that are returned as part of the current enhancements to the vendorDataRequests endpoint:

Field

Notes

Bank Related Information

accountName

A name for the supplier's bank account.

accountNumber

The supplier's bank account number.

bankAccountExternalID

If the current bank details are known under a different ID in an external system, you can store this ID here.

bankAccountStandardID

IBAN (International Bank Account Number)

bankInternalID

The bank key (under which the bank data is stored in the appropriate country) is specified in this field.

bankAccountType

The type of the supplier bank account; for example, checking.

bankBranch

The name of the supplier's bank branch.

controlKey

The field contains a check key for the combination bank number and bank account number.

country

The country/region in which the supplier's bank operates.

address

Address output

line1

line2

line3

poBox

city

countryCode

region

postalCode

Tax Related Information

countryCode

A set of unique identifiers for the taxes to which the supplier is subject, as defined by each country/region's tax authority.

partyTaxID

taxIdentificationNumberTypeCode

longPartyTaxID

vatRegistrationNumber

The VAT number assigned to the supplier.

Company Code Related Information

companyCode

Company code output

paymentMethodsCode

planningGroupCode

cashDiscountTermsCode

generalLedgerAccountReferenceID

subjectToWithholdingTaxIndicator

withholdingTaxCode

withholdingTaxTypeCode

supplierGenericCustomField

Custom fields are included in JSON output if your request specifies "withGenericCustomFields": true

businessPartnerGenericCustomField

companyCodeGenericCustomField

bankInfoGenericCustomField

The following example shows a sample response:
[
    {
        "Supplier Name": "katTB1692776616263",
        "SM Vendor ID": "S10113105",
        "ERP Vendor ID": "1801236",
        "ACM ID": "ACM_59304",
        "Registration Status": "NotInvited",
        "Qualification Status": "NotQualified",
        "Integrated to ERP": "NotIntegrated",
        "Last Integration State": "NotIntegrated",
        "Source System": "SM",
        "Record Created Date": "1692776751863",
        "Last Review Date": "0",
        "Last Update Date": "1692776768868",
        "Last Status Change Date": "1692776757549",
        "Approved": "true",
        "Transactional Supplier": "false",
        "Main Vendor Type": "true",
        "Primary contact first name": "Ptor",
        "Primary contact last name": "katTB1692776616263",
        "Primary contact email": "TB1692776616266@aribalq.com",
        "bankInfos": [
            {
                "accountName": "Ahname",
                "accountNumber": "435455",
                "bankAccountExternalID": "57744",
                "bankAccountStandardID": "324355",
                "bankInternalID": "454534",
                "bankBranch": "Bbranch",
                "country": "US",
                "address": [
                    {
                        "line1": "9690 Deereco road",
                        "city": "Timonium",
                        "countryCode": "US",
                        "postalCode": "21093"
                    }
                ]
            }
        ],
        "taxInfos": [
            {
                "countryCode": "US",
                "partyTaxID": "1692776616280",
                "taxIdentificationNumberTypeCode": "1"
            },
            {
                "countryCode": "US",
                "partyTaxID": "1692776617364",
                "taxIdentificationNumberTypeCode": "2"
            },
            {
                "countryCode": "US",
                "taxIdentificationNumberTypeCode": "5",
                "longPartyTaxID": "1692776618375"
            },
            {
                "countryCode": "US",
                "taxIdentificationNumberTypeCode": "6",
                "longPartyTaxID": "1692776619385"
            }
        ],
        "companyCodes": [
            {
                "companyCode": "100",
                "paymentMethodsCode": "DSFSF",
                "planningGroupCode": "GC3455",
                "cashDiscountTermsCode": "CD43",
                "generalLedgerAccountReferenceID": "RID435345",
                "withHoldingTaxes": [
                    {
                        "subjectToWithholdingTaxIndicator": "WTAX32434",
                        "withholdingTaxCode": "WTCode2424",
                        "withholdingTaxTypeCode": "WTXSD"
                    }
                ]
            }
        ]
    }
]

Configuring Export Fields for the Supplier Data API with Pagination

This topic describes how to specify fields to be included in the Supplier Data API with Pagination data export.

Prerequisites

To configure export fields, you must be a member of the SM Ops Administrator group.

Context

You can specify which fields to include in data extracted by applications built on the Supplier Data API with Pagination.
The following anchor fields are always returned:
  • Supplier Name

  • SM Vendor ID

  • ERP Vendor ID

  • ANID

  • ACMID

  • Registration Status

  • Qualification Status

  • Integrated to ERP

  • Address

You can configure the following fields to be included in the data export:
  • Last Integration State

  • Last Confirmation State

  • Source System

  • Master Vendor Id

  • Form of Address code

  • Duns Id

  • Industry Code

  • Record Created Date

  • Blocked Status

  • Last Review Date

  • Last Update Date

  • Last Status Change Date

  • Primary Supplier Manager

  • Relationship Established Type

  • Supplier Manager

  • Approved

  • Transactional Supplier

  • Transactional Supplier Request Status

  • Main Vendor Type

  • Primary Contact

  • Qualification

To specify which fields are included in the Supplier Data API with Pagination data export, follow these steps:

Procedure

  1. On the dashboard, choose Start of the navigation pathManage Next navigation step SM AdministrationEnd of the navigation path.
  2. Choose Config Fields.
  3. In the Type of Data section, choose Supplier.
  4. In the API section, select Supplier Data API.
  5. Select the the fields you wish to include in the data export. To ensure that a field is not included in the data export, confirm that it isn't selected.
  6. Choose Save.