openapi: 3.2.0
info:
  title: Karbonhq Business Cards 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 Business Cards 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: Business Cards
  description: View or update the Business Card attached to a Contact and/or Organization
paths:
  /v3/BusinessCards/{BusinessCardKey}:
    get:
      operationId: getBusinessCardByKey
      tags:
      - Business Cards
      summary: Gets a single Business Card
      parameters:
      - required: true
        in: path
        name: BusinessCardKey
        example: 2tBHyXtJBxBy
        schema:
          type: string
        description: The Karbon-generated Business Card key
      description: Use the `GET` method on this endpoint to receive the details of a Business Card specified using the BusinessCardKey.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    '@odata.context':
                      type: string
                      example: https://api.karbonhq.com/v3/$metadata#BusinessCards/$entity
                      description: The information about Karbon controllers generating this response.
                - type: object
                  properties:
                    EntityType:
                      type: string
                      example: Organization
                      enum:
                      - Contact
                      - Organization
                      - ClientGroup
                      description: The type of entity that this business card is connected to.
                    EntityKey:
                      type: string
                      example: 2jHPZngklwxQ
                      description: The unique key for the entity specified this business card is connected to
                - $ref: '#/components/schemas/BusinessCard'
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#BusinessCards/$entity
                '@odata.type': '#KarbonService.ClientGroupDTO'
                BusinessCardKey: 2tBHyXtJBxBy
                EntityType: Organization
                EntityKey: 2jHPZngklwxQ
                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
        '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/BusinessCard_Not_Found'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
    put:
      operationId: updateBusinessCardByKey
      tags:
      - Business Cards
      summary: Updates a single Business Card
      parameters:
      - required: true
        in: path
        name: BusinessCardKey
        schema:
          type: string
        example: 2tBHyXtJBxBy
        description: The Karbon-generated Business Card key
      description: Use the `PUT` method on this endpoint to update the details of a Business Card specified using the BusinessCardKey.
      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'
        '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:
              allOf:
              - type: object
                properties:
                  EntityType:
                    type: string
                    example: Organization
                    enum:
                    - Contact
                    - Organization
                    - ClientGroup
                    description: The type of entity that this business card is connected to.
                  EntityKey:
                    type: string
                    example: 2jHPZngklwxQ
                    description: The unique key for the entity specified this business card is connected to
              - $ref: '#/components/schemas/BusinessCardRequest'
    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.
    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.
    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.
    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'
    BusinessCard_Not_Found:
      description: The error returned when a Business Card request cannot be fulfilled because the provided Business Card Key does not exist
      value:
        error:
          code: '4004'
          message: Invalid businessCardPermaKey <BusinessCardKey>
    Shortened_5001:
      description: A response shown when the API encounters an exception
      value:
        error:
          code: '5001'
          message: Internal Error.
    UnauthorizedAccess:
      description: A generic response shown when the API cannot confirm the authentication creditials provided
      value:
        error:
          statusCode: '401'
          message: JWT not present.
  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.
    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
    BusinessCard:
      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: 2tBHyXtJBxBy
        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
        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
        OrganizationKey:
          type: string
          description: A Karbon-generated key to indicate the organization this Business Card belongs to
          example: ZGNmtYyLm4z
        RoleOrTitle:
          type: string
          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:
              AddressKey:
                type: string
                description: A randomly generated GUID to indicate the address details
                example: e150a05a-2dea-4292-8bc8-03398c9384e4
              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:
              PhoneNumberKey:
                type: string
                description: A randomly generated GUID to indicate the phone details
                example: 6e0b9ace-24b1-4328-a922-3b8be5ef5052
              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
    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
  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