API Reference

Production:

http://sdp.tealbook.com/graphql

Introduction to SDP

The TealBook Supplier Data Platform (SDP) delivers trusted supplier data to targeted enterprise systems via API integration. SDP continuously enriches and autonomously refreshes supplier data.

TealBook provides attribute-level trust scores that can be used in conjunction with our Business Rules Engine to give you control and flexibility over which data attributes are accepted and provided.

If you have any Support inquiries, please reach out to support@tealbook.com or submit a ticket here.

Accessing the APIs

Once your organization has been created in SDP, you can access your API Credentials from the SDP User Console. If you do not have access to the SDP User Console, please reach out to your system administrator or to support@tealbook.com.

Step-by-Step Process:

Once you've logged into the SDP User Console, navigate to the API Credentials page.
If this is your organization's first time configuring your API Credentials, there will be a ‘Create Credentials’ button. If your organization has already configured your API Credentials but you need to reset them, there is a ‘Reset Secret’ button.
You can copy your Client ID and Secret from this page.
Open up your tool of choice for API interactions (e.g. Postman).
Create a new POST request type to sdp.tealbook.com/api/auth/login.
In the Body under x-www-form-urlencoded (if using Postman), you need to set clientId to the Client ID you copied above.
Also in the Body under x-www-form-urlencoded (if using Postman), you need to set clientSecret to the Client Secret you copied above.
Send the request. In response, you will receive an accessToken. Copy this and use it in the next step.
In your GraphQL API interaction tool of choice (e.g. Postman), you can set Authorization to Bearer Token and paste the accessToken.
Now you can authenticate in the API and start making requests.

How to leverage the accessToken to make API calls:

All API interactions (other than receiving your accessToken) will be a POST request type to sdp.tealbook.com/graphql.
In the GraphQL API interaction tool of choice (e.g. Postman), open a new tab and set Authorization to Bearer Token. Paste your accessToken. Now you can authenticate in the API.
Start making API requests leveraging the subsequent sections of this documentation.
- Each request is made up of an operation (mutation or query) and query variables (specific aspects of the request that you can configure to control the output that is returned).

Glossary of Terms, Statuses, and Data Errors

Ambiguous Match: an ambiguous match represents the scenario where a match candidate is found that doesn't meet the threshold for a confident match, but is similar enough to the incoming supplier that a manual review is required to determine whether a match should be made.

Business Rules Engine (BRE): TealBook's Business Rules Engine is a mechanism that can be used to control the level of trust you want to have in a given attribute response, represented by a TealBook Trust Score.

Critical Error: an error that prevents a record from being processed. There are two types of critical errors: (1) system errors (there is an issue when processing a given record that is not necessarily related to the data itself and cannot be resolved by a user (e.g. runtime error). This type of error results in a Record Failed status) and (2) data errors (there is an issue with the data in a record that makes it ineligible for matching (e.g. missing supplier address). This type of error results in a Record Dropped status).

Supplier Data Platform (SDP): TealBook's supplier data enrichment platform.

Trust Score: most USP attributes in SDP are assigned a trust score (or will be eventually). This score indicates TealBook's confidence in the accuracy of the attribute information, based on all of the data sources used by TealBook to gather supplier data. Depending on the attribute, potential trust scores include Very Low, Low, Medium, High, and Very High. When an attribute does not yet have a trust score, this case is referred to as a Pending trust score.

Universal Supplier Profile (USP): a USP represents TealBook's master data record for a particular supplier. It is the published version of a supplier profile that we deem the most accurate based on the data we have at that given moment.

Enrichment Job Status Definitions

Pending: The enrichment job is undergoing initial processing/validation.

Processing: The enrichment job has started and records are being processed. Note that the job may require manual, or Human in the Loop (HIL), intervention as part of the enrichment process.

Completed: The enrichment job has been completed. This includes any HIL processes.

Failed: The enrichment job has failed and cannot be completed.

Record-Level Status Definitions

Status (Human-Readable Label)	Description
Record Failed *This is an end-state status for a record (i.e. the record is considered complete).	When a record has failed processing for any reason (e.g. system failure, time-out etc.). Records with this status would need to be resubmitted. They are not considered in the denominator of the match rate calculation.
Record Pending	When a record has been submitted but has not yet begun processing.
Record Processing	When a record is in a machine processing state; it has not yet been matched, no-matched, or reviewed by humans. Records with this status are not yet considered eligible for matching.
Manual Matching in Progress	When an incoming record falls within the threshold of an ambiguous match to 1 or more USP records, and is under review by TealBook’s human-in-the-loop (HIL) team. An ambiguous match represents the scenario where a match candidate is found that doesn't meet the threshold for a confident match, but is similar enough to the incoming supplier that a manual review is required to determine whether a match should be made.
Matched *This is an end-state status for a record (i.e. the record is considered complete).	When a single good match has been found.
Matched by Human Team *This is an end-state status for a record (i.e. the record is considered complete).	When a single good match has been found by TealBook's human-in-the-loop team.
No Match Found *This is an end-state status for a record (i.e. the record is considered complete).	When a record is confidently deemed to have ‘no match’ to an existing USP, either via automatic processing or human-in-the-loop selection.
Dropped from Processing *This is an end-state status for a record (i.e. the record is considered complete).	When a record has 1+ unresolvable critical data errors that prevent it from being processed. Records with this status are not considered in the denominator of the final match rate calculation.

