Smokeball Contacts API

openapi: 3.0.1
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.\r\nPossible 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:
    ContactPagedCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
          nullable: true
        offset:
          type: integer
          format: int32
          nullable: true
        limit:
          type: integer
          format: int32
          nullable: true
        size:
          type: integer
          format: int64
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        previous:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
      additionalProperties: false
    VoiDetails:
      type: object
      properties:
        isCompleted:
          type: boolean
          description: Indicates if VOI has been completed
          example: true
        completedDateTime:
          type: string
          description: Date and time when VOI was completed
          format: date-time
          nullable: true
          example: '2024-01-15T10:30:00Z'
        reference:
          type: string
          description: Reference number or order ID from the VOI service
          nullable: true
          example: '12345678'
        source:
          type: string
          description: Source/provider of the VOI service
          nullable: true
          example: InfoTrackID
        status:
          type: string
          description: Current status of the VOI check
          nullable: true
          example: Complete
      additionalProperties: false
      description: "Verification of Identity (VOI) details\r\n\r\nOnly supported in AU."
    ExecutionPerson:
      type: object
      properties:
        name:
          type: string
          description: Person's full name
          nullable: true
          example: John Smith
        address:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: Person's address
          nullable: true
        personType:
          type: string
          description: "Person type for execution.\r\n\r\nOnly supported in AU."
          nullable: true
          example: Director
        selectedOfficeHeld:
          type: string
          description: Office held by the person.
          nullable: true
          example: Director
        voiDetails:
          allOf:
          - $ref: '#/components/schemas/VoiDetails'
          description: Verification of identity details for this person
          nullable: true
      additionalProperties: false
      description: "Represents an authorized person for organization execution\r\n\r\nOnly supported in AU."
    DxAddressDto:
      type: object
      properties:
        number:
          type: string
          nullable: true
        exchange:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
      additionalProperties: false
    AddressDto:
      type: object
      properties:
        careOf:
          type: string
          description: Care of the addressee (if applicable).
          nullable: true
          example: John Smith
        buildingLevel:
          type: string
          description: Building level in address (if applicable).
          nullable: true
          example: Level 1
        unitNumber:
          type: string
          description: Unit number in address (if applicable).
          nullable: true
          example: '10'
        unitType:
          type: string
          description: "Unit type in address (if applicable). Accepts custom values.\r\n\r\ne.g. Apartment, Unit, Flat, Villa, Suite."
          nullable: true
          example: Suite
        streetNumber:
          type: string
          description: Street number in address.
          nullable: true
          example: '100'
        streetName:
          type: string
          description: Street name in address.
          nullable: true
          example: Broad
        streetType:
          type: string
          description: "Street type. Accepts custom values.\r\n\r\ne.g. Street, Road, Avenue, Lane."
          nullable: true
          example: Street
        addressLine1:
          type: string
          description: "First line of address.\r\n\r\nOnly supported in the US."
          nullable: true
          example: Level 1/10
        addressLine2:
          type: string
          description: "Second line of address (if applicable).\r\n\r\nOnly supported in the US."
          nullable: true
          example: 100 Broad Street
        city:
          type: string
          description: City, district, suburb, town, or village.
          nullable: true
          example: Chicago
        state:
          type: string
          description: State, province, or region.
          nullable: true
          example: IL
        zipCode:
          type: string
          description: Zip or post code.
          nullable: true
          example: '60606'
        locality:
          type: string
          description: "Locality.\r\n\r\nOnly supported in the UK."
          nullable: true
          example: Dunkirk
        county:
          type: string
          description: "County.\r\n\r\nOnly supported in the US and UK."
          nullable: true
          example: New York
        country:
          type: string
          description: Country.
          nullable: true
          example: United States
        poBox:
          allOf:
          - $ref: '#/components/schemas/PoBoxAddressDto'
          description: "PO Box details.\r\n\r\nOnly supported in AU."
          nullable: true
      additionalProperties: false
    Address:
      type: object
      properties:
        careOf:
          type: string
          description: Care of the addressee (if applicable).
          nullable: true
          example: John Smith
        buildingLevel:
          type: string
          description: Building level in address (if applicable).
          nullable: true
          example: Level 1
        unitNumber:
          type: string
          description: Unit number in address (if applicable).
          nullable: true
          example: '10'
        unitType:
          type: string
          description: "Unit type in address (if applicable). Accepts custom values.\r\n\r\ne.g. Apartment, Unit, Flat, Villa, Suite."
          nullable: true
          example: Suite
        streetNumber:
          type: string
          description: Street number in address.
          nullable: true
          example: '100'
        streetName:
          type: string
          description: Street name in address.
          nullable: true
          example: Broad
        streetType:
          type: string
          description: "Street type. Accepts custom values.\r\n\r\ne.g. Street, Road, Avenue, Lane."
          nullable: true
          example: Street
        addressLine1:
          type: string
          description: First line of address.
          nullable: true
          example: Level 1/10
        addressLine2:
          type: string
          description: Second line of address (if applicable).
          nullable: true
          example: 100 Broad Street
        city:
          type: string
          description: City, district, suburb, town, or village.
          nullable: true
          example: Chicago
        state:
          type: string
          description: State, province, or region.
          nullable: true
          example: IL
        zipCode:
          type: string
          description: Zip or post code.
          nullable: true
          example: '60606'
        locality:
          type: string
          description: "Locality.\r\n\r\nOnly supported in the UK."
          nullable: true
          example: Dunkirk
        county:
          type: string
          description: "County.\r\n\r\nOnly supported in the US and UK."
          nullable: true
          example: New York
        country:
          type: string
          description: Country.
          nullable: true
          example: United States
        poBox:
          allOf:
          - $ref: '#/components/schemas/PoBoxAddress'
          description: PO Box details (if applicable).
          nullable: true
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    GroupOfPeople:
      type: object
      properties:
        people:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          description: List of contact person hypermedia links.
          nullable: true
        residentialAddress:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: Contact group's residential address details.
          nullable: true
        mailingAddress:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: "Contact group's mailing address details.\r\n            \r\nOnly supported in the US."
          nullable: true
        name:
          type: string
          description: Names of the people in the group. Limited to the first 5 names.
          nullable: true
          example: John Smith & Jane Citizen
      additionalProperties: false
    TrustDto:
      type: object
      properties:
        name:
          type: string
          description: Trust's name.
          nullable: true
          example: Trinity Trust
        status:
          type: string
          description: "Trust's status.\r\n\r\nStandard values are: as Trustee of, as Trustees of, as Co-Trustees of, as an Individual and as Trustee of, as Successor Trustee of.\r\n\r\nA custom value can be supplied instead."
          nullable: true
          example: as Trustee of
        trustNumber:
          type: string
          description: Trust's number.
          nullable: true
          example: '12345678'
        executedDate:
          type: string
          description: Date trust was executed.
          format: date-time
          nullable: true
          example: '1980-07-01'
        phone:
          allOf:
          - $ref: '#/components/schemas/PhoneNumberDto'
          description: Trust's phone details.
          nullable: true
        fax:
          allOf:
          - $ref: '#/components/schemas/PhoneNumberDto'
          description: Trust's fax details.
          nullable: true
        address:
          allOf:
          - $ref: '#/components/schemas/AddressDto'
          description: Trust's address.
          nullable: true
        trustees:
          type: array
          items:
            $ref: '#/components/schemas/TrusteeDto'
          description: List of trustees.
          nullable: true
          example:
          - Name: John Smith
            Type: Individual
          - Name: Smithfield Steel
            Type: Company
      additionalProperties: false
    PhoneNumberDto:
      type: object
      properties:
        areaCode:
          type: string
          description: Phone area code.
          nullable: true
          example: '555'
        number:
          type: string
          description: Phone number (excluding area code).
          nullable: true
          example: '1234567'
      additionalProperties: false
    CompanyDto:
      type: object
      properties:
        name:
          type: string
          description: Company's name.
          nullable: true
          example: Brown LLC
        type:
          type: string
          description: "Company's type.\r\n\r\nPossible values for US: 'Corporation', 'Government Agency', 'Limited Liability Company', 'Sole Proprietor', 'Partnership', 'Not-for-Profit'\r\n\r\nPossible values for AU: 'Company', 'Sole Proprietor', 'Partnership', 'Government Department'\r\n\r\nPossible values for UK: 'Company', 'Sole Trader', 'Partnership', 'Limited Liability Partnership', 'Government Department'"
          nullable: true
          example: Corporation
        phone:
          allOf:
          - $ref: '#/components/schemas/PhoneNumberDto'
          description: Company's phone details.
          nullable: true
        fax:
          allOf:
          - $ref: '#/components/schemas/PhoneNumberDto'
          description: Company's fax details.
          nullable: true
        email:
          type: string
          description: Company's email address.
          nullable: true
          example: contact@brown.com
        website:
          type: string
          description: Company's website URL.
          nullable: true
          example: https://www.brownllc.com
        notes:
          type: string
          description: Additional notes for company (if applicable).
          nullable: true
          example: Recently merged with Cyberdyne Inc.
        businessAddress:
          allOf:
          - $ref: '#/components/schemas/AddressWithDxAddressDto'
          nullable: true
        mailingAddress:
          allOf:
          - $ref: '#/components/schemas/AddressDto'
          description: Only applicable for USA.
          nullable: true
        abn:
          type: string
          description: "For AU: Australian Company Number (ABN) of the company.\r\n\r\nFor UK: Company Registration Number (CRN) of the company.\r\n\r\nOnly supported in AU and UK."
          nullable: true
          example: '1234567890'
    

# --- 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