Welcome to the Trust Your Supplier (TYS) API documentation! Here, you'll find all the essential information for integrating with our API endpoints. We've crafted this documentation to be user-friendly and rich with examples. For any questions, please reach out to your account representative. To get started quickly, we recommend using our QuickStart guide, which provides a step-by-step walkthrough for integrating the API into your site or app, allowing you to seamlessly access and utilize data from our platform.
API Keys and Access
The Trust Your Supplier (TYS) API Gateway is the primary access point for securely interacting with TYS data using OAuth2. Authorized users can generate and manage credentials such as Client ID, Client Secret, User ID, and Password, which are needed for API access. To obtain these credentials, an admin must log in to TYS and go to Marketplace > API Gateway. Since these credentials are sensitive, they must be protected, and any compromise should be reported to TYS Support for immediate revocation and regeneration.
Example:
- Client ID: jxP8b7RVkfEmC5r4UmqTPY1YJFl055o3
- Client Secret: nTSDGmXRV6V9CrHcloYPQ4KYWKBqo5ri
- User ID: ypovwdqz
- Password: C!=1Evv&
API Protocols
The Trust Your Supplier (TYS) API communicates using GET and POST requests, with HTTP response codes indicating status and errors. All responses are formatted in standard JSON. The API is delivered over HTTPS with TLS v1.2 or higher to ensure data privacy, and lower TLS versions are not supported. Every request must include a Content-Type header set to application/json, and the request body must be valid JSON.
Authentication is a critical component of the Trust Your Supplier (TYS) API, ensuring that only authorized users and systems can access the platform's resources and functionality. This section explains the methods used to authenticate users, the security protocols that protect data during the authentication process, and how sessions are managed to maintain secure access.
Authentication Methods
The TYS API uses the following authentication method to verify users and systems:
- OAuth 2.0 Client Credentials: OAuth 2.0 client credentials is a grant type used in OAuth 2.0 for machine-to-machine authentication. It allows the user to obtain an access token by presenting its client ID and client secret directly to the authorization server.
Security Protocols
The TYS API employs robust security protocols to protect data and ensure secure communications:
- HTTPS Encryption: All API interactions are conducted over HTTPS, which encrypts the data transmitted between the client and server, preventing eavesdropping and tampering.
- Token Expiry: OAuth 2.0 tokens are valid for 24 hours. Once expired, a new token must be obtained, minimizing the risk of unauthorized access if a token is compromised.
The Trust Your Supplier (TYS) API offers a range of endpoints to facilitate interactions with various resources within the platform. These endpoints enable users to manage supplier relationships, access data, and automate procurement processes. These endpoints optimize supplier management and ensure streamlined operations.
Key endpoints include:
- Access Token
- GET Relationships
- GET Bank Accounts
- GET Internal-Checklist
- GET Supplier Profile
- GET Supplier Profile Delta
- GET Questionnaire
Access Token API
This endpoint in the Trust Your Supplier (TYS) API is used to obtain an OAuth 2.0 access token. This token is essential for making authenticated API requests to other TYS endpoints. To generate the token, the client must provide their credentials, such as the client ID and client secret. Once the token is obtained, it is included in the Authorization header of subsequent API requests, allowing secure and authorized access to the TYS platform's resources.
Input:
{
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}",
"username": "{{username}}",
"password": "{{password}}"
}
Result example:
{
"access_token": "pSlTEAwCceTBi12aEs7496evFyB49flu"
}
GET Relationships
This endpoint in the TYS API is used to retrieve a list of supplier relationships that have been added or updated since the specified date and time. This allows clients to efficiently sync their systems by fetching only the changes made after the specified timestamp, rather than retrieving all relationships. This endpoint is particularly useful for keeping supplier data current in real-time systems.
Input: v1/relationships?
Pagination Handling in TYS API:
- Result Limit: Each request retrieves up to 100 results.
- Check for More Records: If "hasMoreRecords": true, additional records are available.
- Continue Fetching: Use the provided "next page" URL to retrieve the next set of results.
- Repeat Until Complete: Continue this process until "hasMoreRecords": false.
- Save for Next Run: Once "hasMoreRecords" is false, save the nextPageHref to be used for the next API run.
Result Example:
{
"supplierId": "11eab49167ea571099a42dece17f4f87",
"companyName": "TestSupplier",
"status": "accepted",
"tysID": "US138267295",
"supplierHRef": null,
"updatedDate": "2020-06-22T14:30:21.384Z",
"supplierLiaisons": [
{
"email": "[email protected]",
"name": "test supplier",
"invitationDate": "2020-06-22T14:05:19.483Z"
}
],
"buyerLiaisons": [
{
"email": "[email protected]",
"name": "IBM Admin"
}
],
"customFields": null,
"buyerSystemDetails": [],
"numberOfQuestionnairesAssigned": 3,
"numberOfUnansweredQuestionnaires": 3,
"isOnHold": false,
"statusHistory": [
{
"status": "accepted",
"statusChangeDate": "2020-06-22T14:30:21.384Z",
"statusChangedBy": "test supplier",
"statusChangedByEmail": "[email protected]"
},
GET Bank Accounts
This endpoint in the TYS API retrieves bank account details for a specific supplier relationship using a unique relationship ID. It's essential for managing financial transactions, verifying data, and ensuring the accuracy of supplier banking information within TYS. API consumers can also use the bankAccountHref URL provided by the API to pull bank account data directly, rather than constructing the URL manually. This is typically done after the supplier reaches a certain status in TYS, such as after onboarding.
Input: v1/relationships/11eb03dc1031ce00ae040d357bba45c7/bank-accounts.
Result example:
{
"code": "BSRBARRID404S",
"status": "SUCCESS",
"message": "No bank account relationship exists for this relationshipID"
}
GET Internal Checklist
This endpoint in the TYS API is used to retrieve the internal checklist associated with a specific supplier relationship. This checklist may include tasks, compliance items, or other internal processes that need to be completed or monitored for the supplier. The unique relationship ID specifies which supplier's checklist is being accessed. This feature helps ensure that all necessary internal actions are tracked and managed efficiently.
Input: /v1/relationships/11eb03dc1031ce00ae040d357bba45c7/internal-checklist
Result example:
{
"questionnaire": {
"iddID": "11ea2e5e2f80b8b0818223aac4509ff4",
"questionnaireName": "PIF Indicator",
"category": "Standard",
"version": "V1.0",
"questions": []
},
"rules": [
{
"id": "45ed9edfbad7330fa93d29c43a0981sPO",
"description": "Supplier invite Rule without criteria",
"event": "SUPPLIER_PROFILE_PUBLISH"
}
],
"status": "pending",
"version": "V-1"
},
GET Supplier Profile
This endpoint in the TYS API is used to retrieve detailed information about a specific supplier. The unique supplier ID identifies the supplier whose data is being requested. This endpoint returns comprehensive supplier details, such as company information, certifications, compliance records, and other relevant data that helps organizations manage and verify their supplier relationships within the TYS platform.
Input: /v1/suppliers/11eab4b84e7b0a50997d197d82888f36
Result example:
{
"companyName": "Google",
"legalName": "GOOGLE Company",
"primaryPhoneNumber": "+1 (984) 764-64545",
"primaryPhoneNumberCountryCode": "1",
"taxCountry": "United States of America",
"businessDescription": "Google, LLC is an American multinational technology company that specializes in Internet-related services and products, which include online advertising technologies, a search engine, cloud computing, software, and hardware. It is considered one of the Big Five technology companies in the U.S. information technology industry, alongside Amazon, Facebook, Apple, and Microsoft.. \n\nGoogle was founded in September 1998 by Larry Page and Sergey Brin while they were Ph.D. students at Stanford University in California. Together they own about 14 percent of its shares and control 56 percent of the stockholder voting power through supervoting stock. They incorporated Google as a California privately held company on September 4, 1998, in California. Google was then reincorporated in Delaware on October 22, 2002.[12] An initial public offering (IPO) took place on August 19, 2004, and Google moved to its headquarters in Mountain View, California, nicknamed the Googleplex. In August 2015, Google announced plans to reorganize its various interests as a conglomerate called Alphabet Inc. Google is Alphabet's leading subsidiary and will continue to be the umbrella company for Alphabet's Internet interests. Sundar Pichai was appointed CEO of Google, replacing Larry Page, who became the CEO of Alphabet.",
"dateEstablished": "2001-01-23T00:00:00.000Z",
"emailAddress": "[email protected]",
"nativeBusinessName": "",
"nativeLegalName": "",
"numberOfFullTimeEmployees": 500,
"numberOfPartTimeEmployees": 10,
"primaryFaxNumber": "",
"primaryFaxNumberCountryCode": "",
"website": "http://www.google.com",
"unspsc": [
"23211101",
"32111701",
"32111703",
"32111704",
"32131003",
"39121628"
],
"lastLogin": "2024-05-17T08:04:14.973Z",
"lastLoginBy": "[email protected]",
"tysID": "US606715363",
"managementProfile": {
"ceos": [
{}
],
"cfos": [
{}
],
"dos": [
{}
],
"other": [
{}
]
},
"contacts": [
{
"title": "",
"firstName": "Google",
"lastName": "User",
"middleName": "",
"yearOfBirth": "",
"secondaryPhone": "",
"email": "[email protected]",
"alternateEmail": "",
"contactType": [
"customer_relationship_contact"
]
},
{
"title": "CFO",
"firstName": "Mark",
"lastName": "Diller",
"middleName": "",
"yearOfBirth": "1997",
"primaryPhoneNumber": "+1 (746) 464-6465",
"secondaryPhone": "",
"email": "[email protected]",
"alternateEmail": "",
"contactType": [
"other_management"
],
"address": {
"street1": "1600 AMPHITHEATRE PKWY MOUNTAIN VIEW",
"street2": "",
"street3": "",
"city": "MOUNTAIN VIEW",
"state": "California",
"country": "United States of America",
"postalCode": "94043-1351",
"poBox": "",
"poBoxPostalCode": ""
}
},
{
"title": "Point of Contact",
"firstName": "Mohit",
"lastName": "B",
"middleName": "",
"yearOfBirth": "0000",
"primaryPhoneNumber": "+1 (111) 111-1111",
"secondaryPhone": "",
"email": "[email protected]",
"alternateEmail": "",
"contactType": [
"chief_financial_officer_or_equivalent",
"director_of_sale_or_equivalent"
],
"address": {
"street1": "1600 AMPHITHEATRE PKWY MOUNTAIN VIEW",
"street2": "",
"street3": "",
"city": "MOUNTAIN VIEW",
"state": "California",
"country": "United States of America",
"postalCode": "94043-1351",
"poBox": "",
"poBoxPostalCode": ""
}
},
{
"title": "PTL",
"firstName": "Pradeep",
"lastName": "J",
"middleName": "",
"yearOfBirth": "0000",
"primaryPhoneNumber": "+1 (111) 111-2222",
"secondaryPhone": "",
"email": "[email protected]",
"alternateEmail": "",
"contactType": [
"chief_executive_officer_or_equivalent"
],
"address": {
"street1": "1600 AMPHITHEATRE PKWY MOUNTAIN VIEW",
"street2": "",
"street3": "",
"city": "MOUNTAIN VIEW",
"state": "California",
"country": "United States of America",
"postalCode": "94043-1351",
"poBox": "",
"poBoxPostalCode": ""
}
}
],
"financialProfile": {
"financial": [
{
"year": 2019,
"asset": 54365,
"liability": 435460,
"profit": 43535,
"revenue": 200000
},
{
"year": 2018,
"asset": 6456,
"liability": 6456,
"profit": 456476,
"revenue": 4543535
},
{
"year": 2017,
"asset": 43645,
"liability": 6456,
"profit": 4324,
"revenue": 64566
}
],
"currency": "USD",
"w9BusinessName": "Google",
"w9Name": "GOOGLE Company",
"fiscalMonth": 4,
"financialDocuments": [
{
"title": null,
"documentHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/documents/null"
}
]
},
"taxProfile": {
"businessType": "Corporation",
"dunsNumber": "248500000",
"taxRegistrationNumber": "76-9028846",
"taxRegistrationDocuments": [
{
"title": "Tax Certificate.pdf",
"documentHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/documents/11eb76b13be3198081796b62a6251ae5"
}
]
},
"ownershipProfile": {
"individualOwners": [],
"parentCompany": [],
"ultimateParentCompany": {},
"entityOrOrganizations": [
{
"ownershipPercentage": "20"
}
]
},
"naics": [
"1111 - Oilseed and Grain Farming T",
"11 - Agriculture, Forestry, Fishing and Hunting T"
],
"addresses": [
{
"addressID": "11eab4b8980618e0997d197d82888f36",
"addressType": "Headquarters",
"addressTypeOther": "",
"street1": "1600 AMPHITHEATRE PKWY MOUNTAIN VIEW",
"street2": "",
"street3": "",
"city": "MOUNTAIN VIEW",
"state": "California",
"country": "United States of America",
"postalCode": "94043-1351",
"poBox": "",
"poBoxPostalCode": "",
"DunsNumber": "079460720"
},
{
"addressID": "11eb3e4f1e2ff510bd03f7c919326fe0",
"addressType": "Office",
"addressTypeOther": "",
"street1": "100 Main St",
"street2": "",
"street3": "",
"city": "Raleigh",
"state": "North Carolina",
"country": "United States of America",
"postalCode": "27511",
"poBox": "",
"poBoxPostalCode": "",
"DunsNumber": ""
},
{
"addressID": "11eb550a26986e90a2a2814ca5df34f4",
"addressType": "Office",
"addressTypeOther": "",
"street1": "200 A St",
"street2": "",
"street3": "",
"city": "Cary",
"state": "North Carolina",
"country": "United States of America",
"postalCode": "74646",
"poBox": "",
"poBoxPostalCode": "",
"DunsNumber": ""
}
],
"questionnaireHref": [
{
"questionnaireID": "11e8a7084046f85086d683ea662ae7b0",
"questionnaireName": "Company Operations",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e8a7084046f85086d683ea662ae7b0"
},
{
"questionnaireID": "11e8a7087ac5cb0086d683ea662ae7b0",
"questionnaireName": "Diversity - United States of America",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e8a7087ac5cb0086d683ea662ae7b0"
},
{
"questionnaireID": "11e8a70896b1028086d683ea662ae7b0",
"questionnaireName": "Ethics and Compliance",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e8a70896b1028086d683ea662ae7b0"
},
{
"questionnaireID": "11e9f1b30941fbb0a6860b1b5ba34c0a",
"questionnaireName": "Trade Compliance",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e9f1b30941fbb0a6860b1b5ba34c0a"
},
{
"questionnaireID": "11e9fbcb541732509d52f33cd5f95702",
"questionnaireName": "Anti-Bribery, Anti-Corruption",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e9fbcb541732509d52f33cd5f95702"
},
{
"questionnaireID": "11ea74a1a7e48730846ae99d778c0705",
"questionnaireName": "MSME Certification (India)",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11ea74a1a7e48730846ae99d778c0705"
},
{
"questionnaireID": "11ea88cea38e3d709cce91af7e73f47e",
"questionnaireName": "State and SEZ GST Information (India)",
"questionnairHRef": "https://integration-gateway.slyncer.com/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11ea88cea38e3d709cce91af7e73f47e"
}
]
}
GET Supplier Delta
This endpoint in the TYS API is used to retrieve the differences or changes in a supplier's profile since the specified timestamp. This allows users to track updates or modifications to the supplier's information, such as changes in certifications, compliance records, or other profile details, helping to keep the supplier data current and accurate.
Input: /v1/suppliers/11eab4b84e7b0a50997d197d82888f36/profile/diff?timestamp=2022-01-01T00:00:00.000Z
Result example:
{
"dateEstablished": {
"oldValue": "2001-01-02T05:00:00.000Z",
"newValue": "2001-01-23T00:00:00.000Z"
},
"financialProfile": {
"fiscalMonth": {
"oldValue": "",
"newValue": 4
}
},
"taxProfile": {
"dunsNumber": {
"oldValue": "006908354",
"newValue": "248500000"
}
},
"diversityInfo": {
"oldValue": "",
"newValue": {
"discloseDiversityInfo": true,
"isDiversitySupplier": true,
"associatedOrganizations": null,
"categories": [
{
"category": "LGBTQ+",
"subcategory": "",
"certificates": [
{
"certifier": "NGLCC",
"expiryDate": "2022-12-12",
"documents": [
{
"id": "11ed75461b72eaf0ba70fb3a23ad9459",
"title": "sample.pdf"
}
],
"otherCertifierDetails": ""
}
]
},
{
"category": "MBE",
"subcategory": "ANC",
"certificates": [
{
"certifier": "Federal Register",
"expiryDate": "2022-12-13",
"documents": [
{
"id": "",
"title": ""
}
],
"otherCertifierDetails": ""
}
]
},
{
"category": "MBE",
"subcategory": "ABE",
"certificates": [
{
"certifier": "NMSDC",
"expiryDate": "2022-12-20",
"documents": [
{
"id": "",
"title": ""
}
],
"otherCertifierDetails": ""
}
]
}
]
}
},
"smallBusinessInfo": {
"oldValue": "",
"newValue": {
"isSmallBusiness": false,
"categories": [],
"documents": null
}
},
"disadvantagedZoneInfo": {
"oldValue": "",
"newValue": {
"isDisadvantaged": false,
"categories": [],
"documents": null
}
}
}
GET Questionnaire
This TYS API endpoint retrieves a questionnaire assigned to a supplier. You can use the questionnaire URL from the supplier profile API. The URL includes the unique supplier ID and questionnaire ID needed to access this questionnaire. This endpoint is useful for tracking and managing the completion of questionnaires related to compliance, onboarding, or other processes involving the supplier.
Input:/v1/suppliers/11eab4b84e7b0a50997d197d82888f36/questionnaires/11e8a7084046f85086d683ea662ae7b0
Note: You can refer to our Data Dictionary at any time for detailed explanations of each API field name. It offers clear definitions and descriptions, helping you understand the data structure and ensure accurate use of the API in your integrations.
The TYS API uses standard HTTP status codes to indicate the success or failure of a request. These codes provide insight into the result of the API call:
- 4xx Client Error Codes:
-
- 400 Bad Request: The request was malformed or contains invalid parameters.
-
- 401 Unauthorized: Authentication is required, or the provided credentials are invalid.
-
- 403 Forbidden: The client does not have permission to access the requested resource.
-
- 404 Not Found: The requested resource could not be found on the server.
-
- 409 Conflict: The request could not be completed due to a conflict with the current state of the resource (e.g., duplicate entries).
- 5xx Server Error Codes:
-
- 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
-
- 502 Bad Gateway: The server received an invalid response from an upstream server.
-
- 503 Service Unavailable: The server is currently unavailable, usually due to maintenance or overload.
Error Responses
When the TYS API encounters an issue processing a request, it returns an error response in JSON format. The error response typically includes:
- Error Code: A numeric or string code that categorizes the error.
- Message: A human-readable description of the error, explaining what went wrong.
- Details: Additional information or context about the error, which may include validation errors, missing parameters, or other issues.
Example Error Response:
{
"error": {
"code": "401",
"message": "Unauthorized. The access token is missing or invalid.",
"details": [
{
"parameter": "Authorization",
"issue": "Token expired"
}
]
}
}
Postman is a popular tool used for testing APIs, allowing developers to easily send requests, examine responses, and automate testing workflows. The Trust Your Supplier (TYS) API can be tested and explored using Postman, making it easier for developers to integrate the API into their applications and ensure that it behaves as expected.
Postman Collections
A Postman Collection is a group of pre-configured requests that can be organized and saved for repeated use. For the TYS API, a Postman Collection can include various requests to different endpoints, complete with necessary parameters, headers, and example data.
Steps to Use Postman Collections with the TYS API:
1. Import the Postman Collection:
- You can import a pre-built Postman Collection that contains all the necessary TYS API endpoints. This might be provided by TYS or created manually by you.
- To import, open Postman, go to "Collections," click "Import," and select the Collection file (usually a .json file).
2. Configure Environment Variables:
- Postman Collections can use environment variables to store values such as API keys, tokens, or base URLs. This allows you to quickly switch between different environments (e.g., development, staging, production).
- Set up the environment variables for {{tys-integration-api-url}}, {{access_token}}, and any other required parameters.
3. Run Requests:
- Once the Collection is imported and configured, you can start sending requests to the TYS API by selecting the appropriate request from the Collection and clicking "Send."
- The response will be displayed in Postman, where you can examine the data, status codes, and headers.
4. Automate Testing:
- Postman allows you to automate tests by writing test scripts in JavaScript that run after each request. For example, you can verify that the status code is 200 OK, or check that certain fields are present in the response.
- Add test scripts to the "Tests" tab for each request in the Collection.
5. Use Postman Runner:
- Postman’s Collection Runner allows you to run all the requests in a Collection sequentially or in parallel. This is useful for automated testing or running multiple test cases at once.
Example Postman Collection Structure for TYS API:
Folder: Supplier Management
- GET /v1/suppliers – Retrieve a list of suppliers.
- POST /v1/suppliers – Onboard a new supplier.
- GET /v1/suppliers/{supplierId} – Retrieve a specific supplier’s details.
Folder: Relationship Management
- GET /v1/relationships – Retrieve supplier relationships.
- PUT /v1/relationships/{relationshipId} – Update a supplier relationship.
Folder: Authentication
- POST /oauth2/token – Retrieve an access token for API authentication.
Using Postman Collections allows you to organize and streamline the testing process, making it easier to validate the functionality of the TYS API and ensure that it integrates smoothly into your application.
When working with the Trust Your Supplier (TYS) API, having access to support and resources is crucial for resolving issues, sharing knowledge, and providing feedback. This section provides details on how to get in touch with technical support, connect with the developer community, and offer feedback on the API.
Technical Support
For any technical issues, inquiries, or assistance related to the TYS API, you can reach out to the technical support team. They are available to help troubleshoot problems, provide guidance on API usage, and answer any questions you may have.
- Email: [email protected]
- Phone: +1-800-555-1234 (Available Monday to Friday, 9 AM to 6 PM EST)
- Support Portal: TYS Support Portal – Access FAQs, documentation, and contact support.
Feedback Channels
If you have questions or need assistance with new features, please contact our support team at [email protected]. Our support hours are from 01:00 AM to 05:00 PM EST, and we will respond promptly during these times.
