openapi: 3.2.0 info: title: Business REST Customers API 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 tags: - name: Customers 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:\n - `createdAt`: Created at ascending\n - `-createdAt`: Created at descending\n - `givenName`: Given name ascending\n - `-givenName`: Given name descending\n - `familyName`: Family name ascending\n - `-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: - 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 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 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 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: - Customers deprecated: true components: 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 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