Unmatched Reason Definitions

While an enrichment job is processing and once it has completed, a request can be made to receive the list of unmatched records from a given pipeline_id. More information on how to make this request can be found here.

There are 4 reason types for unmatched records. These include:

No Match Found: we processed the record and attempted to match it to a USP via automated processes, manual matching, or both, but were unable to find a matching USP in our database.
Duplicate Record: this record was an exact duplicate of another record in the same enrichment job, and was therefore removed. An exact duplicate record is identical to at least 1 other record across all fields submitted in the same job.
Record Dropped: this record had at least 1 critical data error that prevented the record from being successfully processed or eligible for matching. More information on data errors can be found in Data Error Definitions below.
Record Failed: this record failed due to some system error unrelated to the data itself. It can be resubmitted to try again.

Data Error Definitions

Data errors include:

Blank in a required field: there is a blank in 1 or more of the required fields for a given record. The required fields include company name, address, and internal supplier ID.
- If it is company name and/or the internal supplier ID that is missing, this type of error will surface in the unmatched response as: “Record is missing values in the mandatory [Missing Attribute] field."
- If it is address that is missing, across both the complete and parsed address fields, this type of error will surface in the unmatched response as: “Record must have either a complete address or a combination of street address, city, and country.”
Invalid complete address: complete address could not be parsed and/or is missing required fields of city, country, and address line.
- This type of error will be surfaced in the unmatched response as: “Supplier missing minimum required fields: supplier_name and address.”
Invalid address component: a value in any of the city, state/province, country, and/or street address fields is >255 characters.
- This type of error will be surfaced in the unmatched response as: “Invalid value detected in [field name] field. This field has a limit of ⇐255 characters.”

Note: If both the complete address and parsed address fields have been populated for a given record, the data in the complete address field will be taken by default.

Metric Definitions

Metrics can be evaluated for a given pipeline ID. These metrics can be retrieved using the allRecordStats query or they can be viewed on the dashboard page of the SDP User Console.

Metrics available today include counts and percentages of records within the following statuses (at either the aggregate-level or for an individual job):

Total Records Submitted: the number of records you submitted, whether via API or file upload.
Eligible for Matching: the number/proportion of records that are eligible for matching are those that have:
- Finished processing
- Not failed due to system error,
- Not been removed due to being an exact duplicate of another record, and
- Not been dropped from processing due to critical data errors.
Duplicates Removed: the number/proportion of exact duplicates (identical records across all attributes submitted) removed.
Matched (of eligible): the number/proportion of records that we were able to find a match for in our database (of eligible records).
No Match Found (of eligible): the number/proportion of records that we were unable to find a match for in our database (of eligible records).
Dropped Due to Data Error: the number/proportion of records that were dropped from processing due to critical data errors.
Processing: the number/proportion of records that are undergoing automatic processing. These records have not yet been matched, no-matched, or reviewed by humans.
Manual Matching: the number/proportion of records that are undergoing manual matching by TealBook
Failed: the number/proportion of records that failed to process due to system error, such as a runtime error.

Data Attribute Dictionary

Please note that this is a living document and is subject to change.

