Versapay Customers API

openapi: 3.2.0
info:
  version: 1.3.35
  title: Versapay API Reference Customers API
  contact:
    name: Versapay Support
    url: https://www.versapay.com/support
    email: support@versapay.com
  x-logo:
    url: https://developers.versapay.com/images/logo.png
  termsOfService: https://www.versapay.com/terms-of-use
  license:
    name: Copyright 2022 Versapay. All Rights Reserved.
  description: 'As a supplier your customers are the entities that are invoiced.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a customer.

    '
servers:
- url: https://secure.versapay.com
  description: Production
- url: https://uat.versapay.com
  description: UAT
tags:
- name: Customers
  description: 'As a supplier your customers are the entities that are invoiced.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a customer.

    '
paths:
  /api/imports/customer:
    post:
      summary: Create and Update Customer
      description: 'Create a customer using the following attributes (at minimum by providing values for required attributes). If providing an identifier for an existing customer, its information is updated.<br><br>

        *Note: Any additional non-standard attribute will be stored with customer record and available for presentment rendering.*

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    example: C1234
                  message:
                    type: string
                    example: 1 customer with 3 contacts
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /api/exports/customer/{identifier}:
    get:
      summary: Export/View a Customer
      description: 'View a customer based on the `identifier` provided.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer record.

          '
        schema:
          type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /api/exports/customers:
    get:
      summary: Export Customers
      description: 'Customer records that have been created since watermark, limited to 100 records at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/CustomersResponse'
              examples:
                customers:
                  value:
                    customers:
                      '20':
                        identifier: megavoice-customer-1
                        display_number: megavoice-customer-1
                        name: MegavoiceCust
                        email: mukmuk@example.com
                        business_number: null
                        first_name: null
                        last_name: null
                        address_1: null
                        address_2: null
                        postal_code: null
                        city: null
                        province: null
                        country: ''
                        telephone: null
                        fax: null
                        status: ''
                        auto_debit: ''
                        invite_sent: null
                        signed_up: null
                        notification_suppressed: false
                        notification_override: false
                        paper_invoices: false
                        paper_statements: false
                        parent_identifier: null
                        balance_cents: 0
                        aging_cents: 0
                        aging_30_cents: 0
                        aging_60_cents: 0
                        aging_90_cents: 0
                        aging_120_cents: 0
                        aging_180_cents: 0
                        aging_older_cents: 0
                        current_cents: 0
                        credit_cents: 0
                        unapplied_payment_cents: 0
                        prepayment_cents: 0
                        owing_cents: 0
                        notes: null
                        adp: null
                        adp_arc: null
                        adp_external: null
                        last_contact_date: null
                        next_contact_date: null
                        credit_limit_cents: null
                        account_status: open
                        tags: null
                        user_tags: null
                        external_id: '1'
                        watermark: 20
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/customers/recent:
    get:
      summary: Export Customers Recently Updated
      description: 'Customer records that have been updated in the past 7 days, since watermark, limited to 100 records at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/CustomersResponse'
              examples:
                customers:
                  value:
                    customers:
                      '20':
                        identifier: megavoice-customer-1
                        display_number: megavoice-customer-1
                        name: MegavoiceCust
                        email: mukmuk@example.com
                        business_number: null
                        first_name: null
                        last_name: null
                        address_1: null
                        address_2: null
                        postal_code: null
                        city: null
                        province: null
                        country: ''
                        telephone: null
                        fax: null
                        status: ''
                        auto_debit: ''
                        invite_sent: null
                        signed_up: null
                        notification_suppressed: false
                        notification_override: false
                        paper_invoices: false
                        paper_statements: false
                        parent_identifier: null
                        balance_cents: 0
                        aging_cents: 0
                        aging_30_cents: 0
                        aging_60_cents: 0
                        aging_90_cents: 0
                        aging_120_cents: 0
                        aging_180_cents: 0
                        aging_older_cents: 0
                        current_cents: 0
                        credit_cents: 0
                        unapplied_payment_cents: 0
                        prepayment_cents: 0
                        owing_cents: 0
                        notes: null
                        adp: null
                        adp_arc: null
                        adp_external: null
                        last_contact_date: null
                        next_contact_date: null
                        credit_limit_cents: null
                        account_status: open
                        tags: null
                        user_tags: null
                        external_id: '1'
                        watermark: 20
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/customer/{identifier}/open_invoices:
    get:
      summary: Export Open Invoices for a Customer
      description: 'Invoice records with an open balance for the customer based on the `identifier` provided,

        limited to 100 records at a time.<br><br>A consumer should store the last `watermark` value of each

        response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer record.

          '
        schema:
          type: string
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    number:
                      type: string
                      description: Invoice number, unique within a supplier.
                    display_number:
                      type: string
                      description: Invoice number as displayed to customers.
                    currency:
                      type: string
                      description: Currency code, based on ISO-4217, in lowercase. E.g. `cad`, `usd`, `aud`
                    amount_cents:
                      type: integer
                      description: The invoice amount in cents.
                    owing_cents:
                      type: integer
                      description: Balance remaining on this invoice or credit memo.
                    customer_identifier:
                      type: string
                      description: Unique identifier for customer.
                    watermark:
                      $ref: '#/components/schemas/Watermark'
              example:
                open_invoices:
                - number: sh763-h3454-dh3432
                  display_number: INV1234
                  currency: usd
                  amount_cents: 40000
                  owing_cents: 30000
                  customer_identifier: CUS001
                  watermark: 8123612
                - number: pq7d2-h3124-jl3937
                  display_number: INV5678
                  currency: usd
                  amount_cents: -10000
                  owing_cents: -10000
                  customer_identifier: CUS001
                  watermark: 8123615
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /api/invitations:
    post:
      summary: Issue an invitation
      description: 'Issue a new contact invitation for the specified customer.  The recipient of the invitation will begin to receive other Collaborative AR notifications, subject to the configuration of the supplier.


        *Note:* If the provided email is not an existing contact of the specified customer, a new contact will be created.

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - email
              properties:
                identifier:
                  type: string
                  description: the `identifier` of the customer to invite the contact to
                  example: CUS001
                email:
                  type: string
                  description: Contact email address.
                  example: bob.smith@example.com
      responses:
        '200':
          description: Successfully Invited
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Cancel an invitation
      description: 'Cancel an existing contact invitation for the specified customer.


        *Note:* `403` will be returned if the specified customer is closed, or if the specified email was invited by a customer user

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - email
              properties:
                identifier:
                  type: string
                  description: the `identifier` of the customer to cancel the invitation for
                  example: CUS001
                email:
                  type: string
                  description: Contact email address.
                  example: bob.smith@example.com
      responses:
        '200':
          description: Invitation Successfully Cancelled
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /api/imports/customers/{identifier}/update_identifier:
    post:
      summary: Update Customer Identifier
      description: 'Update a customer''s identifier and any associations where identifier is being stored. <br><br> *Note:* `412` will be returned if the specified customer cannot be found or the identifier has already been taken.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer to be updated.

          '
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
              - new_identifier
              properties:
                new_identifier:
                  type: string
                  description: Customer's new identifier to be used. Must be unique within supplier.
                  example: CUS-1001
      responses:
        '200':
          description: Customer Successfully Updated.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    description: Message indicating update successful.
                    example: customer identifier updated
                  identifier:
                    type: string
                    description: Customer's new identifier.
                    example: CUS-1001
        '412':
          description: Precondition failed.
          content:
            application/json:
              schema:
                properties:
                  importer:
                    type: string
                    description: stringified json message containing error.
                    example: '{:customer=>["not found."]}'
