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](/api-reference/legacy/crm/create-crm-record).
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](/api-reference/legacy/crm/create-crm-record).

        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](/api-reference/legacy/crm/create-crm-record)

        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](/api-reference/legacy/crm/create-crm-record).

        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