Data Attribute	Attribute Name (JSON)	Has Trust Score?	Description	Standard Format	Example	Significance and Value
Name	company_name	Yes	The official, legally registered name of the business or entity. This name is used for all legal, financial, and commercial purposes and serves as a unique identifier within the business ecosystem. The business or entity name may include legal designations such as "LLC," "Inc.," "Ltd.," or "Corp."	string	Office Depot	To uniquely identify the supplier and establish a recognizable reference for procurement and business interactions.
Supplier Address	company_address	Yes	The physical location associated with the supplier. This includes the street address, city, state or province, postal code, and country. It provides a tangible reference to the supplier's operational base and facilitates communication and logistics.	list of strings	6600 North Military Trail, Boca Raton, FL, 33496, United States	To send correspondence, invoices, and shipments. Verifying the supplier's location and jurisdiction.
Domain	web_domain	Yes	The website domain or online address associated with the business or entity. It provides a direct link to the organization's online presence, where customers, partners, and stakeholders can access information, products, and services.	URL	www.officedepot.com	To visit the supplier's website for information and contact details. Verifying the online presence and legitimacy of the supplier.
Annual Revenue	annual_revenue_number annual_revenue_currency	Yes	The total income generated by the business or entity within a specific fiscal year. This financial metric provides insights into the company's size, financial health, and overall performance.	numeric (ranges)	Office Depot: $1B-$10B	To gauge the financial health and stability of the supplier, helping procurement professionals assess the supplier's capacity for sustained business operations.
Year Founded	year_founded	Yes	The specific year in which the business or entity was originally established and officially began its operations. This attribute provides valuable historical context, offering insights into the business's longevity and experience in its industry. In some cases, this attribute might also be referred to as "Year Established" or "Incorporation Year," and it is typically associated with a specific date in history that marks the business's inception.	numeric (4 digits)	1979	To evaluate the supplier's history, experience, and longevity. Assessing the supplier's stability and industry expertise.
Employee Count	employee_count	Yes	The total number of individuals employed by the business or entity. In some cases, this attribute might also be referred to as "Headcount" or "Employees".	numeric (ranges)	Office Depot: 10K-50K	To understand the size and scale of the supplier's workforce, providing insights into its capacity, capabilities, and potential for scalability.
Description (Long)	description	Not at this time	This includes the long textual representation providing information about the business, its products, services, and other relevant details. The long description typically offers comprehensive insights. These descriptions are valuable for introducing the business to clients, partners, and stakeholders, aiding in decision-making and relationship-building.	string	“The Office Depot Corporation is an American office supply holding company headquartered in Boca Raton, Florida. The company operates 1,400 retail stores, e-commerce sites and a business-to-business sales organization. The company's portfolio of brands includes OfficeDepot, OfficeMax, Grand & Toy, ODP Business Solutions, Ativa, TUL, Foray, Realspace, and DiVOGA…”	To gain a comprehensive understanding of the supplier's offerings, capabilities, and unique value proposition, aiding in the evaluation of suitability for specific procurement needs.
Cert Issue Date	cert_issue_date	Yes (1 trust score for the whole Certification, not each sub-attribute)	The date when the certificate was officially issued to the business or entity. It marks the beginning of the certificate's validity period and is a critical reference point for tracking compliance and expiration.	date (YYYY/MM/DD)	2023/09/02	To understand when a supplier became certified. This information is valuable for historical reporting, providing insights into the supplier's certification timeline for reporting purposes.
Cert Expiration Date	cert_expiration_date	Yes (1 trust score for the whole Certification, not each sub-attribute)	The date when the certificate is set to expire. It indicates the end of the certificate's validity and highlights the need for renewal or recertification.	date (YYYY/MM/DD)	2023/09/02	To understand when a supplier's certification will expire. This information is crucial for proactively engaging with suppliers, allowing timely re-certification processes to maintain compliance and quality standards.
Cert Number	cert_number	Yes (1 trust score for the whole Certification, not each sub-attribute)	The unique identification number associated with the certificate. It serves as a reference point for verifying the certificate's authenticity and status.	alphanumeric	P-20456	To uniquely identify and verify the supplier's certifications.
Certifying Body	certifying_body	Yes (1 trust score for the whole Certification, not each sub-attribute)	The organization or authority responsible for certifying or issuing the certificate. It ensures that the certification process adheres to industry or regulatory standards, offering credibility and trust in the certification.	alphanumeric	Cal eProcure	To understand the authority or organization endorsing the supplier's certifications, providing insights into the credibility of the certifications.
Certification Domain	cert_domain	Yes (1 trust score for the whole Certification, not each sub-attribute)	A direct link to the certificate or the certification authority.	URL	https://web.sba.gov/pro-net/search/dsp_dsbs.cfm	To establish a direct link to the source of the certification data for auditability.
Certification Source Type	cert_type	Yes (1 trust score for the whole Certification, not each sub-attribute)	The type of source from which the certification was retrieved. Right now, the only available option is Authorized, meaning the certification comes from an official certification source.	string	Authorized	To understand the type of source that the certification came from. This can be useful in customizing source types that you want to count towards qualified spend versus those you do not.
Certification Category	cert_category	Yes (1 trust score for the whole Certification, not each sub-attribute)	The general category or type of the certificate, such as "Diversity," "Quality," "Information Security," "Social Responsibility and Sustainability," or "Food." It categorizes the certification within a broader theme.	string	Diversity	To understand the broad category within which a certification falls, which could be leveraged for reporting.
Certification Sub-Category	cert_subcategory	Yes (1 trust score for the whole Certification, not each sub-attribute)	References the specific certifications available under each primary category. These subcategories allow for a more granular classification of certifications, aiding clients in precise discovery and filtering. Examples of subcategories include "MBE" (Minority-owned Business Enterprise), "SBE" (Small Business Enterprise), "WBE" (Women-owned Business Enterprise), etc.	string	Small Business	To understand the more specific subcategory that a certification falls under, which could be leveraged for reporting.
Certification Sub-Type	cert_subtype	Yes (1 trust score for the whole Certification, not each sub-attribute)	A more specific sub-category within the certificate type. It delineates various certifications available under each category. There are a few subtypes that are names of certifying agencies (e.g., SME Climate Hub, Rainforest Alliance), but for the most part subtypes are subsets of a subcategory (e.g., Forest Management is a subtype of the Environment subcategory).	string	SME Climate Hub	To further refine and specify the subtype of certifications, allowing for a more granular assessment of the supplier's compliance within a particular category.
Phone Number	phone_number	Not at this time	The telephone contact number for the business or entity. It provides a direct communication channel for clients, partners, and stakeholders to reach the organization.	alphanumeric	+1(509) 703-7714 +1(509) 703-7714x6541	To establish direct communication with the supplier, facilitating inquiries, and maintaining contact for operational and contractual purposes.
Legal Structure	legal_structure	Not at this time	The formal legal classification or framework under which the business operates. This attribute describes whether the business is structured as a sole proprietorship, partnership, corporation, limited liability company (LLC), or another legally recognized form. The legal structure affects aspects such as ownership, liability, and taxation.	string	LLC	To understand the legal form of the supplier's organization, providing insights into its governance, compliance, and operational structure.
Fax	fax_number	Not at this time	The facsimile contact number for the business or entity.	alphanumeric	509-703-7716	An additional communication channel for official documents and correspondence.
Ownership	ownership	Not at this time	Information about who owns or controls the business, whether it's publicly traded, or privately owned.	string	Private Public	To identify and understand the ownership structure of the supplier, providing insights into its governance, decision-making, and potential affiliations.
Contact Person	contact_name	Not at this time	The name of the person to contact for inquiries or business matters.	string	Contact: Mirthea Rojas	To establish a point of contact for inquiries, providing clarity on who to communicate with regarding procurement matters.
Contact Title	contact_title	Not at this time	The job title of the person to contact for inquiries or business matters.	string	Title: Manager	To establish a point of contact for inquiries, providing clarity on who to communicate with regarding procurement matters.
Contact Email	contact_email	Not at this time	The primary email address for a key contact person at the supplier.	email	paul.viveiros@evoqua.com	To establish a point of contact for inquiries, providing clarity on who to communicate with regarding procurement matters.
Contact Phone	contact_phone_number	Not at this time	The primary phone number for a key contact person at the supplier.	alphanumeric	+1(509) 703-7714 +1(509) 703-7714x6541	To establish a point of contact for inquiries, providing clarity on who to communicate with regarding procurement matters.
Location Type	location_type	Not at this time	Describes the type of physical location, such as headquarters, branch office, or a single store.	string	Branch HQ	To categorize the type of location where the supplier operates, such as headquarters, or branch office, aiding in logistical considerations
Net Income	net_income	Not at this time	The profit earned by the business after deducting all expenses and taxes from its total revenue.	numeric	$63,545	To assess the supplier's profitability, providing insights into its financial health and stability.
Gross Profit	gross_profit	Not at this time	The difference between a business's total revenue and the cost of goods sold. It indicates the profit generated from the core business activities before accounting for operating expenses.	numeric	$93,545	To evaluate the supplier's profitability before considering operating expenses, aiding in a comprehensive financial analysis.
Operating Income	operating_income	Not at this time	The income generated from the business's day-to-day operational activities after accounting for operating expenses. It is a significant financial metric that reflects the business's ability to generate profit from its core operations.	numeric	$43,545	To understand the supplier's profitability from its core operations, excluding non-operational income and expenses.
Total Assets	total_assets	Not at this time	The combined value of all the assets owned by the business, including cash, property, equipment, and investments. It provides insight into the business's total worth.	numeric	$103,545	To gauge the overall value of the supplier's assets, providing insights into its financial strength and capacity.
Total Liabilities	total_liabilities	Not at this time	The combined value of all the debts and financial obligations of the business. It reflects the business's financial obligations and the funds required to settle them.	numeric	$61,545	To understand the supplier's total financial obligations, contributing to an assessment of its financial health and risk.
Local Exchange Symbol	local_exchange_symbol	Not at this time	The symbol used to identify the business on a local stock exchange if applicable, e.g., stock ticker symbol.	string	COST:NASDAQ	To uniquely identify the supplier on a local exchange, facilitating financial analysis.
Tax ID	tax_id	Not at this time	A unique numerical identifier assigned to a business or entity by the tax authorities. It is used for tax reporting and compliance purposes, including filing tax returns and withholding taxes.	alphanumeric	EIN: 123-45-6789 BN: 12345679	To uniquely identify the supplier for taxation purposes, facilitating compliance and financial transactions.
CAGE Code	cage_code	Not at this time	A unique identifier assigned to businesses that contract with the U.S. government. It is used to track and manage government contracts, grants, and agreements.	alphanumeric (5 characters)	1234A	To uniquely identify the supplier for government contracting and procurement activities, ensuring accurate and standardized identification.
SAM UEI	sam_uei	Not at this time	An identification number associated with businesses registered in the U.S. System for Award Management (SAM). SAM is a federal database that stores information about entities doing business with the U.S. government.	alphanumeric (12 characters)	7798WER47798	To uniquely identify the supplier within the System for Award Management (SAM), facilitating government procurement and compliance.
DUNS Number	duns_number	Not at this time	A unique nine-digit identifier assigned to businesses by Dun & Bradstreet. It is widely used for credit reporting, supplier evaluation, and business risk assessment.	numeric (9 digits)	00-123-4567 001234567	To uniquely identify the supplier in the Dun & Bradstreet database, aiding in credit assessments and business information verification.
LEI	lei	Not at this time	A global identifier for legal entities engaging in financial transactions. It is used to improve transparency and risk management in financial markets by providing a standardized way to identify organizations.	alphanumeric (20 characters)	549300 84UKLVMY22DS16	To uniquely identify the supplier in the Legal Entity Identifier system, ensuring transparency and traceability for regulatory compliance.
NAICS Code	naics	Not at this time	A standardized classification system used to categorize North American businesses based on their primary industry. It can be either 2, 4, or 6 digits in length, with each group of 2 digits providing increased specificity. The first 2 digits represent the broad industry sector, the first 4 digits offer a more detailed industry group, and the full 6 digits provide a highly specific industry description. The NAICS code facilitates uniform data collection and analysis across industries, allowing for effective comparison and classification of businesses within the North American economy.	numeric (array) Including: 2, 4, 6 digits	11 3456 541611	To categorize the supplier into a standardized industry classification, aiding in industry-specific analysis and reporting.
SIC	sic	Not at this time	A historical system used for classifying businesses into industry categories based on their primary activities. While it has largely been replaced by NAICS codes, it is still referenced for certain applications and historical data analysis.	numeric (array) Including: 2, 4 digits	01 4226	To categorize the supplier into a Standard Industrial Classification, providing a historical classification system for industry analysis.

