> For the complete documentation index, see [llms.txt](https://docs.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alternativepayments.io/api-reference/vendors.md).

# Vendors

## List vendors

> Get a paginated list of vendors with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-VendorReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VendorReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"}}},"paths":{"/vendors":{"get":{"description":"Get a paginated list of vendors with optional filtering","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"boolean"},"description":"Filter by active status","in":"query","name":"is_active"},{"schema":{"type":"string"},"description":"Filter by origin (manual, quickbooks, ocr)","in":"query","name":"origin"},{"schema":{"type":"string"},"description":"Filter by vendor name","in":"query","name":"vendor_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-VendorReply"}}}}},"summary":"List vendors","tags":["Vendors"]}}}}
```

## Create a vendor

> Create a new vendor with the provided information. Optionally include bank account details.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateVendorInput":{"description":"Vendor creation request","properties":{"bank_account":{"$ref":"#/components/schemas/BankAccountInput"},"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"},"BankAccountInput":{"description":"Bank account details for vendor creation","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/vendors":{"post":{"description":"Create a new vendor with the provided information. Optionally include bank account details.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a vendor","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorInput"}}},"description":"Vendor information","required":true}}}}}
```

## Get a vendor

> Get vendor details by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}":{"get":{"description":"Get vendor details by ID","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a vendor","tags":["Vendors"]}}}}
```

## Update a vendor

> Partially update vendor details

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PatchVendorInput":{"description":"Vendor patch request (partial update)","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"}}},"paths":{"/vendors/{id}":{"patch":{"description":"Partially update vendor details","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update a vendor","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchVendorInput"}}},"description":"Vendor patch information","required":true}}}}}
```

## Get vendor bank account

> Get the vendor's bank account details (masked)

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BankAccountReply":{"description":"Vendor bank account details (masked)","properties":{"account_mask":{"type":"string"},"account_type":{"$ref":"#/components/schemas/AccountTypeEnum"},"bank_name":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"},"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/bank-account":{"get":{"description":"Get the vendor's bank account details (masked)","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get vendor bank account","tags":["Vendors"]}}}}
```

## Add or update vendor bank account

> Create or replace the vendor's bank account

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BankAccountReply":{"description":"Vendor bank account details (masked)","properties":{"account_mask":{"type":"string"},"account_type":{"$ref":"#/components/schemas/AccountTypeEnum"},"bank_name":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"},"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UpsertBankAccountInput":{"description":"Bank account upsert request","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/vendors/{id}/bank-account":{"post":{"description":"Create or replace the vendor's bank account","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Add or update vendor bank account","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertBankAccountInput"}}},"description":"Bank account details","required":true}}}}}
```

## Create vendor data request

> Send a self-service data collection link to the vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateVendorDataRequestReply":{"description":"Vendor data request creation result","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-request":{"post":{"description":"Send a self-service data collection link to the vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorDataRequestReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create vendor data request","tags":["Vendors"]}}}}
```

## List vendor data requests

> Get all data requests for a vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ListVendorDataRequestsReply":{"description":"List of vendor data requests","properties":{"data":{"items":{"$ref":"#/components/schemas/VendorDataRequestReply"},"type":"array"}},"type":"object"},"VendorDataRequestReply":{"description":"Vendor data request details","properties":{"created_at":{"type":"string"},"expires_at":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"submitted_at":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-requests":{"get":{"description":"Get all data requests for a vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListVendorDataRequestsReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List vendor data requests","tags":["Vendors"]}}}}
```

## Resend vendor data request

> Resend the data collection email for a vendor data request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ResendVendorDataRequestReply":{"description":"Data request resend confirmation","properties":{"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-requests/{request_id}/resend":{"post":{"description":"Resend the data collection email for a vendor data request","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Data Request ID","in":"path","name":"request_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVendorDataRequestReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Resend vendor data request","tags":["Vendors"]}}}}
```

## Deactivate a vendor

> Deactivate a vendor, setting is\_active to false

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"DeactivateVendorReply":{"description":"Vendor deactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/deactivate":{"post":{"description":"Deactivate a vendor, setting is_active to false","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateVendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Deactivate a vendor","tags":["Vendors"]}}}}
```

## Reactivate a vendor

> Reactivate a previously deactivated vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ReactivateVendorReply":{"description":"Vendor reactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/reactivate":{"post":{"description":"Reactivate a previously deactivated vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactivateVendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Reactivate a vendor","tags":["Vendors"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alternativepayments.io/api-reference/vendors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.