The Business context API covering the Customer List for a business location — list, get, update and delete customers. Vendasta has deprecated the Customer List in favour of the CRM; this surface is maintained for existing integrations only.
openapi: 3.0.0
info:
title: Business REST APIs
version: '1.0'
description: |-
APIs for managing data for a single business location.
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - Current Trusted Tester [Endpoint](../crm/crm.json/paths/~1{namespace}~1{resourceTypeCode}/post).
servers:
- url: 'https://prod.apigateway.co/business'
description: Production
- url: 'https://demo.apigateway.co/business'
description: Demo
- url: '{local}/business'
description: Local
- url: 'http://localhost:11001/business'
description: Localhost
paths:
/customers:
post:
summary: Create Customer
operationId: post-customers
responses:
'201':
description: Created
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/customers'
'409':
description: Conflict
content:
application/vnd.api+json:
schema:
type: object
description: ''
x-examples:
example-1:
errors:
- code: ResourceAlreadyExists
title: Already exists
detail: A customers already exists with matching values
status: '409'
meta:
conflictingCustomerID: CUSTOMER-7e5cda73-1d01-42ee-a44a-622b8c3c7c04
field: emailAddresses
fieldValue: tdewald+test@vendasta.com
resourceType: customers
meta:
requestId: pLSjFbcXoEFfRsWx
links:
self:
href: /business/customers
additionalProperties: false
properties:
errors:
type: array
uniqueItems: false
minItems: 1
items:
type: object
additionalProperties: false
properties:
code:
type: string
default: ResourceAlreadyExists
example: ResourceAlreadyExists
readOnly: true
title:
type: string
default: Already exists
example: Already exists
readOnly: true
detail:
type: string
default: A customers already exists with matching values
example: A customers already exists with matching values
readOnly: true
status:
type: string
default: '409'
example: '409'
readOnly: true
meta:
type: object
additionalProperties: false
properties:
conflictingCustomerID:
type: string
example: CUSTOMER-123
description: The ID of the customer record with a matching email or phone number
readOnly: true
field:
type: string
enum:
- phoneNumbers
- emailAddresses
example: emailAddresses
description: The field that contains the matching value
readOnly: true
fieldValue:
type: string
example: example@email.com
description: The email or phone number value that matches an existing customer
readOnly: true
resourceType:
type: string
default: customers
example: customers
readOnly: true
readOnly: true
readOnly: true
readOnly: true
meta:
type: object
additionalProperties: false
properties:
requestId:
type: string
readOnly: true
readOnly: true
links:
type: object
additionalProperties: false
properties:
self:
type: object
additionalProperties: false
properties:
href:
type: string
readOnly: true
readOnly: true
readOnly: true
readOnly: true
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - Current Trusted Tester [Endpoint](../crm/crm.json/paths/~1{namespace}~1{resourceTypeCode}/post).
Used to create a new customer record within Business App.
The following members must be populated during creation:
- `relationships.businessLocation.data.id`
- `attributes.emailAddresses` or `attributes.phoneNumbers`
x-lifecycle:
status: trustedTester
security:
- OAuth2Demo:
- customers
- OAuth2Prod:
- customers
parameters:
- schema:
type: string
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
default: application/vnd.api+json
example: application/vnd.api+json
in: header
name: Content-Type
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
required: true
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/customers'
examples:
Example Request:
value:
data:
type: customers
attributes:
givenName: William
familyName: Smith
address:
streetAddress: 123 Fake St.
city: Kalamazoo
regionCode: US-MI
countryCode: US
phoneNumbers:
- '+13065551234'
emailAddresses:
- example@email.com
tags:
- 2021 Christmas Campaign
permissionToContact: true
createdAt: '2019-08-24T14:15:22Z'
updatedAt: '2019-08-24T14:15:22Z'
relationships:
businessLocation:
data:
id: AG-123
tags:
- Customers
deprecated: true
get:
summary: List Customers
operationId: get-customers
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/customers'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
description: Provides a link back to the first page of results
format: uri
next:
type: string
description: The URI at which the next batch of customers can be gotten from
format: uri
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - *coming soon*
Produces a list of customers
parameters:
- schema:
type: string
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
in: query
name: 'filter[businessLocation.id]'
description: Return customers for the specified business location
required: true
- schema:
type: string
in: query
description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
name: 'page[cursor]'
- schema:
type: string
in: query
description: 'The maximum number of tasks you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
name: 'page[limit]'
- schema:
type: string
enum:
- createdAt
- '-createdAt'
- givenName
- '-givenName'
- familyName
- '-familyName'
default: '-createdAt'
example: familyName
in: query
name: sort
description: |-
The order to sort the results in. Only one sort parameter may be provided:
- `createdAt`: Created at ascending
- `-createdAt`: Created at descending
- `givenName`: Given name ascending
- `-givenName`: Given name descending
- `familyName`: Family name ascending
- `-familyName`: Family name descending
security:
- OAuth2Demo:
- customers
- OAuth2Prod:
- customers
tags:
- Customers
x-lifecycle:
status: trustedTester
deprecated: true
options:
summary: List valid HTTP verbs for /customers
operationId: options-customers
responses:
'204':
description: No Content
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
tags:
- Options
- Customers
deprecated: true
'/customers/{id}':
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
summary: Get Customer
tags:
- Customers
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/customers'
links:
type: object
properties:
self:
type: string
operationId: get-customers-id
x-lifecycle:
status: trustedTester
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - Current Trusted Tester [Endpoint](../crm/crm.json/paths/~1{namespace}~1{resourceTypeCode}/post)
Fetch the current values for the specified customer.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
security:
- OAuth2Demo:
- customers
- OAuth2Prod:
- customers
deprecated: true
delete:
summary: Delete Customer
tags:
- Customers
responses:
'204':
description: No Content
operationId: delete-customers-id
x-lifecycle:
status: trustedTester
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - *coming soon*
Delete the specified customer.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
security:
- OAuth2Demo:
- customers
- OAuth2Prod:
- customers
deprecated: true
patch:
summary: Update Customer
operationId: patch-customers-id
tags:
- Customers
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Deprecated` - Will be replaced by a new CRM API - Current Trusted Tester [Endpoint](../crm/crm.json/paths/~1{namespace}~1{resourceTypeCode}/post).
Update the existing customer.
Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.
x-lifecycle:
status: trustedTester
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
default: application/vnd.api+json
enum:
- application/vnd.api+json
in: header
name: Content-Type
required: true
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
security:
- OAuth2Demo:
- customers
- OAuth2Prod:
- customers
responses:
'200':
description: Ok
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/customers'
links:
type: object
properties:
self:
type: string
format: uri
description: The address of the updated customer
headers: {}
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/customers'
deprecated: true
options:
summary: 'List valid HTTP verbs for /customers/{id}'
operationId: options-customers-id
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
tags:
- Options
- Customers
deprecated: true
components:
securitySchemes:
JWT:
type: http
scheme: bearer
bearerFormat: JWT
OAuth2Demo:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-demo.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-demo.apigateway.co/oauth2/token'
scopes:
customers: Allows read-write access to customer details
OAuth2Prod:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-prod.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-prod.apigateway.co/oauth2/token'
scopes:
customers: Allows read-write access to customer details
schemas:
customers:
title: Customers
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
A customer is a person a business location has had a prior business relationship with and permission to contact.
Customer records are displayed within Business App and are available to marketplace products. If you are looking for contacts within Sales and Success Center, see Sales Contact.
type: object
x-examples:
Example Customer:
type: customers
id: 'AG-123:CUSTOMER-123'
attributes:
givenName: William
familyName: Smith
address:
streetAddress: 109 8th Street E.
city: Saskatoon
regionCode: CA-SK
countryCode: CA
phoneNumbers:
- '+13065551234'
emailAddresses:
- bill@example.com
tags:
- 2021 Christmas Campaign
permissionToContact: true
createdAt: '2019-08-24T14:15:22Z'
updatedAt: '2019-08-24T14:15:22Z'
relationships:
businessLocation:
data:
id: AG-123
x-lifecycle:
status: trustedTester
x-tags:
- Customers
properties:
type:
type: string
default: customers
example: customers
enum:
- customers
readOnly: true
id:
type: string
minLength: 1
example: 'AG-123:CUSTOMER-123'
readOnly: true
attributes:
type: object
properties:
givenName:
type: string
description: 'Given name(s) or first name(s) of the customer. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.'
example: William
minLength: 1
familyName:
type: string
minLength: 1
description: 'Surname(s) or last name(s) of the customer. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.'
example: Smith
address:
type: object
properties:
streetAddress:
type: string
minLength: 1
example: 123 Fake St.
city:
type: string
minLength: 1
example: Kalamazoo
description: 'The city, town or locality component of an address.'
regionCode:
type: string
minLength: 1
example: US-MI
description: |-
The code for the top level subdivision within the country (state/province). For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)
Examples: CA-SK, US-FL, AG-08, AU-NSW
countryCode:
type: string
minLength: 2
example: US
maxLength: 2
description: |-
The two letter country code. For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)
Examples: CA, US, AU
phoneNumbers:
type: array
description: A comma-separated list of phone numbers for a customer in E.164 format ex. +13065551234. At least one unique phone number or email is required.
items:
type: string
example: '+13065551234'
emailAddresses:
type: array
description: A list of email addresses for a customer. At least one unique phone number or email is required.
items:
type: string
example: example@email.com
format: email
tags:
type: array
description: A list of business identifiers used to categorize customer resources.
items:
type: string
example: 2021 Christmas Campaign
permissionToContact:
type: boolean
default: false
description: Whether the customer has given permission to be contacted for marketing purposes.
createdAt:
type: string
format: date-time
description: The time at which the customer was initially created in the platform.
readOnly: true
updatedAt:
type: string
format: date-time
description: The time at which the customer was last updated.
readOnly: true
relationships:
type: object
properties:
businessLocation:
type: object
properties:
data:
type: object
properties:
id:
type: string
minLength: 1
description: The ID of the business location the customer belongs to.
type:
type: string
default: businessLocation
enum:
- businessLocation
readOnly: true
required:
- id
tags:
- name: Customers
- name: Options