Certifications Legend

Qualification (Category)	Subcategory	Acronym
Diversity	Small Business Enterprise	SBE
Diversity	Minority-owned Business Enterprise	MBE
Diversity	Women-owned Business Enterprise	WBE
Diversity	Small Disadvantaged Business	SDB
Diversity	Disadvantaged Business	DBE
Diversity	Veteran-owned Business Enterprise	VBE
Diversity	Historically Underutilized Business Zones	HUB
Diversity	Service-Disabled Veteran Business Enterprise	SDVBE
Diversity	Certified Aboriginal Business	CAB
Diversity	U.S. Department of Housing and Urban Development	HUD
Diversity	Disabled Veteran Business Enterprise	DVBE
Diversity	Certified Benefit Corporation	BCORP
Diversity	LGBT-owned Business Enterprise	LGBTBE
Diversity	People with Disabilities	PWD
Diversity	Alaskan Native Corporations and Indian Tribes	ANCIT
Diversity	Labour Surplus Area	LSA
Diversity	Historically Black Colleges and Universities	HBCU
Diversity	Women-led Business Enterprise	WLE

Understanding Supplier Enrichment

TealBook Supplier Enrichment enhances your existing supplier data (such as your ERP vendor master file), providing you with enriched and trusted supplier data for your procurement systems and decision-making.

