Table of Contents
Summary
Whistic's Vendor Creation API allows you to programmatically add new vendors to your account using a structured, three-step workflow. This integration streamlines vendor onboarding by retrieving your organization's customized intake form template, understanding validation requirements, and submitting vendor information directly through API calls.
This article guides you through the complete workflow for creating vendors via API, from retrieving the form structure to successfully submitting vendor data.
Click the play button below (in the upper right corner) for a quick demo!
🔧 Before You Begin
Requirements:
- Valid API key (API Key Creation)
- Access to the Whistic swagger page (public.whistic.com)
- Understanding of your organization's vendor intake form structure
Important Notes:
- The vendor intake form structure is specific to your organization and may include custom fields
- All submissions are validated against your current form schema, including type-checking, format validation, and required field verification
- Field requirements (required vs. optional) are defined by your organization's form configuration
Related Documentation:
📋 Step 1: Retrieve the Vendor Intake Form Template
The first step is to retrieve the complete payload structure for your organization's vendor intake form.
Endpoint: GET /api/vendor-create/form
Purpose: This endpoint returns a complete example payload structure with all fields present but empty. The template shows the exact structure needed for vendor creation.
What You'll Receive:
- Complete payload structure with all available fields
- Standard fields (vendor name, URL, contact information, etc.)
- Custom fields configured for your organization
- Appropriate empty values for each field type:
- Strings as
"" - Numbers as
0 - Booleans as
false - Arrays as
[]
- Strings as
✅ Step 2: Get Validation Rules and Requirements
After retrieving the form template, get the validation rules to understand field requirements and constraints.
Endpoint: GET /api/vendor-create/schema
Purpose: This endpoint returns a JSON Schema that defines validation rules for the vendor intake form.
What You'll Receive:
- Field types (string, number, boolean, array, object)
- Required field indicators (
"required": true) - Validation constraints:
- Format requirements (email, phone, URL)
- Pattern matching rules
- Maximum and minimum length restrictions
- Enumerated values (dropdown options)
- Character limits
- Field descriptions and help text
- Format hints (e.g., email address format; phone number format)
Example Schema Elements:
Note: Review the schema carefully to ensure your data meets all validation requirements before submission. Pay special attention to:
- Which fields are marked as
"required": true - Maximum length constraints (
maxLength) - Enumerated values that must match exactly
- Format requirements for email addresses, phone numbers, and URLs
📝 Step 3: Prepare Your Vendor Data
Using the template from Step 1 and validation rules from Step 2, fill in your vendor information.
Key Sections to Complete:
Vendor Information (Required Section):
- Vendor Name
- Product/Service Name
- Vendor URL
- Type of Vendor (Current, Prospective, or Inactive)
- Description of the vendor/service
Vendor Primary Contact (Required Section):
- First Name and Last Name
- Email Address
- Phone Number (if required by your form)
- Job Title (if required by your form)
Requester/Business Sponsor Information:
- Contact details for the internal requester
- Job title and department information
Business Unit Information:
- Sponsoring Business Unit
- Vendor Criticality Level
Internal Systems & Data Classification:
- Systems or applications the vendor will access
- Data types the vendor will have access to
- Risk assessment questions (financial stability, data breaches, regulated functions)
Additional Information:
- Billing address details
- Payment information (contract value, payment cadence, payment method)
- Estimated number of users
Best Practices:
- Ensure all required fields are completed with valid data
- Verify email addresses and URLs follow the correct format
- Match enumerated values exactly as they appear in the schema
- Stay within maximum character limits for text fields
- Use the format hints provided in the schema for proper data formatting
🚀 Step 4: Submit the Vendor Creation Request
Once your payload is complete and validated against the schema, submit the vendor creation request.
Endpoint: POST /api/vendor-create
Request Body: Your completed payload from Step 3
Validation Process: The API automatically validates your submission against the current form schema, including:
- Type checking (ensuring strings, numbers, arrays match expected types)
- Format validation (email addresses, phone numbers, URLs)
- Required field verification
- Character length constraints
- Enumerated value matching
Successful Response: Upon successful creation, you'll receive confirmation with the newly created vendor's details.
Error Responses: If validation fails, you'll receive detailed error messages indicating:
- Which fields failed validation
- What validation rule was violated
- How to correct the issue
❓ FAQ
Do I need to call all three endpoints every time I create a vendor?
No. Once you've retrieved the form template (GET /api/vendor-create/form) and schema (GET /api/vendor-create/schema), you can reuse them for multiple vendor creation requests. However, if your organization updates the vendor intake form (adding or removing fields), you should retrieve the latest form template and schema to ensure compatibility.
What happens if my organization's vendor intake form changes?
If your organization modifies the vendor intake form structure or validation rules, previous templates and schemas may become outdated. We recommend periodically retrieving the latest form template and schema, especially if you receive validation errors on previously working payloads.
Can I see an example of a complete vendor creation payload?
Yes. The GET /api/vendor-create/form endpoint returns a complete example with all available fields. You can also reference your Swagger documentation for additional payload examples specific to your organization's configuration.
What validation errors might I encounter?
Common validation errors include:
- Missing required fields
- Incorrect data types (submitting a string where a number is expected)
- Invalid email or URL formats
- Exceeding maximum character limits
- Using values not included in enumerated options
- Incorrect phone number formatting
How do I know which fields are custom to my organization?
The form template and schema reflect your organization's specific configuration, including any custom fields. All fields returned in the template are available for your use—standard fields are consistent across all Whistic accounts, while custom fields are unique to your organization's setup.
Can I create vendors with partial information?
You must provide all fields marked as "required": true in the schema. Optional fields can be omitted or left empty. Review the schema from GET /api/vendor-create/schema to determine which fields are required for your organization.
What format should I use for phone numbers and email addresses?
The schema includes format hints for these fields. Email addresses should follow standard email format (user@example.com), and phone numbers should follow the format shown in the hint (e.g., +1-234-567-8900). The API validates these formats automatically.
Where can I find my organization's API credentials?
Contact your Whistic administrator or Account Manager for assistance with gathering an API key. Whistic Admins can retrieve an API key by going to Settings > Integrations > Whistic Public API.
What's the difference between the form template and the schema?
The form template (GET /api/vendor-create/form) shows the complete payload structure with empty values—it's your starting point for filling in data. The schema (GET /api/vendor-create/schema) provides the validation rules, requirements, and constraints for each field—it tells you how to properly fill in the template.