Vendors API

Manage vendor/distributor records for your organization.

Related API

This API manages vendor entity records (name, contact, address). For vendor API integration settings (credentials, testing), see Vendor Config API.

GET /api/v1/vendors

Returns a paginated list of vendors with optional filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`pageSize`	integer	20	Items per page (max 100)
`search`	string	null	Search by vendor name
`activeOnly`	boolean	true	Return only active vendors

Response (200 - Success)

{
    "success": true,
    "data": {
        "vendors": [
            {
                "id": 1,
                "name": "TD SYNNEX",
                "contactPerson": "John Smith",
                "address1": "44201 Nobel Drive",
                "city": "Fremont",
                "state": "CA",
                "postalCode": "94538",
                "country": "USA",
                "phone": "(800) 456-4822",
                "email": "[email protected]",
                "website": "https://www.tdsynnex.com",
                "notes": "Primary AV distributor",
                "isActive": true,
                "apiEnabled": true,
                "dateCreated": "2024-01-15T10:00:00Z",
                "dateUpdated": "2024-12-25T12:00:00Z"
            }
        ],
        "pagination": {
            "currentPage": 1,
            "pageSize": 20,
            "totalCount": 5,
            "totalPages": 1,
            "hasPrevious": false,
            "hasNext": false
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

GET /api/v1/vendors/{id}

Returns detailed information for a specific vendor.

Response (200 - Success)

{
    "success": true,
    "data": {
        "vendor": {
            "id": 1,
            "name": "TD SYNNEX",
            "contactPerson": "John Smith",
            "address1": "44201 Nobel Drive",
            "address2": "Building A",
            "city": "Fremont",
            "state": "CA",
            "postalCode": "94538",
            "country": "USA",
            "fullAddress": "44201 Nobel Drive\nBuilding A\nFremont, CA 94538\nUSA",
            "phone": "(800) 456-4822",
            "fax": "(800) 456-4823",
            "email": "[email protected]",
            "website": "https://www.tdsynnex.com",
            "notes": "Primary AV distributor",
            "isActive": true,
            "apiEnabled": true,
            "lastApiTest": "2024-12-24T10:00:00Z",
            "lastApiTestSuccess": true,
            "dateCreated": "2024-01-15T10:00:00Z",
            "dateUpdated": "2024-12-25T12:00:00Z"
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Status	Code	Description
404	`VENDOR_NOT_FOUND`	Vendor with specified ID does not exist

POST /api/v1/vendors

Creates a new vendor.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Vendor name (max 100 chars)
`contactPerson`	string	No	Primary contact name (max 100 chars)
`address1`	string	No	Street address line 1 (max 200 chars)
`address2`	string	No	Street address line 2 (max 200 chars)
`city`	string	No	City (max 100 chars)
`state`	string	No	State/Province (max 50 chars)
`postalCode`	string	No	Postal/ZIP code (max 20 chars)
`country`	string	No	Country (max 50 chars)
`phone`	string	No	Phone number (max 20 chars)
`fax`	string	No	Fax number (max 20 chars)
`email`	string	No	Email address (max 100 chars)
`website`	string	No	Website URL (max 200 chars)
`notes`	string	No	Internal notes (max 500 chars)
`isActive`	boolean	No	Active status (default: true)

Example Request

{
    "name": "Ingram Micro",
    "contactPerson": "Jane Doe",
    "address1": "3351 Michelson Dr",
    "city": "Irvine",
    "state": "CA",
    "postalCode": "92612",
    "country": "USA",
    "phone": "(800) 456-8000",
    "email": "[email protected]",
    "website": "https://www.ingrammicro.com",
    "notes": "Secondary distributor for Crestron"
}

Response (201 - Created)

{
    "success": true,
    "data": {
        "vendor": {
            "id": 2,
            "name": "Ingram Micro",
            ...
        }
    },
    "message": "Vendor created successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Vendor name is required
400	`CREATE_FAILED`	Failed to create vendor

PUT /api/v1/vendors/{id}

Updates an existing vendor. Only provided fields are updated.

Request Body

Same fields as POST, but all are optional. Only include fields you want to update.

Example Request

{
    "contactPerson": "John Smith Jr.",
    "phone": "(800) 555-1234",
    "notes": "Updated contact info - January 2025"
}

Response (200 - Success)

{
    "success": true,
    "data": {
        "vendor": {
            "id": 1,
            "name": "TD SYNNEX",
            "contactPerson": "John Smith Jr.",
            ...
        }
    },
    "message": "Vendor updated successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Status	Code	Description
404	`VENDOR_NOT_FOUND`	Vendor with specified ID does not exist
400	`VALIDATION_ERROR`	Vendor name cannot be empty

DELETE /api/v1/vendors/{id}

Deletes a vendor.

Response (200 - Success)

{
    "success": true,
    "data": {
        "id": 1,
        "name": "TD SYNNEX",
        "deleted": true
    },
    "message": "Vendor deleted successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Status	Code	Description
404	`VENDOR_NOT_FOUND`	Vendor with specified ID does not exist
400	`DELETE_FAILED`	Failed to delete vendor (may have dependencies)

Deletion Warning

Deleting a vendor may fail if products reference this vendor. Consider setting isActive to false instead of deleting.