TealBook enriches your supplier data by:

Verifying and recommending supplier information (such as the supplier’s website and address).
Adding missing supplier data (such as the supplier’s annual revenue and number of employees).
Adding diversity certification details (including the certification type, issue date, and expiry date).

SDP provides trust scores for many supplier attributes, including supplier diversity certifications, giving you visibility into the confidence of the data.

Supplier Enrichment Process

The following diagram illustrates the steps in the Supplier Enrichment process. To initiate this process, submit your supplier data using the inputVmData mutation or upload your vendor master file via the SDP User Console.

Step 1: Submit Your Supplier Data

Use the inputVmData Mutation to send your supplier data (such as your SAP vendor master file) to SDP. This request triggers the Supplier Enrichment process.

Alternatively, you can upload your vendor master file via the SDP User Console.

Step 2: SDP Verifies the Supplier Data

SDP inspects the submitted supplier data and flags any errors, such as missing required fields or invalid data (such as a Complete Address that only contains a city).

Records with these kinds of critical data errors are not processed further, but can be requested as part of the retrieveUnmatchedRecords Query.

Step 3: SDP Looks for Supplier Matches

SDP checks for matches between the suppliers in your submitted supplier data and the supplier profiles (aka USPs) in the SDP supplier database.

Step 4: TealBook Resolves Ambiguous Matches

The TealBook HIL team reviews any uncertain supplier matches to determine if the match is valid (or which match is valid, in the case of multiple potential matches). Each ambiguous match is either confirmed (as a confident match) or rejected (as a confident no-match).

Step 5: SDP Enriches Your Supplier Profiles

For each supplier that TealBook is able to match, SDP enriches the supplier's profile by making recommendations corresponding to your configured business rules, potentially adding supplemental supplier data and diversity certification details.

Supplier data enrichments are based on the business rules configured for your account. It's important to note that your organization's BRE configuration takes precedence over API requests. For example, if you configure your business rules to ‘Never’ receive data for a specific attribute, such as NAICS, then even if you make an API call requesting data for a handful of attributes including NAICS, you will not receive any TealBook NAICS data in the merged_value response (because according to your BRE configuration, you never want to receive data for the NAICS attribute).

SDP provides a trust score for many enriched supplier attributes and for each supplier diversity certification, giving you visibility into the confidence of the data.

Step 6: Retrieve Your Enriched Supplier Data

Run a pipelineStats Query to determine if the enriched supplier data is ready*, then use the retrieveMatchedRecords Query to get the results. You can now use this enriched supplier data to update your supplier data in your destination system.

*Note that in SDP, your data is processed record-by-record. This means that you do not have to wait for the entire enrichment job to reach Complete status before you begin retrieving enriched supplier data.

SDP API Process

The TealBook Integration APIs enable platform-to-platform communication between your procurement platform and the TealBook Supplier Data Platform (SDP).

Supplier Enrichment APIs

Use the Supplier Enrichment APIs to submit your supplier data for enrichment, poll the status of the subsequent enrichment job, and retrieve enriched supplier profiles when processing is complete. All of these actions require a POST request type to sdp.tealbook.com/graphql.

The APIs accept supplier information and return enriched profile information for each supplier TealBook is able to match. The data TealBook returns depends on the Business Rule Engine (BRE) configurations for your organization. TealBook will return the best match based on the provided information.

This is an asynchronous API pattern. The request is posted for processing and an identifier (pipeline_id) is returned that can be used to check the status of your request. Processing can take as little as a few minutes to up to 48 hours, depending on how long it takes to find a supplier match. That said, your data is processed record-by-record, so you can start to request matched and enriched output before the status of the pipeline_id as a whole is complete.

The APIs used in the Supplier Enrichment process are described in the following sections.

Step 1: Submit an Enrichment Request

POST: sdp.tealbook.com/graphql ; inputVmData Mutation