components:
  schemas:
    Contact:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          description: Email address of the contact.
          format: email
        first_name:
          type: string
          description: First name of the contact.
        last_name:
          type: string
          description: Last name of the contact.
        title:
          type: string
          description: Title of the contact.
        department:
          type: string
          description: Department of the contact.
        telephone:
          type: string
          description: Phone number of the contact.
        bulk_activate:
          type: boolean
          description: If this is `true`, the contact is activated or invited (depending on the account configuration) on import.
          default: false
    Customer:
      type: object
      required:
      - identifier
      - name
      properties:
        identifier:
          type: string
          description: Customer number, must be unique within supplier. Alphanumeric.
          example: C1234
        display_number:
          type: string
          description: Customer display number, Alphanumeric.
          example: DispNum1234
        name:
          type: string
          description: Customer name.
          example: Acme Inc.
        email:
          type: string
          format: email
          description: Email address of the default contact.
          example: bob.smith@example.com
        first_name:
          type: string
          description: First name of the default contact.
          example: Bob
        last_name:
          type: string
          description: Last name of the default contact.
          example: Smith
        notes:
          type: string
          description: Optional text field up to 64K.
          example: Payment terms will be revised next year.
        address_1:
          type: string
          description: Billing address line 1.
          example: 200 Main Street
        address_2:
          type: string
          description: Billing address line 2.
          example: Suite 250
        city:
          type: string
          description: Billing address - city.
          example: Toronto
        province:
          type: string
          description: Billing address - state or province.
          example: 'ON'
        postal_code:
          type: string
          description: Billing address - zip or postal code.
          example: M5M 5M5
        country:
          type: string
          description: Billing address - country.
          example: CA
        telephone:
          type: string
          description: Customer phone number.
          example: (416) 123-4567
        fax:
          type: string
          description: Customer fax number.
          example: (416) 100-1020
        url:
          type: string
          format: uri
          description: Customer web site.
          example: www.acmeinc.com
        business_number:
          type: string
          description: Customer EIN or Business Number. 20-character alphanumeric.
          example: GS324587987
        locale:
          type: string
          description: Customer language, based on ISO 639-1 standard.
          enum:
          - en
          - fr
          - es
        parent_identifier:
          type: string
          description: Required if the customer is part of a hierarchy, and this customer has a level (parent) above it. This is the identifier of the customer immediately above this customer in the tree.
          example: P3212
        pdf_attachment_opt_in:
          type: boolean
          description: If `true`, the customer will receive PDFs of invoices and attachments with all invoice notifications.
          default: false
        account_status:
          type: string
          description: The status of the customer's account with the supplier.
          enum:
          - open
          - closed
          default: open
        last_contact_date:
          type: string
          format: date
          description: The last time the customer was contacted. It is ignored if the customer already has a last contact date and it is more recent than this one.
          example: '2017-12-04'
        next_contact_date:
          type: string
          format: date
          description: The date of the next planned contact with the customer. This always overwrites what is on the customer.
          example: '2018-02-15'
        credit_limit_cents:
          type: integer
          description: The customer's credit limit. This is the maximum value of outstanding invoices before the supplier is alerted, if supplier is configured to monitor this. If the customer is a multi-currency customer, this is the total credit limit converted to a single currency (see next field.)
          example: '2000000'
        credit_limit_currency:
          type: string
          description: Currency of the credit limit. If blank, defaults to the currency of the majority of the customer's invoices. If there are no invoices, defaults to the supplier’s default currency.
          example: CAD
        credit_rating:
          type: string
          description: Credit rating for the customer.
          example: AA
        terms_type:
          type: string
          description: This field and `terms_value` specify how to set a customer's due date.
          enum:
          - date
          - day
        terms_value:
          type: integer
          description: 'This field and `terms_type` specify how to set a customer''s invoice due date.


            If terms_type is ''day'':


            * It means the due date should be <terms_value> days after invoice date.

            * E.g. if terms_value is 30, the due date must be 30 days after the invoice date.

            * It must be a whole number between 0 and 100.


            If terms_type is ''date'':


            * It means the due date is on a fixed day (terms_value) of the month.

            * E.g. if terms_value is 15, it means the due date should be on the 15th of the month after invoice date.

            * It must be an integer between 1 and 27 inclusive, or -1 to specify the last day of the month, or -2 to specify the second-last day of the month.

            '
          example: 15
        company_bio:
          type: string
          description: Short description of products and services that the customer offers.
          example: Acme Inc. sells cutting-edge widgets.
        ignores_cc_payment_rules:
          type: boolean
          description: If this is `true`, it means that the customer is not subject to any credit card payment rules, and is free to use credit cards any time.
          default: false
          example: 'false'
        notification_suppressed:
          type: boolean
          description: If this is `true`, all notifications to the customer are suppressed.
          default: false
          example: 'false'
        tags:
          type: string
          description: One or more tags separated by semi-colons.
          example: Blue;Green;Yellow
        external_id:
          type: string
          description: External (ERP-based) identifier for the customer record.
        external_group_identifier:
          type: string
          description: 'External (ERP-based) identifier used to control customer grouping.


            If the supplier is configured for restricted grouping, the system will not permit a user to group customers together that have different values for `external_group_identifier`.


            If the supplier is not configured for restricted grouping, this value is saved but ignored.

            '
        replace_contacts:
          type: boolean
          description: When `true` for a customer that is re-imported any contacts in the payload that are also in the DB will be updated if they are not signed-up users, and any contacts in the DB that were created by the supplier and are not in the payload will be deleted if not signed up, otherwise they will be disabled.
          default: false
        line_item_attributes:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
          example:
          - email: jane.smith@example.com
            first_name: Jane
            last_name: Smith
            telephone: 809-888-1234
            title: Buyer
          - email: bob.smith@example.com
            first_name: Bob
            last_name: Smith
            title: Manager
            department: Accounts Payable
            telephone: 809-345-9833
          - email: steve.jobs@example.com
            first_name: Steve
            last_name: Jobs
            title: CEO
    CustomerResponse:
      type: object
      properties:
        identifier:
          type: string
          description: Customer number, unique within supplier.
          example: CUST-001
        name:
          type: string
          description: Customer name.
          example: ABC Inc.
        email:
          type: string
          format: email
          description: Email address of the default contact.
          example: bob.smith@example.com
        first_name:
          type: string
          description: First name of the default contact.
          example: Bob
        last_name:
          type: string
          description: Last name of the default contact.
          example: Smith
        notes:
          type: string
          description: Optional text field up to 64K.
          example: Payment terms will be revised next year.
        address_1:
          type: string
          description: Billing address line 1.
          example: 1 Bay St.
        address_2:
          type: string
          description: Billing address line 2.
          example: Suite 200
        city:
          type: string
          description: Billing address - city.
          example: Toronto
        province:
          type: string
          description: Billing address - state or province.
          example: 'ON'
        postal_code:
          type: string
          description: Billing address - zip or postal code.
          example: M5M 5M5
        country:
          type: string
          description: Billing address - country.
          example: CA
        telephone:
          type: string
          description: Customer phone number.
          example: (416) 123-4567
        fax:
          type: string
          description: Customer fax number.
          example: (416) 111-2222
        business_number:
          type: string
          description: Customer EIN or Business Number. 20-character alphanumeric.
          example: '18889990'
        status:
          type: string
          description: Customer adoption status.
          enum:
          - Not Activated
          - Activated
          - Invited
          - Express
          - Signed Up
          - Paying
        auto_debit:
          type: string
          description: '`Y`, if customer has set up an AutoPay agreement. `N` otherwise.

            '
          enum:
          - Y
          - N
          example: N
        invite_sent:
          type: string
          format: date
          description: The date when invite was sent, in YYYY-MM-DD format.
          example: '2018-02-23'
        signed_up:
          type: string
          format: date
          description: The date when customer user signed up, in YYYY-MM-DD format.
          example: '2018-02-24'
        notification_suppressed:
          type: string
          description: '`Y`, if notifications are suppressed for the customer. `N` otherwise.

            '
          enum:
          - Y
          - N
        notification_override:
          type: string
          description: '`Y`, if overdue balance notifications are made optional for the customer. `N` otherwise.

            '
          enum:
          - Y
          - N
        paper_invoices:
          type: string
          description: '`Y`, if customer receives paper invoices. `N` otherwise.

            '
          enum:
          - Y
          - N
        balance:
          type: string
          description: 'Total outstanding balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_balance`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        credit:
          type: string
          description: 'Total outstanding credit balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_credit`). This applies to suppliers accepting multicurrency payments.

            '
          example: -$123.45
        current:
          type: string
          description: 'Current outstanding balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_current`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging:
          type: string
          description: 'Total overdue balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_30:
          type: string
          description: 'Balance overdue (1-30 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_30`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_60:
          type: string
          description: 'Balance overdue (31-60 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_60`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_90:
          type: string
          description: 'Balance overdue (61-90 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_90`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_older:
          type: string
          description: 'Balance overdue (91+ days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_older`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        unapplied_payment:
          type: string
          description: 'Total unapplied payment on the customer account.<br>


            Note: This field is prefixed with the curr

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/versapay/refs/heads/main/openapi/versapay-customers-api-openapi.yml