openapi: 3.0.3
info:
  title: Service Fusion Open Calendar Tasks Contacts API
  description: 'The Service Fusion Open API is a REST/JSON interface to Service Fusion field service management (FSM) software for home-service contractors. It exposes the core operational records - customers and their contacts, jobs (work orders), estimates, invoices, payments, the product/service catalog, technicians, and calendar tasks - over HTTPS. Requests are authenticated with OAuth 2.0; obtain an access token from the token endpoint at https://api.servicefusion.com/oauth/access_token using an authorization_code or client_credentials grant, then send it as a Bearer token. API access is available on the Service Fusion Pro plan and is rate limited to roughly 60 requests per minute.

    Grounding note - customers, jobs, estimates, invoices, and techs are documented resources on the Service Fusion API. Contacts, products, services, payments, and calendar tasks are modeled here from the Service Fusion FSM data model and the platform''s read-and-create API conventions; verify exact paths, fields, and available methods against the live reference at https://docs.servicefusion.com/ before production use. In practice the public API is read-and-create heavy - list (GET), retrieve (GET), and create (POST) are the reliably available operations; update (PUT) and delete (DELETE) are not consistently exposed across resources.'
  version: '1.0'
  contact:
    name: Service Fusion
    url: https://www.servicefusion.com
servers:
- url: https://api.servicefusion.com/v1
  description: Service Fusion Open API v1
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Contacts
  description: Individual contacts and service locations on a customer account.
paths:
  /customers/{id}/contacts:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: listCustomerContacts
      tags:
      - Contacts
      summary: List a customer's contacts
      description: Lists the contacts and service locations attached to a customer account.
      responses:
        '200':
          description: A list of contacts for the customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createCustomerContact
      tags:
      - Contacts
      summary: Add a contact to a customer
      description: Creates a new contact under the given customer account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '201':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
  schemas:
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
    ContactList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        _meta:
          $ref: '#/components/schemas/Pagination'
    Address:
      type: object
      properties:
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
        state_prov:
          type: string
        postal_code:
          type: string
        country:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    ContactInput:
      type: object
      required:
      - fname
      properties:
        fname:
          type: string
        lname:
          type: string
        contact_type:
          type: string
        phone:
          type: string
        email:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Contact:
      type: object
      properties:
        id:
          type: string
        customer_id:
          type: string
        fname:
          type: string
        lname:
          type: string
        contact_type:
          type: string
        phone:
          type: string
        email:
          type: string
        address:
          $ref: '#/components/schemas/Address'
  responses:
    ValidationError:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid OAuth 2.0 access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0. Access tokens are issued at https://api.servicefusion.com/oauth/access_token.
      flows:
        authorizationCode:
          authorizationUrl: https://api.servicefusion.com/oauth/authorize
          tokenUrl: https://api.servicefusion.com/oauth/access_token
          scopes: {}
        clientCredentials:
          tokenUrl: https://api.servicefusion.com/oauth/access_token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer access token obtained via the OAuth 2.0 token endpoint.