Create a Supplier Enrichment request by submitting a list of supplier records. This request results in the creation of a pipeline_id which is used to identify and perform queries related to this specific enrichment job.

GRAPHQL

graphql

Select...
mutation InputVmData($data: [VendorMasterInput!]!) {
 inputVmData(data: $data) {
   result
   pipelineId
 }
}

Example Query Variables:

GRAPHQL

graphql

Select...
{"data": [
   {"company_name":"ACME INC.","internal_supplier_id":"123456","street_address":"ONE ACME WAY","country":"United States","state":"TEXAS","city":"Round Rock","zip_postal_code":"78682"},
   {"company_name":"Spongebob Inc.","internal_supplier_id":"456789","complete_address":"355 Pineapple Dr #3306, Bikini Bottom, TX 75074, USA"},
   {"company_name":"Sheldon Cooper LLC","internal_supplier_id":"987654","complete_address":"2001 Big Bang St, San Francisco, CA 94115, USA"}]
}

GRAPHQL

graphql

Select...
{
	“data:” {
		“inputVmData”: {
			“result”: “Enrichment Request has been received.”,
			“pipelineId”: e6e9c141-39dc-44ff-b251-ga7e5218131b”
		}
	}
}

Step 2: Poll Enrichment Job

Use the following APIs to retrieve your Enrichment Job resources and check the resource status.

Fetch the Status of an Enrichment Job

POST sdp.tealbook.com/graphql ; pipelineStats Query

To retrieve the status of an Enrichment Job, provide the pipeline_id as the filter. To retrieve just the status, use the status node. Other available nodes include id (the pipeline_id for this job), cumulative_match_rate (the current match rate for this job, based on the records that have been processed thus far), total_records (the number of records submitted as part of this job), created_by (the same of the user that created the job), and created_at (the date and time that the job was created). The response depends on the nodes that you include in your query, where the status indicates the job's progress in the Supplier Enrichment process.

Possible statuses are:

Pending: The enrichment job is undergoing initial processing/validation.
Processing: The enrichment job has started and records are being processed. Note that the job may require Human in the Loop (HIL) intervention as part of the enrichment process.
Completed: The enrichment job has been completed. This includes any HIL processes.
Failed: The enrichment job has failed and cannot be completed.

GRAPHQL

graphql

Select...
query pipelineStats($paging: PageOptionsDto, $filter: PipelinesFilterBy, $order: PipelineOrderBy) {
   pipelineStats(paging: $paging, filter: $filter, order: $order) {
       nodes {
           id
           source_name
           status
           cumulative_match_rate
           total_records
           created_by
           created_at
       }
       pageInfo {
           page
           offset
           limit
           itemCount
       }
   }
}

GRAPHQL

graphql

Select...
{"filter": {
    "pipeline_id": "e6e9c141-39dc-44ff-b251-ga7e5218131b"}
 }

GRAPHQL

graphql

Select...
{
   "data": {
       "pipelineStats": {
           "nodes": [
               {
                   "id": "f7e97519-e260-4fed-8186-93715265a9d6",
                   "source_name": "Tealbook",
                   "status": "Processing",
                   "cumulative_match_rate": 56.908212560386474,
                   "total_records": 4238,
                   "created_by": "sheldon.cooper@tealbook.com",
                   "created_at": "2024-01-12T15:18:41.737Z"
               }
           ],
           "pageInfo": {
               "page": 1,
               "offset": 0,
               "limit": 10,
               "itemCount": 1
           }
       }
   }
}

Fetch Record-Level Statuses and Metrics for an Enrichment Job

POST sdp.tealbook.com/graphql ; allRecordStats Query

This query can be used to retrieve the point-in-time count of records within each record-level status for a specific enrichment request using the pipeline_id as the query filter. Requesting the available metrics will provide an at-a-glance view of the counts and percentages of records within each status at the time the query is run.

GRAPHQL

graphql

Select...
query allRecordStats($filter: PipelinesFilterBy) {
  allRecordStats(filter: $filter) {
          number_of_records
          number_of_records_eligible_for_matching
          number_of_records_matched
          records_matched_percentage
      }
  }

GRAPHQL

graphql

Select...
{"filter": {
    "pipeline_id": "e6e9c141-39dc-44ff-b251-ga7e5218131b"}
 }

GRAPHQL

graphql

Select...
{
   "data": {
       "allRecordStats": {
           "number_of_records": 4238,
           "number_of_records_eligible_for_matching": 3681,
           "number_of_records_matched": 2061,
           "records_matched_percentage": 56
       }
   }
}

Step 3: Retrieve Enriched Supplier Profiles

Fetch Matched and Enriched Records for an Enrichment Job

POST sdp.tealbook.com/graphql ; retrieveMatchedRecords Query

To retrieve a list of the enriched supplier profiles for an Enrichment Job resource, provide the pipeline_id as the query variable. The response includes enriched profile information for each supplier that SDP is able to match. Results are returned incrementally as supplier profiles are matched and enriched. When the job is complete as a whole, the pipeline_id status will be Complete.

The supplier data is enriched based on the business rules configured for your account. SDP provides a trust score for many enriched supplier attributes and for each supplier diversity certification, giving you visibility into the accuracy of the data.

GRAPHQL

graphql

