Smokeball Contacts API

openapi: 3.2.0
info:
  title: Smokeball Activity Codes Contacts API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Contacts
paths:
  /contacts/{contactId}/relations:
    get:
      tags:
      - Contacts
      summary: Get contact relations
      description: Returns a list of relations for a specified contact if associated with the authenticated client.
      operationId: GetRelations
      parameters:
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'Link' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkPagedCollection'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Contacts
      summary: Create a contact relation
      description: Creates a relation for a specified contact.
      operationId: CreateRelation
      parameters:
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When related contact id is not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /contacts/{contactId}/relations/{relatedContactId}:
    get:
      tags:
      - Contacts
      summary: Get a contact relation
      description: Retrieves a relation for a specified contact if associated with the authenticated client.
      operationId: GetRelationById
      parameters:
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      - name: relatedContactId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Contacts
      summary: Update a contact relation
      description: Updates a relation for a specified contact.
      operationId: UpdateRelation
      parameters:
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      - name: relatedContactId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactRelationDto'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Contacts
      summary: Delete a contact relation
      description: Deletes a relation for a specified contact.
      operationId: DeleteRelation
      parameters:
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      - name: relatedContactId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /contacts:
    get:
      tags:
      - Contacts
      summary: Get contacts
      description: Returns a list of contacts.
      operationId: GetContacts
      parameters:
      - name: Offset
        in: query
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
      - name: Limit
        in: query
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
      - name: UpdatedSince
        in: query
        description: Returns contacts updated since a specified time (.net ticks representation of the UTC datetime).
        schema:
          type: integer
          format: int64
      - name: ExcludeDeletedContacts
        in: query
        description: Excludes (filters out) deleted contacts if set to true.
        schema:
          type: boolean
          example: true
        example: true
      - name: Type
        in: query
        description: 'Filters result by one more contact types if set. Returns all contact types by default.

          Possible values: Staff, Person, Organisation, GroupOfPeople, Trust'
        schema:
          type: array
          items:
            type: string
      - name: Search
        in: query
        description: ' Available fields: email, phone, name'
        schema:
          type: array
          items:
            type: string
      - name: Sort
        in: query
        description: ' Available fields: lastUpdated'
        schema:
          type: string
      - name: Fields
        in: query
        description: ' Available fields: passportDetails, deathDetails, citizenshipDetails, utbmsDetails, tags, executionOptions, voiDetails'
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'Contact' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPagedCollection'
    post:
      tags:
      - Contacts
      summary: Create a contact
      description: Creates a contact.
      operationId: CreateContact
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the authenticated account does not have access to create contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /contacts/{id}:
    get:
      tags:
      - Contacts
      summary: Get a contact
      description: Retrieves a specified contact.
      operationId: GetContactById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'Contact' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Contacts
      summary: Update a contact
      description: Updates a specified contact.
      operationId: UpdateContact
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactDto'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Contacts
      summary: Delete a contact
      description: Deletes a specified contact.
      operationId: DeleteContact
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /contacts/{id}/tags:
    get:
      tags:
      - Contacts
      summary: Get contact tags
      description: Retrieves a specified contacts tags.
      operationId: GetContactTagsById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a collection of 'Tag' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagCollection'
        '403':
          description: When contact with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Contacts
      summary: Add tags to a contact
      description: Adds tags to a contact.
      operationId: AddContactTags
      parameters:
      - name: id
        in: path
        description: The contact ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The list of tags to add
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                type: string
          application/json:
            schema:
              type: array
              items:
                type: string
          application/*+json:
            schema:
              type: array
              items:
                type: string
      responses:
        '201':
          description: When request is successful. Returns a hypermedia 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /contacts/{id}/tags/{tagId}:
    delete:
      tags:
      - Contacts
      summary: Remove tags from a contact
      description: Removes tags from a contact.
      operationId: RemoveContactTags
      parameters:
      - name: id
        in: path
        description: The contact ID
        required: true
        schema:
          type: string
          format: uuid
      - name: tagId
        in: path
        description: The tag ID (optional for bulk delete)
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The list of tags for bulk delete
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                type: string
          application/json:
            schema:
              type: array
              items:
                type: string
          application/*+json:
            schema:
              type: array
              items:
                type: string
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the contact tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When contact with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    Tag:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Identifier of the tag. Role tags do not have an identifier.
        name:
          type:
          - string
          - 'null'
          description: Name of tag.
        type:
          type: string
          description: Type of tag. Accepted values are 'Role' or 'Custom'
          example: Custom
      additionalProperties: false
      description: Represents a tag with an identifier, name, and type.
    Trustee:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Trustee's name.
          example: John Smith
        type:
          type:
          - string
          - 'null'
          description: 'Type of trustee.


            Standard values are: Company, Individual.

            A custom value can be supplied instead.'
          example: Individual
      additionalProperties: false
    TrusteeDto:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Trustee's name.
          example: John Smith
        type:
          type:
          - string
          - 'null'
          description: 'Type of trustee.


            Standard values are: Company, Individual.


            A custom value can be supplied instead.'
          example: Individual
      additionalProperties: false
    ContactDto:
      type: object
      properties:
        externalSystemId:
          type:
          - string
          - 'null'
          description: External system id for the contact.
          example: EXT01
        person:
          allOf:
          - $ref: '#/components/schemas/PersonDto'
          description: Contact person details (if applicable).
        company:
          allOf:
          - $ref: '#/components/schemas/CompanyDto'
          description: Contact company details (if applicable).
        trust:
          allOf:
          - $ref: '#/components/schemas/TrustDto'
          description: 'Contact trust details (if applicable).


            Only supported in US.'
        groupOfPeople:
          allOf:
          - $ref: '#/components/schemas/GroupOfPeopleDto'
          description: 'Contact group details (if applicable).


            Only supported in US and AU.'
        isDeleted:
          type: boolean
          description: Contact can be restored by setting this to false.
          example: false
      additionalProperties: false
    TagCollection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Tag'
      additionalProperties: false
    CitizenshipDetailsDto:
      type: object
      properties:
        countryOfCitizenship:
          type:
          - string
          - 'null'
          description: Country of citizenship
          example: USA
        nationality:
          type:
          - string
          - 'null'
          description: Nationality
          example: American
        languageOfInterpreter:
          type:
          - string
          - 'null'
          description: Language of interpreter
          example: French
      additionalProperties: false
    CitizenshipDetails:
      type: object
      properties:
        countryOfCitizenship:
          type:
          - string
          - 'null'
          description: Country of citizenship
          example: USA
        nationality:
          type:
          - string
          - 'null'
          description: Nationality
          example: American
        languageOfInterpreter:
          type:
          - string
          - 'null'
          description: Language of interpreter
          example: French
      additionalProperties: false
    DeathDetailsDto:
      type: object
      properties:
        deathDate:
          type:
          - string
          - 'null'
          description: Contact person's date of death.
          format: date-time
          example: '2020-08-01'
        isDeathDateUnknown:
          type: boolean
          description: Whether the person's exact date of death is known.
          example: false
        deathDateFrom:
          type:
          - string
          - 'null'
          description: Starting range for person's possible date of death.
          format: date-time
          example: '2020-08-01'
        deathDateTo:
          type:
          - string
          - 'null'
          description: Ending range for person's possible date of death.
          format: date-time
          example: '2020-08-01'
        deathPlace:
          type:
          - string
          - 'null'
          description: Contact person's place of death.
          example: Chicago
        deathState:
          type:
          - string
          - 'null'
          description: "Contact person's death state.\n            \nOnly supported in AU and US."
          example: IL
        deathCountry:
          type:
          - string
          - 'null'
          description: Contact person's death country.
          example: USA
        deathCounty:
          type:
          - string
          - 'null'
          description: "Contact person's death county.\n            \nOnly supported in US."
          example: San Bernardino County
      additionalProperties: false
    VoiDetails:
      type: object
      properties:
        isCompleted:
          type: boolean
          description: Indicates if VOI has been completed
          example: true
        completedDateTime:
          type:
          - string
          - 'null'
          description: Date and time when VOI was completed
          format: date-time
          example: '2024-01-15T10:30:00Z'
        reference:
          type:
          - string
          - 'null'
          description: Reference number or order ID from the VOI service
          example: '12345678'
        source:
          type:
          - string
          - 'null'
          description: Source/provider of the VOI service
          example: InfoTrackID
        status:
          type:
          - string
          - 'null'
          description: Current status of the VOI check
          example: Complete
      additionalProperties: false
      description: 'Verification of Identity (VOI) details


        Only supported in AU.'
    LinkPagedCollection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Link'
        offset:
          type:
          - integer
          - 'null'
          format: int32
        limit:
          type:
          - integer
          - 'null'
          format: int32
        size:
          type: integer
          format: int64
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
        previous:
          allOf:
          - $ref: '#/components/schemas/Link'
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
      additionalProperties: false
    Company:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Company's name.
          example: Brown LLC
        type:
          type:
          - string
          - 'null'
          description: 'Company''s type.


            Possible values for US: ''Corporation'', ''Government Agency'', ''Limited Liability Company'', ''Sole Proprietor'', ''Partnership'', ''Not-for-Profit''


            Possible values for AU: ''Company'', ''Sole Proprietor'', ''Partnership'', ''Government Department''


            Possible values for UK: ''Company'', ''Sole Trader'', ''Partnership'', ''Limited Liability Partnership'', ''Government Department'''
          example: Corporation
        phone:
          allOf:
          - $ref: '#/components/schemas/PhoneNumber'
          description: Company's phone details.
        fax:
          allOf:
          - $ref: '#/components/schemas/PhoneNumber'
          description: Company's fax details.
        email:
          type:
          - string
          - 'null'
          description: Company's email address.
          example: contact@brown.com
        website:
          type:
          - string
          - 'null'
          description: Company's website URL.
          example: https://www.brownllc.com
        notes:
          type:
          - string
          - 'null'
          description: Additional notes for company (if applicable).
          example: Construction company
        abn:
          type:
          - string
          - 'null'
          description: 'For AU: Australian Company Number (ABN) of the firm.


            For UK: Company Registration Number (CRN) of the firm.


            Only supported in AU and UK.'
          example: '1234567890'
        companyNumberType:
          type:
          - string
          - 'null'
          description: 'Company''s Australian company number type.


            Accepted values - ACN, ARBN


            Only supported in AU.'
          example: ACN
        companyNumber:
          type:
          - string
          - 'null'
          description: "Company's Australian Company Number.\n            \nOnly supported in AU."
          example: '234567890'
        doingBusinessAsName:
          type:
          - string
          - 'null'
          description: "Doing Business As (DBA) name.\n            \nOnly supported in US."
          example: Brown Holdings
        tradingAs:
          type:
          - string
          - 'null'
          description: "Trading As type (e.g. 'Trading As', 'Doing Business As').\n            \nOnly supported in AU."
          example: Trading As
        tradingName:
          type:
          - string
          - 'null'
          description: "Trading name of the organisation.\n            \nOnly supported in AU and UK."
          example: Brown Trading Co
        mailingAddress:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: Company's mailing address details.
        businessAddress:
          allOf:
          - $ref: '#/components/schemas/AddressWithDxAddress'
          description: Company's business address details.
        staff:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Link'
          description: Company's staff hypermedia links.
          readOnly: true
        directors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Link'
          description: Company's directors hypermedia links.
          readOnly: true
        staffIds:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Deprecated - use Staff instead. This field may not be supported in future.
          readOnly: true
        executionOptions:
          allOf:
          - $ref: '#/components/schemas/ExecutionOptions'
          description: 'Company''s execution options for document signing and VOI details.


            Only supported in AU.'
      additionalProperties: false
    PhoneNumber:
      type: object
      properties:
        areaCode:
          type:
          - string
          - 'null'
          description: Phone area code.
          example: '555'
        number:
          type:
          - string
          - 'null'
          description: Phone number (excluding area code).
          example: '1234567'
      additionalProperties: false
    PhoneNumberWithExtensionDto:
      type: object
      properties:
        areaCode:
          type:
          - string
          - 'null'
          description: "Phone area code. \n\nOnly supported in the US."
          example: '555'
        number:
          type:
          - string
          - 'null'
          description: Phone number (excluding area code).
          example: '1234567'
        extension:
          type:
          - string
          - 'null'
          description: Phone number extension. Accepts numeric characters only.
          example: '103'
      additionalProperties: false
    Trust:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Trust's name.
          example: Trinity Trust
        status:
          type:
          - string
          - 'null'
          description: 'Trust''s status.


            Standard values are: as Trustee of, as Trustees of, as Co-Trustees of, as an Individual and as Trustee of, as Successor Trustee of.

            A custom value can be supplied instead.'
          example: as Trustee of
        trustNumber:
          type:
          - string
          - 'null'
          description: Trust's number.
          example: '12345678'
        executedDate:
          type:
          - string
          - 'null'
          description: Date trust was executed.
          format: date-time
          example: '1980-07-01'
        phone:
          allOf:
          - $ref: '#/components/schemas/PhoneNumber'
          description: Trust's phone details.
        fax:
          allOf:
          - $ref: '#/components/s

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