openapi: 3.2.0
info:
  title: Karbonhq Contacts API
  version: v3
  contact:
    name: API Support
    url: https://developers.karbonhq.com/issues/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://karbonhq.com/terms-of-use/
  description: 'Operations tagged Contacts across 2 of this provider''s published API definitions: KarbonAPI.json, karbonhq-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.karbonhq.com
  description: The production API server
security:
- ApiKeyAuth: []
  BearerAuth: []
tags:
- name: Contacts
  description: Manage your contacts and get the full overview over clients, whether they are individuals or organizations. Read more
paths:
  /v3/Contacts:
    get:
      tags:
      - Contacts
      summary: Gets a list of Contacts
      parameters:
      - in: query
        name: $filter
        schema:
          type: string
        examples:
          FullName:
            value: FullName eq 'Sample Management Team
            summary: Return only the Contacts where the Full Name matches 'Sample Client Team'
          EmailAddress:
            value: EmailAddress eq 'karbon@example.com'
            summary: Return only the Contacts where the Email Address matches 'karbon@example.com'
          PhoneNumber:
            value: PhoneNumber eq '220114588'
            summary: Return only the Contacts where the Phone Number matches '220114588'
          ContactType:
            value: ContactType eq 'Client'
            summary: Return only the Contacts where the Contact Type matches 'Client'
          externalKey:
            value: ExternalKey eq '123987456'
            summary: Return only the Contacts whose ExternalKey matches '123987456'. ExternalKey is the identifier from an integrated external system - XPM Client ID, Xero Contact ID, or QuickBooks Online Intuit Customer ID. Only the eq operator is supported.
        description: 'When this parameter is combined with the URI, this endpoint will return a subset of the Contacts that satisfy the `$filter` expression.

          '
      - in: query
        name: $orderby
        schema:
          type: string
          enum:
          - FullName
          - FullName desc
          - LastModifiedDateTime
          - LastModifiedDateTime desc
          default: ClientGroupKey
        example: FullName
        description: 'When this parameter is combined with the URI, this endpoint will return a list of Contacts, sorted by the available properties.

          '
      - $ref: '#/components/parameters/SkipRecords'
      - $ref: '#/components/parameters/TopRecords'
      description: 'Use the `GET` method on this endpoint to receive a paginated list of Contacts from your tenant. Using the query parameters available to this endpoint, you can also filter the list of Contacts by their full name, email address, or phone number.


        **Notes**


        This endpoint returns a maximum of 100 Contacts at once.


        If the query results in more than 100 Contacts, a link to the next set of the results will be given in the `@odata.nextLink` field of the response.


        The `$filter` query parameter supports 3 logical operators (`eq`, `contains`, and `and`) and 3 properties to help you form an expression. Usage examples below


        Logical Operators

        Purpose

        FullName

        EmailAddress

        PhoneNumber


        eq

        Full-text search

        /v3/Contacts?$filter=FullName eq ''Sample Management

        Team''

        /v3/Contacts?$filter=EmailAddress eq

        ''sample@company.com''

        /v3/Contacts?$filter=PhoneNumber eq

        ''1234567890''


        contains

        Partial-text search

        /v3/Contacts?$filter=(contains(FullName, ''Management

        Team''))

        /v3/Contacts?$filter=(contains(EmailAddress,

        ''sample@''))

        /v3/Contacts?$filter=(contains(PhoneNumber,

        ''45678''))


        and

        Combines properties

        /v3/Contacts?$filter=PhoneNumber eq

        ''1234567890'' and contains(FullName, ''Management Team'')'
      operationId: getAllContacts
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContacts'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Property:
                  $ref: '#/components/examples/Unsupported_Property_Filter'
                Unsupported Orderby Property:
                  $ref: '#/components/examples/Orderby_Unsupported_Property'
                $top limit exceeded:
                  $ref: '#/components/examples/Limit_Exceeded_Top'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    post:
      tags:
      - Contacts
      summary: Creates a new Contact
      description: Use the `POST` method on this endpoint to create a new Contact in your tenant.
      operationId: createContact
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCreateContact'
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#Contacts/KarbonService.ContactDTO/$entity
                '@odata.type': '#KarbonService.ContactDTO'
                ContactKey: 67zlxNyJSr8e
                FirstName: William
                MiddleName: John
                LastName: Connor
                PreferredName: Bill
                Salutation: Mr
                Suffix: Jr.
                ClientOwner: rodney.muller@samplecompany.com
                ClientManager: jessica.tse@samplecompany.com
                ContactType: Client
                UserDefinedIdentifier: BILLJR
                RestrictionLevel: Public
                AvatarUrl: https://az.karbonemail.com/images/e4ae96c1-8d17-4c6e-af8a-8040482176fc
                LastModifiedDateTime: '2022-07-05T07:30:13.7188114Z'
                EntityDescription:
                  Text: Birthday on June 23.
                AccountingDetail:
                  ContactPermaKey: 67zlxNyJSr8e
                  OrganizationPermaKey: null
                  BirthDate: '1969-08-05T00:00:00Z'
                  DeathDate: null
                  Salutation: Mr
                  Sex: M
                  FinancialYearEndDay: 30
                  FinancialYearEndMonth: 8
                  IncorporationDate: null
                  IncorporationState: null
                  LegalName: null
                  LineOfBusiness: null
                  EntityType: null
                  TaxCountryCode: US
                  TradingName: null
                  AnnualRevenue: null
                  BaseCurrency: null
                  GstBasis: null
                  GstPeriod: null
                  IncomeTaxInstallmentPeriod: Yearly
                  IsVATRegistered: null
                  OrganizationValuation: null
                  PaysTax: null
                  PrepareGST: null
                  ProvisionalTaxBasic: null
                  ProvisionalTaxRatio: null
                  RevenueModel: null
                  SalesTaxBasis: null
                  SalesTaxPeriod: null
                  Sells: null
                  RegistrationNumbers:
                  - RegistrationNumber: 12-3456789
                    Type: Social Security Number (SSN)
                  Notes:
                  - Body: This is a sample note text.
                    Type: Basic
                BusinessCards:
                - BusinessCardKey: 2tBHyXtJBxBy
                  EntityType: Contact
                  EntityKey: 67zlxNyJSr8e
                  IsPrimaryCard: true
                  WebSites:
                  - www.website.one
                  - www.website.two
                  EmailAddresses:
                  - sample@example.com
                  - sample.two@example.com
                  OrganizationKey: ZGNmtYyLm4z
                  RoleOrTitle: COO
                  FacebookLink: facebook.com/sampleName
                  LinkedInLink: linkedin.com/sampleName
                  TwitterLink: twitter.com/sampleName
                  SkypeLink: skype.com/sampleName
                  Addresses:
                  - AddressKey: e150a05a-2dea-4292-8bc8-03398c9384e4
                    AddressLines: 45 Sample Street
                    City: Alexandria
                    StateProvinceCounty: NSW
                    ZipCode: '2015'
                    CountryCode: AU
                    Label: Physical
                  PhoneNumbers:
                  - PhoneNumberKey: 6e0b9ace-24b1-4328-a922-3b8be5ef5052
                    Number: '1234567890'
                    CountryCode: AU
                    Label: Work
          headers:
            Location:
              description: The endpoint URL to the newly created Contact.
              schema:
                type: string
                example: https://api.karbonhq.com/v3/Contacts('9zgh8pk1dfL')/KarbonService.ContactDTO
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Incorrect or Missing Data:
                  $ref: '#/components/examples/Missing_Create_Data'
                Unsupported Property:
                  $ref: '#/components/examples/Update_Unsupported_Property'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Permission Denied:
                  $ref: '#/components/examples/RestrictionLevel_Permission_Denied'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Duplicate UDI:
                  $ref: '#/components/examples/Duplicate_UDI'
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
      requestBody:
        description: Refer to the table below for more information on each field in the request body.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
  /v3/Contacts/GetContactByUserDefinedIdentifier(UserDefinedIdentifier='{UserDefinedIdentifier}'):
    get:
      tags:
      - Contacts
      summary: Gets a Contact using UserDefinedIdentifier
      parameters:
      - required: true
        in: path
        name: UserDefinedIdentifier
        schema:
          type: string
        example: BILLJR
        description: A unique identifier that you had created to identify this Contact. This parameter is **not** case sensitive.
      - in: query
        name: $expand
        schema:
          type: string
          enum:
          - BusinessCards
          - ServiceTypes
        example: BusinessCards
        description: 'When this parameter is combined with the URI, this endpoint will also return the Business Cards or Service Types of the Contact.

          '
      description: 'Use the `GET` method on this endpoint to receive the details of a Contact specified using the UserDefinedIdentifier.


        Using the query parameter available to this endpoint, you can also include Business Card details of the Contact in the response.'
      operationId: getContactByUDI
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCreateContact'
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#Contacts/KarbonService.ContactDTO/$entity
                '@odata.type': '#KarbonService.ContactDTO'
                ContactKey: 67zlxNyJSr8e
                FirstName: William
                MiddleName: John
                LastName: Connor
                PreferredName: Bill
                Salutation: Mr
                Suffix: Jr.
                ClientOwner: rodney.muller@samplecompany.com
                ClientManager: jessica.tse@samplecompany.com
                ContactType: Client
                UserDefinedIdentifier: BILLJR
                RestrictionLevel: Public
                AvatarUrl: https://az.karbonemail.com/images/e4ae96c1-8d17-4c6e-af8a-8040482176fc
                LastModifiedDateTime: '2022-07-05T07:30:13.7188114Z'
                EntityDescription:
                  Text: Birthday on June 23.
                AccountingDetail:
                  ContactPermaKey: 67zlxNyJSr8e
                  OrganizationPermaKey: null
                  BirthDate: '1969-08-05T00:00:00Z'
                  DeathDate: null
                  Salutation: Mr
                  Sex: M
                  FinancialYearEndDay: 30
                  FinancialYearEndMonth: 8
                  IncorporationDate: null
                  IncorporationState: null
                  LegalName: null
                  LineOfBusiness: null
                  EntityType: null
                  TaxCountryCode: US
                  TradingName: null
                  AnnualRevenue: null
                  BaseCurrency: null
                  GstBasis: null
                  GstPeriod: null
                  IncomeTaxInstallmentPeriod: Quarterly
                  IsVATRegistered: null
                  OrganizationValuation: null
                  PaysTax: null
                  PrepareGST: null
                  ProvisionalTaxBasic: null
                  ProvisionalTaxRatio: null
                  RevenueModel: null
                  SalesTaxBasis: null
                  SalesTaxPeriod: null
                  Sells: null
                  RegistrationNumbers:
                  - RegistrationNumber: 12-3456789
                    Type: Social Security Number (SSN)
                  Notes:
                  - Body: This is a sample note text.
                    Type: Basic
                BusinessCards:
                - BusinessCardKey: 2tBHyXtJBxBy
                  EntityType: Contact
                  EntityKey: 67zlxNyJSr8e
                  IsPrimaryCard: true
                  WebSites:
                  - www.website.one
                  - www.website.two
                  EmailAddresses:
                  - sample@example.com
                  - sample.two@example.com
                  OrganizationKey: ZGNmtYyLm4z
                  RoleOrTitle: COO
                  FacebookLink: facebook.com/sampleName
                  LinkedInLink: linkedin.com/sampleName
                  TwitterLink: twitter.com/sampleName
                  SkypeLink: skype.com/sampleName
                  Addresses:
                  - AddressKey: e150a05a-2dea-4292-8bc8-03398c9384e4
                    AddressLines: 45 Sample Street
                    City: Alexandria
                    StateProvinceCounty: NSW
                    ZipCode: '2015'
                    CountryCode: AU
                    Label: Physical
                  PhoneNumbers:
                  - PhoneNumberKey: 6e0b9ace-24b1-4328-a922-3b8be5ef5052
                    Number: '1234567890'
                    CountryCode: AU
                    Label: Work
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                UDI Is Empty:
                  $ref: '#/components/examples/UDI_Is_Empty'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                UDI Not Found:
                  $ref: '#/components/examples/UDI_Not_Found_Contact'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
  /v3/Contacts/{Contactkey}:
    get:
      tags:
      - Contacts
      summary: Gets a Contact using Contactkey
      parameters:
      - required: true
        in: path
        name: Contactkey
        schema:
          type: string
        example: 4jgPTtcXxwC2
        description: The Karbon-generated Contact key
      - in: query
        name: $expand
        schema:
          type: string
          enum:
          - BusinessCards
          - ClientTeam
          - ClientAccess
          - ServiceTypes
        example: BusinessCards
        description: 'When this parameter is combined with the URI, this endpoint will also return one or more of the following: Business Cards for the Contact, the Client Team assigned to the Contact, a list of other Contacts that can access this Contact in Karbon for Clients, or the Service Types assigned to the Contact.'
      description: 'Use the `GET` method on this endpoint to receive the details of a Contact specified using the `Contactkey`.


        Using the query parameter available to this endpoint, you can also include the Business Card details of the Contacts in the response.'
      operationId: getContactByID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCreateContact'
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#Contacts/KarbonService.ContactDTO/$entity
                '@odata.type': '#KarbonService.ContactDTO'
                ContactKey: 67zlxNyJSr8e
                FirstName: William
                MiddleName: John
                LastName: Connor
                PreferredName: Bill
                Salutation: Mr
                Suffix: Jr.
                ClientOwner: rodney.muller@samplecompany.com
                ClientManager: jessica.tse@samplecompany.com
                ContactType: Client
                UserDefinedIdentifier: BILLJR
                RestrictionLevel: Public
                AvatarUrl: https://az.karbonemail.com/images/e4ae96c1-8d17-4c6e-af8a-8040482176fc
                LastModifiedDateTime: '2022-07-05T07:30:13.7188114Z'
                EntityDescription:
                  Text: Birthday on June 23.
                AccountingDetail:
                  ContactPermaKey: 67zlxNyJSr8e
                  OrganizationPermaKey: null
                  BirthDate: '1969-08-05T00:00:00Z'
                  DeathDate: null
                  Salutation: Mr
                  Sex: M
                  FinancialYearEndDay: 30
                  FinancialYearEndMonth: 8
                  IncorporationDate: null
                  IncorporationState: null
                  LegalName: null
                  LineOfBusiness: null
                  EntityType: null
                  TaxCountryCode: US
                  TradingName: null
                  AnnualRevenue: null
                  BaseCurrency: null
                  GstBasis: null
                  GstPeriod: null
                  IncomeTaxInstallmentPeriod: Quarterly
                  IsVATRegistered: null
                  OrganizationValuation: null
                  PaysTax: null
                  PrepareGST: null
                  ProvisionalTaxBasic: null
                  ProvisionalTaxRatio: null
                  RevenueModel: null
                  SalesTaxBasis: null
                  SalesTaxPeriod: null
                  Sells: null
                  RegistrationNumbers:
                  - RegistrationNumber: 12-3456789
                    Type: Social Security Number (SSN)
                  Notes:
                  - Body: This is a sample note text.
                    Type: Basic
                BusinessCards:
                - BusinessCardKey: 2tBHyXtJBxBy
                  EntityType: Contact
                  EntityKey: 67zlxNyJSr8e
                  IsPrimaryCard: true
                  WebSites:
                  - www.website.one
                  - www.website.two
                  EmailAddresses:
                  - sample@example.com
                  - sample.two@example.com
                  OrganizationKey: ZGNmtYyLm4z
                  RoleOrTitle: COO
                  FacebookLink: facebook.com/sampleName
                  LinkedInLink: linkedin.com/sampleName
                  TwitterLink: twitter.com/sampleName
                  SkypeLink: skype.com/sampleName
                  Addresses:
                  - AddressKey: e150a05a-2dea-4292-8bc8-03398c9384e4
                    AddressLines: 45 Sample Street
                    City: Alexandria
                    StateProvinceCounty: NSW
                    ZipCode: '2015'
                    CountryCode: AU
                    Label: Physical
                  PhoneNumbers:
                  - PhoneNumberKey: 6e0b9ace-24b1-4328-a922-3b8be5ef5052
                    Number: '1234567890'
                    CountryCode: AU
                    Label: Work
                ClientTeam:
                - MemberKey: JTphCpQqQYg
                  MemberType: User
                  RoleType: ClientOwner
                - MemberKey: nRML2ngs7WJ
                  MemberType: User
                  RoleType: ClientManager
                - MemberKey: 3fv7lflmd1Z7
                  MemberType: User
                  RoleType: UserDefinedRole2
                - MemberKey: 3v9YJmt55hLY
                  MemberType: User
                  RoleType: UserDefinedRole1
                - MemberKey: 3zdQh89xCmZM
                  MemberType: User
                  RoleType: null
                ClientAccess:
                - ClientKey: 67zlxNyJSr8e
                  ClientType: Contact
                  AccessLevel: Limited
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Property:
                  $ref: '#/components/examples/Update_Unsupported_Property'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Key Not Found:
                  $ref: '#/components/examples/ContactKey_Not_Found'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    put:
      tags:
      - Contacts
      summary: Updates a Contact (Full)
      parameters:
      - required: true
        in: path
        name: Contactkey
        schema:
          type: string
        example: 4t8LbR1QcbGS
        description: The Karbon-generated Contact key
      description: 'Use the `PUT` method on this endpoint to update full details of a Contact specified using the `Contactkey`.


        Using the query parameter `$expand` with this endpoint, you can also update the Business Card details of the Contact.


        **Note:** When updating business cards, you must include `BusinessCardKey`, `EntityType` and `EntityKey` properties for existing Business Cards - or the existing card and any associated Client Requests may be removed.


        **BusinessCards is optional:** If the `BusinessCards` array is omitted from the request body, the existing Business Cards on the Contact are left untouched. Include the `BusinessCards` array only when you intend to update it.


        **RegistrationNumber null/empty values delete the entry:** If a `RegistrationNumbers` entry is included with a null, empty, or whitespace `RegistrationNumber` value, any existing registration number of that `Type` is deleted. If no entry exists for that `Type`, the request is a no-op. Non-blank values continue to upsert as before.'
      operationId: putContactByID
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Incorrect or Missing Data:
                  $ref: '#/components/examples/Missing_Update_Data'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Permission Denied:
                  $ref: '#/components/examples/RestrictionLevel_Permission_Denied'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Key Not Found:
                  $ref: '#/components/examples/ResourceNotFound'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Non existent Key:
                  $ref: '#/components/examples/Shortened_5001'
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
        '409':
          description: Conflict — the resource was modified by another request. Refetch the latest version and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Stale Object State:
                  $ref: '#/components/examples/Conflict_StaleObjectState'
      requestBody:
        description: Refer to the table below for more information on each field in the request body.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
    patch:
      tags:
      - Contacts
      summary: Updates a Contact (Partial)
      parameters:
      - required: true
        in: path
        name: Contactkey
        schema:
          type: string
        example: 4t8LbR1QcbGS
        description: The Karbon-generated Contact key
      description: 'Use the `PATCH` method on this endpoint to update partial details of a Contact specified using the `Contactkey`.


        This method **only supports** editing the `FirstName`, `MiddleName`, `LastName`, `PreferredName`, `Salutation`, `Suffix` and `RestrictionLevel` properties.'
      operationId: patchContactsByID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: The information about Karbon controllers generating this response.
                  '@odata.type':
                    type: string
                    description: The information about Karbon Objects generating this response.
                  ContactKey:
                    type: string
                    description: A Karbon-generated value that is used to identify the Contact
                  FirstName:
                    type: string
                    description: The first name of the Contact
                  MiddleName:
                    type: string
                    description: The middle name of the Contact
                  LastName:
                    type: string
                    description: The last name of the Contact
                  PreferredName:
                    type: string
                    description: The preferred name of the Contact
                  Salutation:
                    type: string
                    description: The title to address the Contact
                  Suffix:
                    type: string
                    description: The suffix of the Contact
                  ClientOwner:
                    type: string
                    description: The team member in your firm who looks after client relationship or is responsible for the vast majority of the work of the Contact. You can only use the UserKey or the email address of an existing team member.
                  ClientManager:
                    type: string
                    description: The team member in your firm who manages the work for Contact. You can only use the UserKey or the email address of an existing team member.
                    example: jessica.tse@samplecompany.com
                  ContactType:
                    type: string
                    description: The Contact Type for this Contact. You can only use existing Contact Types, these are available from the TenantSettings endpoint.
                  UserDefinedIdentifier:
                    type: string
                    description: A unique key that you can use to identify this Contact.
                  RestrictionLevel:
                    type: string
                    description: 'The privacy level for this Client Group.


                      <ul><li>Public Client Groups can be managed by anyone in the firm</li> <li>Private Client Groups can only be managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team). Basic details (name of the Contacts and the Work Items) related to such Client Groups are visible to anyone in the firm.</li> <li>Hidden Client Groups are only be visible to and managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team).</li>

                      '
                    example: Public
                    default: Public
                    enum:
                    - Public
                    - Private
                    - Hidden
                  AvatarUrl:
                    type: string
                    description: The URL to the Contact's avatar
                  LastModifiedDateTime:
                    type: string
                    format: date-time
                    description: The date and time at which this Contact was last modified.
                  EntityDescription:
                    type: object
                    properties:
                      Text:
                        type: string
                        description: Free-form text that can be used to add more information about the Client Group
                  AccountingDetail:
                    type:
                    - string
                    - 'null'
                    description: The accounting details associated with the Contact. This property will be `null`.
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#Contacts/KarbonService.ContactDTO/$entity
                '@odata.type': '#KarbonService.ContactDTO'
                ContactKey: 67zlxNyJSr8e
                FirstName: William
                MiddleName: John
                LastName: Connor
                PreferredName: Bill
                Salutation: Mr
                Suffix: Jr.
                ClientOwner: rodney.muller@samplecompany.com
                ClientManager: jessica.tse@samplecompany.com
                ContactType: Client
                UserDefinedIdentifier: BILLJR
                RestrictionLevel: Public
                AvatarUrl: https://az.karbonemail.com/images/e4ae96c1-8d17-4c6e-af8a-8040482176fc
                LastModifiedDateTime: '2022-07-05T07:30:13.7188114Z'
                EntityDescription:
                  Text: Birthday on June 23.
                AccountingDetail: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Incorrect or Missing Data:
                  $ref: '#/components/examples/Missing_Update_Data'
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
                Invalid Property:
                  $ref: '#/components/examples/Invalid_Property'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Permission Denied:
                  $ref: '#/components/examples/RestrictionLevel_Permission_Denied'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Key Not Found:
                  $ref: '#/components/examples/ResourceNotFound'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Non existent Key:
                  $ref: '#/components/examples/Shortened_5001'
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
        '409':
          description: Conflict — the resource was modified by another request. Refetch the latest version and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Stale Object State:
                  $ref: '#/components/examples/Conflict_StaleObjectState'
      requestBody:
        description: Refer to the table below for more information on each field in the request body.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                FirstName:
                  type: string
                  description: The first name of the Contact
                  example: William
                MiddleName:
                  type: string
                  description: The middle name of the Contact
                  example: John
                LastName:
                  type: string
                  description: The last name of the Contact
                  example: Connor
                PreferredName:
                  type: string
                  description: The preferred name of the Contact
                  example: Bill
                Salutation:
                  type: string
                  description: The title to address the Contact
                  example: Mr
                Suffix:
                  type: string
                  description: The suffix of the Contact
                  example: Jr.
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
components:
  examples:
    Unsupported_option:
      description: The error returned when the query option in a request is not allowed for by the API
      value:
        error:
          code: '4002'
          message: Query option '<Option Name>' is not allowed. To allow it, set the 'AllowedQueryOptions' property on EnableQueryAttribute or QueryValidationSettings.
    Unsupported_Property_Filter:
      description: The error returned when an unsupported filter is used in a request
      value:
        error:
          code: '4002'
          message: Could not find a property named '<Property Name>' on type 'KarbonService.<KarbonEntity>SummaryDTO'.
    Missing_Update_Data:
      description: The error returned when the payload for an update is missing or invalid
      value:
        error:
          code: '4005'
          message: 'Required payload data is missing: update'
    Missing_Create_Data:
      description: The error returned when the request payload is missing a required value
      value:
        error:
          code: '4005'
          message: 'Required payload data is missing: <Entity>'
    UnauthorizedAccess:
      description: A generic response shown when the API cannot confirm the authentication creditials provided
      value:
        error:
          statusCode: '401'
          message: JWT not present.
    Shortened_5001:
      description: A response shown when the API encounters an exception
      value:
        error:
          code: '5001'
          message: Internal Error.
    Duplicate_UDI:
      description: The error returned when the request payload includes a User Defined Identifier which is already in use
      value:
        error:
          code: '5001'
          message: User defined identifier already in use
    UDI_Is_Empty:
      description: The error returned when a Client Group request cannot be fulfilled because a User Defined Identifier has not been provided
      value:
        error:
          code: '4002'
          message: UserDefinedIdentifier is missing or empty
    Orderby_Unsupported_Property:
      description: The error returned when an unsupported sort order is used in a request
      value:
        error:
          code: '4002'
          message: The property '<Property Name>' cannot be used in the $orderby query option.
    ContactKey_Not_Found:
      description: The error returned when a Contact cannot be found for the provided Contact Key
      value:
        error:
          code: '4004'
          message: No Contact found for provided key
    ResourceNotFound:
      description: A generic response shown when the API cannot find a requested path
      value:
        statusCode: '404'
        message: Resource not found
    elongated_5001:
      description: A response shown when the API encounters an exception
      value:
        error:
          code: '5001'
          message: Unexpected Internal Error. Please contact Karbon HQ Technical support with API Request Id of 63792674374107265425.
    RestrictionLevel_Permission_Denied:
      description: The error returned when a request sets RestrictionLevel to a value the calling API application does not have permission to use
      value:
        error:
          code: '4021'
          message: This API application does not have permission to set RestrictionLevel to Hidden.
    Invalid_Property:
      description: The error returned when attempting to use PATCH to update a property that can only be updated as part of a PUT
      value:
        error:
          code: '4002'
          message: Invalid property to update. Only <Property name> can be patched.
    UDI_Not_Found_Contact:
      description: The error returned when a Contact request cannot be fulfilled because the provided User Defined Identifier does not exist
      value:
        error:
          code: '4004'
          message: No Contact found for provided UserDefinedIdentifer
    Limit_Exceeded_Top:
      description: The error returned when the limit is used in a request exceeds the maximum set for the API
      value:
        error:
          code: '4002'
          message: The limit of '100' for Top query has been exceeded. The value from the incoming request is '130'.
    Conflict_StaleObjectState:
      description: The error returned when two requests race to update the same resource and the later commit is rejected by optimistic concurrency control.
      value:
        error:
          code: '4020'
          message: The resource was modified by another request. Refetch the latest version and retry.
    Update_Unsupported_Property:
      description: The error returned when attempting to update a property on an Organization other than the FullName
      value:
        error:
          code: '4002'
          message: Invalid property to update. Only FullName can be patched
  schemas:
    ResourceNotFound:
      description: A generic response shown when the API cannot find a requested entity
      type: object
      properties:
        statusCode:
          type:
          - string
          - 'null'
          description: The generic HTTP Error code
          example: '404'
        message:
          type: string
          description: The error message
          example: Resource not found
    RateLimitErrorMessage:
      description: The error message returned when the API rate limit is hit
      type: object
      properties:
        statusCode:
          type:
          - string
          - 'null'
          description: The generic HTTP Error code
          example: '429'
        message:
          type: string
          description: The error message
          example: Rate limit is exceeded. Try again in 10 seconds.
    CreateContact:
      description: A single Contact
      required:
      - FirstName
      - LastName
      type: object
      properties:
        FirstName:
          type: string
          example: William
          description: The first name of the Contact
        MiddleName:
          type: string
          example: John
          description: The middle name of the Contact
        LastName:
          type: string
          example: Connor
          description: The last name of the Contact
        PreferredName:
          type: string
          example: Bill
          description: The preferred name of the Contact
        Salutation:
          type: string
          example: Mr
          description: The title to address the Contact
        Suffix:
          type: string
          example: Jr.
          description: The suffix of the Contact
        RestrictionLevel:
          type: string
          description: 'The privacy level for this Contact.


            <ul><li>Public Contacts can be managed by anyone in the firm</li> <li>Private Contacts can only be managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team). Basic details (name of the Contacts and the Work Items) related to such Contacts are visible to anyone in the firm.</li> <li>Hidden Contacts are only be visible to and managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team).</li>

            Setting `Private` requires the calling API application to have the `IncludePrivate` permission; setting `Hidden` requires `IncludeHidden`. `Public` is always allowed. Omitting this field on a PUT leaves the existing value unchanged.

            '
          example: Public
          default: Public
          enum:
          - Public
          - Private
          - Hidden
        ClientOwner:
          type: string
          description: The team member in your firm who looks after client relationship or is responsible for the vast majority of the work of the Contact. You can only use the UserKey or the email address of an existing team member.
          example: rodney.muller@samplecompany.com
        ClientManager:
          type: string
          description: The team member in your firm who manages the work for Contact. You can only use the UserKey or the email address of an existing team member.
          example: jessica.tse@samplecompany.com
        ContactType:
          type: string
          description: The Contact Type for this Contact. You can only use existing Contact Types, these are available from the TenantSettings endpoint.
          example: Client
        UserDefinedIdentifier:
          type: string
          description: A unique key that you can use to identify this Contact.
          example: BILLJR-001
        BusinessCards:
          type: array
          items:
            $ref: '#/components/schemas/BusinessCardRequest'
        EntityDescription:
          type: object
          properties:
            Text:
              type: string
              description: Free-form text that can be used to add more information about the Client Group
              example: Birthday on June 23.
        AccountingDetail:
          $ref: '#/components/schemas/DetailsOfAccounting'
        ClientTeam:
          $ref: '#/components/schemas/ClientTeam'
    ResponseCreateContact:
      description: A single Contact
      required:
      - '@odata.context'
      - '@odata.type'
      - ContactKey
      - FirstName
      - LastName
      - RestrictionLevel
      - UserDefinedIdentifier
      type: object
      properties:
        '@odata.context':
          type: string
          description: The information about Karbon controllers generating this response.
        '@odata.type':
          type: string
          description: The information about Karbon Objects generating this response.
        ContactKey:
          type: string
          description: A Karbon-generated value that is used to identify the Contact
          example: 4t8LbR1QcbGS
        FirstName:
          type: string
          description: The first name of the Contact
          example: William
        MiddleName:
          type: string
          example: John
          description: The middle name of the Contact
        LastName:
          type: string
          example: Connor
          description: The last name of the Contact
        PreferredName:
          type: string
          example: Bill
          description: The preferred name of the Contact
        Salutation:
          type: string
          example: Mr
          description: The title to address the Contact
        Suffix:
          type: string
          example: Jr.
          description: The suffix of the Contact
        ClientOwner:
          type: string
          description: The team member in your firm who looks after client relationship or is responsible for the vast majority of the work of the Contact. You can only use the UserKey or the email address of an existing team member.
          example: rodney.muller@samplecompany.com
        ClientManager:
          type: string
          description: The team member in your firm who manages the work for Contact. You can only use the UserKey or the email address of an existing team member.
          example: jessica.tse@samplecompany.com
        ContactType:
          type: string
          description: The Contact Type for this Contact. You can only use existing Contact Types, these are available from the TenantSettings endpoint.
          example: Client
        UserDefinedIdentifier:
          type: string
          description: A unique key that you can use to identify this Contact.
          example: BILLJR
        RestrictionLevel:
          type: string
          description: 'The privacy level for this Client Group.


            <ul><li>Public Client Groups can be managed by anyone in the firm</li> <li>Private Client Groups can only be managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team). Basic details (name of the Contacts and the Work Items) related to such Client Groups are visible to anyone in the firm.</li> <li>Hidden Client Groups are only be visible to and managed by the [Client Team](https://help.karbonhq.com/en/articles/1524707-create-a-client-team).</li>

            '
          example: Public
          default: Public
          enum:
          - Public
          - Private
          - Hidden
        AvatarUrl:
          type: string
          description: The URL to the Contact's avatar
          example: https://az.karbonemail.com/images/e4ae96c1-8d17-4c6e-af8a-8040482176fc
        LastModifiedDateTime:
          type: string
          format: date-time
          description: The date and time at which this Contact was last modified.
          example: '2022-07-05T07:30:13.7188114Z'
        EntityDescription:
          type: object
          properties:
            Text:
              type: string
              description: Free-form text that can be used to add more information about the Client Group
              example: Birthday on June 23.
        AccountingDetail:
          $ref: '#/components/schemas/DetailsOfAccounting'
        BusinessCards:
          $ref: '#/components/schemas/BusinessCardsRequestAsArray'
        ClientTeam:
          $ref: '#/components/schemas/ClientTeam'
        ClientAccess:
          $ref: '#/components/schemas/ClientAccess'
    BusinessCardsRequestAsArray:
      description: A collection of business cards
      type: array
      items:
        $ref: '#/components/schemas/BusinessCardRequest'
    GetContacts:
      description: A list of Contacts
      required:
      - value
      - '@odata.context'
      - '@odata.count'
      type: object
      properties:
        '@odata.context':
          type: string
          description: The information about Karbon controllers generating this response.
          example: https://api.karbonhq.com/v3/$metadata#Contacts/KarbonService.ContactSummaryDTO
        '@odata.count':
          type: integer
          format: int64
          example: 323
          description: The total number of Contacts that satisfy the query criteria.
        value:
          type: array
          items:
            required:
            - FullName
            - LastModifiedDateTime
            - ContactKey
            - '@odata.type'
            type: object
            properties:
              '@odata.type':
                type: string
                example: '#KarbonService.ContactSummaryDTO'
                description: The information about Karbon Objects generating this response.
              ContactKey:
                type: string
                example: 29YXnqWcqCf3
                description: A Karbon-generated unique identifier for the Contact
              FullName:
                type: string
                example: William John Connor
                description: The full name of the Contact
              PreferredName:
                type: string
                example: Bill
                description: The preferred name of the Contact
              Salutation:
                type: string
                example: Mr
                description: The title to address the Contact
              ClientOwner:
                type: string
                example: rodney.muller@samplecompany.com
                description: The team member in your firm who looks after client relationship or is responsible for the vast majority of the work of the clients in this Client Group. You can only use the UserKey or the email address of an existing team member.
              ClientManager:
                type: string
                example: jessica.tse@samplecompany.com
                description: The team member in your firm who manages the work for the clients in this Client Group. You can only use the UserKey or the email address of an existing team member
              Address:
                type:
                - string
                - 'null'
                example: 42 Galaxy Way, London
                description: The Address of the Contact
              EmailAddress:
                type: string
                example: william.connor@samplecompany.com
                description: The Email Address of the Contact
              PhoneNumber:
                type:
                - string
                - 'null'
                example: 0987888686
                description: The phone number associated with the Contact
              RoleOrTitle:
                type: string
                example: COO
                description: The business role or title of the Contact
              ContactType:
                type: string
                example: Client
                description: The Contact Type for this Contact. You can only use existing Contact Types, these are available from the TenantSettings endpoint.
              UserDefinedIdentifier:
                type: string
                example: 73YEnqFcqCf3
                description: A unique key that you can use to identify this Contact.
              LastModifiedDateTime:
                type: string
                format: date-time
                description: The date and time at which the Contact was most recently modified.
                example: '2021-12-29T07:01:53Z'
        '@odata.nextLink':
          type: string
          example: https://api.karbonhq.com/v3/Contacts?$skip=100
          description: The link to next set of Contacts. @odata.nextLink field will only appear if you have more than 100 Contacts.
    ErrorMessages:
      description: The details of an error associated with an API request
      required:
      - error
      type: object
      properties:
        error:
          required:
          - code
          - message
          type: object
          properties:
            code:
              type: string
              example: '4004'
              description: A Karbon-generated code to identify the error
            message:
              type: string
              example: The record could not be found
              description: The error message
    ClientAccess:
      description: A list of Organizations and People that the contact has been granted access to view in Karbon for Clients
      readOnly: true
      type: array
      items:
        type: object
        properties:
          ClientKey:
            type: string
            example: JTphCpQqQYg
            description: The unique key of the Client
          ClientType:
            type: string
            example: Contact
            description: Whether the Client is an Organization or a Person
            enum:
            - Contact
            - Organization
          AccessLevel:
            type:
            - string
            - 'null'
            example: Limited
            description: The level of access this contact has when viewing the specified client in Karbon for Clients
            enum:
            - Limited
            - FullAccess
            - null
    DetailsOfAccounting:
      type: object
      description: The details specific to the Accounting firm related to this entity
      properties:
        ContactPermaKey:
          type:
          - string
          - 'null'
          description: A Karbon-generated key that is used to identify the Contact (if a person).
        OrganizationPermaKey:
          type:
          - string
          - 'null'
          description: A Karbon-generated key that is used to identify the Contact (if a business or an organization).
        BirthDate:
          type:
          - string
          - 'null'
          format: date-time
          description: The day at which the contact (if a person) was born.
        DeathDate:
          type:
          - string
          - 'null'
          format: date-time
          description: The day at which the contact (if a person) died.
        Salutation:
          type:
          - string
          - 'null'
          description: The title of the contact (if a person)
          enum:
          - Mr
          - Mrs
          - Ms
          - Miss
          - Dr
          - Prof
          - Rev
          - null
        Sex:
          type:
          - string
          - 'null'
          description: The gender of the contact (if a person)
          enum:
          - M
          - F
          - null
        FinancialYearEndDay:
          type:
          - integer
          - 'null'
          format: int32
          description: The day of month in which the fiscal year ends for the contact
        FinancialYearEndMonth:
          type:
          - integer
          - 'null'
          format: int32
          description: The month in which the fiscal year ends for the contact. Note that this is a 0 index value, so January is 0 and December is 11
        IncorporationDate:
          type:
          - string
          - 'null'
          format: date-time
          description: The date at which the contact (if a business or an organization) was incorporated.
        IncorporationState:
          type:
          - string
          - 'null'
          description: The state in which the contact (if a business or an organization) was incorporated.
        LegalName:
          type:
          - string
          - 'null'
          description: The legal name of the contact
        LineOfBusiness:
          type:
          - string
          - 'null'
          description: The industry this contact is associated with.
        EntityType:
          type:
          - string
          - 'null'
          description: The entity type of the contact (if a business or an organization)
          enum:
          - Corporation
          - Club or Society
          - Estate or Trust
          - Exempt Organization
          - Partnership
          - Private Foundation
          - S Corporation
          - Person
          - Sole Proprietor
          - Limited Liability
          - Charitable Incorporated Organisation
          - Company Limited by Guarantee
          - Community Interest Company
          - Limited Liability Partnership
          - Local Authority
          - Non Departmental Public Body
          - Pension Scheme
          - Royal Charter
          - Unincorporated Association
          - Other/None
          - null
        TaxCountryCode:
          type:
          - string
          - 'null'
          description: The code of the country where the contact pays their tax.
          enum:
          - US
          - AU
          - UK
          - NZ
          - CA
          - ZA
          - HK
          - FR
          - SG
          - IE
          - SE
          - FI
          - DK
          - 'NO'
          - IN
          - CH
          - null
        TradingName:
          type:
          - string
          - 'null'
          description: The trading name of the contact (if a business or an organization)
        AnnualRevenue:
          type:
          - number
          - 'null'
          format: decimal
          description: The total annual revenue generated by the contact
        BaseCurrency:
          type:
          - string
          - 'null'
          description: The 3-letter code, denoting the currency of annual revenue
        GstBasis:
          type:
          - string
          - 'null'
          description: The method of accounting for GST/BAS
          enum:
          - Cash
          - Accruals
          - None
          - Close
          - null
        GstPeriod:
          type:
          - string
          - 'null'
          description: The GST period
        IncomeTaxInstallmentPeriod:
          type:
          - string
          - 'null'
          description: The income tax installment period
          enum:
          - Monthly
          - Quarterly
          - Yearly
          - null
        IsVATRegistered:
          type:
          - boolean
          - 'null'
          description: Set to true if the business or organization is registered for VAT
        OrganizationValuation:
          type:
          - number
          - 'null'
          format: decimal
          description: The present value of the company
        PaysTax:
          type:
          - boolean
          - 'null'
          description: Set to true, if the contact has to pay tax
        PrepareGST:
          type:
          - boolean
          - 'null'
          description: <>
        ProvisionalTaxBasic:
          type:
          - string
          - 'null'
          description: <>
        ProvisionalTaxRatio:
          type:
          - string
          - 'null'
          description: <>
        RevenueModel:
          type:
          - string
          - 'null'
          description: The revenue model of the business or organization
          enum:
          - Advertising
          - Commission
          - E-Commerce
          - Fee for Service
          - Licensing
          - Markup
          - Production
          - Subscription
          - null
        SalesTaxBasis:
          type:
          - string
          - 'null'
          description: The tax method
          enum:
          - Cash
          - Accruals
          - None
          - Close
          - null
        SalesTaxPeriod:
          type:
          - string
          - 'null'
          description: The tax period
        Sells:
          type:
          - string
          - 'null'
          description: The item that is primarily supplied by the company
          enum:
          - Services
          - Products
          - Products and Services
          - Other
          - null
        DateSignedEngagement:
          type:
          - string
          - 'null'
          format: date-time
          description: ''
        Bank:
          type: array
          description: A user definable list of banks the client uses
          items:
            type: string
            example: Commonwealth Bank
        Payroll:
          type: array
          description: A user definable list of payroll services the client uses
          items:
            type: string
            example: ''
        BillPay:
          type: array
          description: A user definable list of bill payment services the client uses
          items:
            type: string
            example: ''
        Benefits:
          type: array
          description: A user definable list of benefits services the client uses
          items:
            type: string
            example: ''
        Revenue:
          type: array
          description: A user definable list of revenue management services the client uses
          items:
            type: string
            example: ''
        Expenses:
          type: array
          description: A user definable list of expense management services the client uses
          items:
            type: string
            example: ''
        FileManagement:
          type: array
          description: A user definable list of file management services the client uses
          items:
            type: string
            example: SharePoint
        Accounting:
          type: array
          description: A user definable list of accounting tools and services the client uses
          items:
            type: string
            example: QuickBooks Online
        RegistrationNumbers:
          type: array
          description: The registration numbers associated with the contact.
          items:
            required:
            - RegistrationNumber
            - Type
            type: object
            properties:
              RegistrationNumber:
                type: string
                description: The registration number
                maxLength: 50
              Type:
                type: string
                description: The type of registration
                enum:
                - Australian Business Number (ABN)
                - Australian Company Number (ACN)
                - Tax File Number (TFN)
                - Social Security Number (SSN)
                - Tax ID
                - VAT Number
                - Company Registration Number
                - PAYE Reference Number
                - PAYE Accounts Office Reference
                - CT Reference
                - Unique Taxpayer Reference (UTR)
                - NZ Business Number
                - GST Number
                - IRD Number
                - Business Number
                - Social Insurance Number (SIN)
                - Registration Number
                - Income Tax Number
                - PAYE Number
                - DOL UIF Number
                - SDL Number
                - DOL Workman Compensation
                - Company Number
                - Business Registration Number
                - Charity Number
                - MPF provider
                - RCS
                - SIRET
                - UEN
                - RCT Reference
                - Companies Office Number
                - KUND ID
                - Organisation Number
                - Finnish Business ID
                - CVR Number
                - GST Identification Number (GSTIN)
                - Permanent Account Number (PAN)
        LegalFirm:
          description: The legal firm(s) that represent the client, these can be strings or references to Karbon organizations
          type:
          - object
          - 'null'
          properties:
            Name:
              type: string
              example: Polygon Legal
              description: The name of the legal firm that represents the client
            OrganizationKey:
              type:
              - string
              - 'null'
              description: The Organization key of the Karbon organization client record
              example: 4cYDk82rZDRn
        TaxProvider:
          description: The provider of tax services to the client, these can be strings or references to Karbon organizations
          type:
          - object
          - 'null'
          properties:
            Name:
              type: string
              example: Orbit Tax
              description: The name of the tax provider
            OrganizationKey:
              type:
              - string
              - 'null'
              description: The optional Organization key of the Tax Provider client record in Karbon
              example: null
        Notes:
          type: array
          items:
            required:
            - Body
            - Type
            type: object
            properties:
              Body:
                type: string
                description: The free-form text in the note
              Type:
                type: string
                description: The section (within the accounting details) where the note resides
                enum:
                - Basic
                - Tax
                - System
                - Owner
                - Officer
    ClientTeam:
      description: The Client Team associated with a contact or organization
      type: array
      items:
        type: object
        properties:
          MemberKey:
            type: string
            example: JTphCpQqQYg
            description: The unique key of the user or team assigned to the client team role
          MemberType:
            type: string
            example: User
            description: The type of member assigned to the client team, can be either User or Team
            enum:
            - User
            - Team
          RoleType:
            type:
            - string
            - 'null'
            example: ClientOwner
            description: The specific role the user or team is assigned to, can be null if a member of the client team without a specific role
            enum:
            - ClientOwner
            - ClientManager
            - UserDefinedRole1
            - UserDefinedRole2
            - null
    BusinessCardRequest:
      description: A business card associated with a contact or organization
      type: object
      properties:
        BusinessCardKey:
          type: string
          description: A Karbon-generated unique identifier for the Business Card
          example: ''
          required: true
        EntityType:
          type: string
          description: The type of entity this Business Card belongs to.
          example: Contact
          enum:
          - Contact
          - Organization
          - ClientGroup
        EntityKey:
          type: string
          description: A Karbon-generated key to indicate the entity (Contact, Organization, or ClientGroup) this Business Card belongs to.
          example: 67zlxNyJSr8e
        IsPrimaryCard:
          type: boolean
          description: Set to true, if this business card is also the primary business card for this entity.
          example: true
        OrganizationKey:
          type:
          - string
          - 'null'
          description: Used on the Business Card for a Contact to specify the Organization that the Contact is related to. Will always be null for an Organization business card.
          example: 7NN1ySxv89B
        WebSites:
          description: The websites associated with this Business card.
          type: array
          items:
            type: string
          example:
          - www.website.one
          - www.website.two
        EmailAddresses:
          description: The email addresses associated with this Business card.
          type: array
          items:
            type: string
          example:
          - sample@example.com
          - sample.two@example.com
        RoleOrTitle:
          type:
          - string
          - 'null'
          description: The business role or title of the contact this Business Cards belongs to
          example: COO
        FacebookLink:
          type: string
          description: The URL to the entity's Facebook profile
          example: facebook.com/sampleName
        LinkedInLink:
          type: string
          description: The URL to the entity's LinkedIn profile
          example: linkedin.com/sampleName
        TwitterLink:
          type: string
          description: The URL to the entity's Twitter profile
          example: twitter.com/sampleName
        SkypeLink:
          type: string
          description: The URL to the entity's Skype profile
          example: skype.com/sampleName
        Addresses:
          type: array
          items:
            type: object
            properties:
              AddressLines:
                type: string
                description: Street Address
                example: 45 Sample Street
                maxLength: 200
              City:
                type: string
                description: City
                example: Alexandria
                maxLength: 100
              StateProvinceCounty:
                type: string
                description: State / Province / County
                example: NSW
                maxLength: 100
              ZipCode:
                type: string
                description: ZipCode / PostCode
                example: '2015'
                maxLength: 20
              CountryCode:
                type: string
                format: ISO 3166-1 alpha-2
                description: Two letter Country Code
                example: AU
              Label:
                type: string
                description: The tag to indicate the type of Address
                example: Physical
                enum:
                - Physical
                - Mailing
                - Legal
                - Home
        PhoneNumbers:
          type: array
          items:
            type: object
            properties:
              Number:
                type: string
                description: The phone number of the entity
                example: '1234567890'
                maxLength: 20
              CountryCode:
                type: string
                description: The phone number country code
                example: AU
              Label:
                type: string
                description: The tag to indicate the type of phone number
                example: Work
                enum:
                - Work
                - Mobile
                - Office
                - Fax
                - Home
                - Other
  parameters:
    SkipRecords:
      in: query
      name: $skip
      schema:
        type: integer
        minimum: 0
        maximum: 100
      example: 50
      description: Skip the first n items
    TopRecords:
      in: query
      name: $top
      schema:
        type: integer
        minimum: 0
      example: 10
      description: Limit the number of items returned
  securitySchemes:
    BearerAuth:
      description: The Application ID for your API application, supplied by secure message when your Application is first registered
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      description: The AccessKey for your API application, found inside the Settings > Connected Apps section in Karbon
      type: apiKey
      in: header
      name: AccessKey
externalDocs:
  description: Karbon Developers - API release notes
  url: https://developers.karbonhq.com/release-notes/
x-refined-from:
- KarbonAPI.json
- karbonhq-openapi.yml