Select...
query retrieveMatchedRecords($pipeline_id: String!) {
 retrieveMatchedRecords(pipeline_id: $pipeline_id) {
  fields {
    company_name {
        client_value
        merged_source
        merged_value
        tealbook_value
        tealBook_trust_score
    }
   company_address {
       client_value
       merged_source
       merged_value
       tealBook_trust_score
       tealbook_value
   }
   naics {
    client_value
       merged_source
       merged_value
       tealBook_trust_score
       tealbook_value
   }
  }
  internal_supplier_id_or_vendor_number
 }
}

GRAPHQL

graphql

Select...
{"pipeline_id": "e6e9c141-39dc-44ff-b251-ga7e5218131b"}

GRAPHQL

graphql

Select...
{
    "data": {
        "retrieveMatchedRecords": [
            {
                "fields": {
                    "company_name": [
                        {
                            "client_value": "ACME INC.",
                            "merged_source": "Tealbook",
                            "merged_value": "ACME Incorporated",
                            "tealbook_value": "ACME Incorporated",
                            "tealBook_trust_score": "HIGH"
                        }
                    ],
                    "company_address": [
                        {
                            "client_value": "ONE ACME WAY, Round Rock, TX 78682, USA",
                            "merged_source": “Tealbook”,
                            "merged_value": “1 ACME Way, Round Rock, TX 78682, USA”,
                            "tealBook_trust_score": "HIGH",
                            "tealbook_value": “1 ACME Way, Round Rock, TX 78682, USA”,
                        }
                    ],
                    "naics": [
                        {
                            "client_value": "null",
                            "merged_source": Tealbook,
                            "merged_value": 336111,
                            "tealBook_trust_score": "MEDIUM",
                            "tealbook_value": 336111
                        }
                    ],
                },
                "internal_supplier_id_or_vendor_number": "123456"
            },
            {
                "fields": {
                    "company_name": [
                        {
                            "client_value": "Spongebob, Inc.",
                            "merged_source": "Tealbook",
                            "merged_value": "Spongebob, Inc.",
                            "tealbook_value": "Spongebob, Inc.",
                            "tealBook_trust_score": "HIGH"
                        }
                    ],
                    "company_address": [
                        {
                            "client_value": "355 Pineapple Dr #3306, Bikini Bottom, TX 75074, USA",
                            "merged_source": “Tealbook”,
                            "merged_value": "355 Pineapple Dr #3308, Bikini Bottom, TX 75074, USA",
                            "tealBook_trust_score": "HIGH",
                            "tealbook_value": "355 Pineapple Dr #3308, Bikini Bottom, TX 75074, USA"
                        }
                    ],
                    "naics": [
                        {
                            "client_value": "null",
                            "merged_source": “Tealbook”,
                            "merged_value": "483111",
                            "tealBook_trust_score": "HIGH",
                            "tealbook_value": "483111"
                        }
                    ],
                },
                "internal_supplier_id_or_vendor_number": "456789"
            }
        ]
    }
}

Fetch Unmatched Records for an Enrichment Job

POST sdp.tealbook.com/graphql ; retrieveUnmatchedRecords Query

This query can be used to retrieve the records that were unable to be matched for a given pipeline_id, including reasons why they were unable to be matched.

GRAPHQL

graphql

Select...
query RetrieveUnmatchedRecords($pipeline_id: String!) {
 RetrieveUnmatchedRecords(pipeline_id: $pipeline_id) {
   UnmatchedReason
   errors {
       msg
   }
   company_name
   complete_address
   internal_supplier_id
 }
}

GRAPHQL

graphql

Select...
{"pipeline_id": "e6e9c141-39dc-44ff-b251-ga7e5218131b"}

GRAPHQL

graphql

Select...
{
   "data": {
       "RetrieveUnmatchedRecords": [
           {
               "UnmatchedReason": "No Match Found",
               "errors": [
                   {
                       "msg": "We did not find a match for this record in our database."
                   }
               ],
               "company_name": "Sheldon Cooper",
               "complete_address": "2001 Big Bang St, San Francisco, CA 94115, USA",
               "internal_supplier_id": "987654"
           }
       ]
   }
}

Fetch Original Records for an Enrichment Job

POST /graphql ; retrieveOriginalRecords Query

This query can be used to retrieve the original supplier data you submitted to a given pipeline_id. The available nodes are the same as the data attributes available for the inputVmData mutation.

GRAPHQL

graphql

Select...
query retrieveOriginalRecords($pipeline_id: String!) {
retrieveOriginalRecords(pipeline_id: $pipeline_id) {
  company_name
  complete_address
  internal_supplier_id
}
}

GRAPHQL

graphql

Select...
{"pipeline_id": "e6e9c141-39dc-44ff-b251-ga7e5218131b"}

GRAPHQL

graphql

Select...
{
   "data": {
       "retrieveOriginalRecords": [
           {
               "company_name": "ACME INC.",
               "complete_address": null,
               "internal_supplier_id": "123456"
           },
           {
               "company_name": "Spongebob Inc.",
               "complete_address": "355 Pineapple Dr #3306, Bikini Bottom, TX 75074, USA",
               "internal_supplier_id": "456789"
           },
           {
               "company_name": "Sheldon Cooper LLC",
               "complete_address": "2001 Big Bang St, San Francisco, CA 94115, USA",
               "internal_supplier_id": "987654"
           }
       ]
   }
}

Error Handling

Select...
{
  "errors": [
    {
      "error_code": "example",
      "message": "example",
      "path": [
        "example",
      ]
      "detailed_message": "example example example"
    }
  ],
  "data": null
}

Within this response, error_code and message will always be returned. path and detailed_message are optional and will only be returned in specific instances.

There are a number of different error codes that you may run into, including:

Status Response	Error Code	Description	Possible Messages	Possible Detailed Messages
200	UNAUTHORIZED_EXCEPTION	When a user attempts to run an operation with invalid/outdated credentials.	The access token has not been provided or it has expired. Please refresh your access token and try again. or API Credentials don't exist. Please try again.	N/A
200	FORBIDDEN	When a user attempts to access an API without the sufficient permissions to access that API.	You do not have permissions to run this API. If you believe you should have permissions, please reach out to support@tealbook.com for assistance.	N/A
200	INVALID_ARGUMENT	When a user provides an invalid value for a field argument.	Provided an invalid value for a field argument.	N/A
200	MISSING_INPUT	When a request is missing required fields (i.e. internal supplier ID, company name, and/or complete address or parsed address components for the inputVmData mutation).	The request is missing the required field(s) {{field}}.	The request is missing the required field(s) {{fields}}. Please add the missing field(s) to your request and try again.
200	OPERATION_NOT_PROVIDED	When a request was parsed successfully and is valid against the server’s schema, but the server couldn’t resolve which operation to run. Occurs when a request containing multiple named operations doesn’t specify which operation to run, or if the named operation isn’t included in the request.	Operation not provided.	The request contains multiple named operations but does not specify which operation to run. Please specify the operation name in the request.
400	SYNTAX_ERROR	When a request string contains a syntax error.	Depends on the specific error.	The request string contains a syntax error. Please check the syntax and try again.
400	OBJECT_SCHEMA_VALIDATION_FAILED	When the object failed validation against the server's schema.	The object failed validation against the server's schema.	The object failed validation against the server's schema. Please review the request and ensure it complies with the schema.
400	PRE_PARSE_ERROR	An error that occurs before the server could attempt to parse the given GraphQL operation.	Error before parsing.	An error occurred before the server could attempt to parse the given GraphQL operation. Please check the request and try again.
400	BATCH_REQUEST_NOT_ALLOWED	When a user attempts to send a batched HTTP request when allowBatchedHttpRequests isn't enabled.	Batched request not allowed.	The server does not allow batched HTTP requests. Please send individual requests instead.
400	CSRF_PREVENTION_ERROR	When CSRF prevention blocks a request.	CSRF prevention error.	The request was blocked due to CSRF prevention measures. Please ensure that your request includes the necessary CSRF token.
405	METHOD_NOT_ALLOWED	When a request uses an invalid HTTP method (GET with a mutation, or any HTTP method other than GET or POST), then Apollo Server responds with a 405 status code	The HTTP method used is not allowed for this operation. Please check the documentation for the correct method.
500	INTERNAL_SERVER_ERROR	May occur: If the Server hasn't correctly started up or is in the process of shutting down. If the context function throws. If there is an unexpected error during the processing of the request (either a bug in the Server or a plugin hook throws).	Internal server error	Something went wrong on our end. We're sorry for the inconvenience. Please try again later or contact support@tealbook.com if the issue persists.

Query

The Query type in GraphQL represents the entry point for retrieving data from the API. It defines the available read-only operations (queries) that clients can execute to fetch data.

Mutation

The Mutation type in GraphQL is used for modifying or creating data. It defines the operations (mutations) that allow clients to make changes to the data stored on the server, such as creating, updating, or deleting resources

Objects

Objects in GraphQL represent complex data structures. They define the fields and their types that can be queried in a GraphQL API. Objects can have nested fields and relationships with other objects.

Scalars

Scalars: Scalars in GraphQL represent primitive data types, such as String, Int, Boolean, Float, etc. They are used to define the types of individual fields in the GraphQL schema.

Enums

Enums in GraphQL define a set of possible values for a field. They represent a discrete set of options or states that a field can have. Enums help ensure type safety and provide a clear list of valid values for a field.

Sections

API Reference

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

What made this section unhelpful for you?

Introduction to SDP

What made this section unhelpful for you?

Accessing the APIs

Step-by-Step Process:

How to leverage the accessToken to make API calls:

What made this section unhelpful for you?

Glossary of Terms, Statuses, and Data Errors

Enrichment Job Status Definitions

Record-Level Status Definitions

Unmatched Reason Definitions

Data Error Definitions

Metric Definitions

What made this section unhelpful for you?

Data Attribute Dictionary

Certifications Legend

What made this section unhelpful for you?

Understanding Supplier Enrichment

Supplier Enrichment Process

Step 1: Submit Your Supplier Data

Step 2: SDP Verifies the Supplier Data

Step 3: SDP Looks for Supplier Matches

Step 4: TealBook Resolves Ambiguous Matches

Step 5: SDP Enriches Your Supplier Profiles

Step 6: Retrieve Your Enriched Supplier Data

What made this section unhelpful for you?

SDP API Process

Supplier Enrichment APIs

Step 1: Submit an Enrichment Request

Step 2: Poll Enrichment Job

Step 3: Retrieve Enriched Supplier Profiles

What made this section unhelpful for you?

Error Handling

What made this section unhelpful for you?

Query

Mutation

Objects

Scalars

Enums