openapi: 3.2.0
info:
  title: Karbonhq Custom Fields 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 Custom Fields 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: Custom Fields
  description: Endpoints to manage Custom Fields on Contacts and Organizations in Karbon, refer to the Karbon help and support content for more information on creating custom fields and frequently asked questions
paths:
  /v3/CustomFields:
    get:
      tags:
      - Custom Fields
      description: Retrieve a list of all of the custom fields that have been created for a Karbon account
      summary: Gets all custom field definitions for the current tenant
      operationId: GetCustomFieldDefinitions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDefinitions'
              example:
                Key: ZGNmtYyLm4z
                Name: Industry Type
                Type: Text
                IsVisibleToContacts: true
                IsVisibleToOrganizations: true
                ListOptions: []
    post:
      tags:
      - Custom Fields
      description: Defines a new custom field that can be assigned to a Contact and/or Organization - use the Karbon UI to create examples of how a new field with specific list options should be created
      summary: Creates a new custom field definition
      operationId: CreateCustomFieldDefinition
      responses:
        '201':
          description: Custom field definition successfully created
          headers:
            Location:
              description: Location of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDefinition'
              example:
                Key: ZGNmtYyLm4z
                Name: Industry Type
                Type: Text
                IsVisibleToContacts: true
                IsVisibleToOrganizations: true
                ListOptions: []
        '400':
          description: Incoming Model is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/NotFound'
        '500':
          description: Error processing Request
      requestBody:
        description: The payload sent to create a new Custom Field
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldDefinition'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
  /v3/CustomFields/{CustomFieldDefinitionKey}:
    delete:
      tags:
      - Custom Fields
      description: Delete a custom field defintion by key
      summary: Deletes a custom field definition by key
      operationId: DeleteCustomFieldDefinition
      parameters:
      - name: CustomFieldDefinitionKey
        in: path
        description: The key of the custom field definition to delete
        required: true
        schema:
          type: string
        example: ZGNmtYyLm4z
      responses:
        '204':
          description: Custom field definition successfully deleted
        '404':
          description: Custom field definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/NotFound'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
  /v3/CustomFieldValues/{EntityKey}:
    get:
      tags:
      - Custom Fields
      description: Retrieves the custom fields for a Contact or Organization
      summary: Gets custom field values for a specific entity
      operationId: GetCustomFieldValues
      parameters:
      - name: EntityKey
        in: path
        description: The key to get custom field values for a Contact or Organization
        required: true
        schema:
          type: string
        example: Lm4zGNmtYyZ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValues'
              example:
                EntityKey: ZGNmtYyLm4z
                CustomFieldValues:
                - Key: ZGNGtYyLm4z
                  Name: Industry Type
                  Type: Text
                  Value:
                  - Professional Services
                - Key: AFNGtYyLm4z
                  Name: Revenue
                  Type: Number
                  Value:
                  - '1000000'
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/NotFound'
    put:
      tags:
      - Custom Fields
      description: Performs an update of the complete set of custom field values for a Contact or Organization
      summary: Updates custom field values for a specific entity
      operationId: UpdateCustomFieldValues
      parameters:
      - name: EntityKey
        in: path
        description: The key to get custom field values for a Contact or Organization
        required: true
        schema:
          type: string
        example: Lm4zGNmtYyZ
      responses:
        '204':
          description: Custom field values successfully updated
          content: {}
        '400':
          description: Invalid custom field values or entity key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Bad Request:
                  $ref: '#/components/examples/Bad_Request_Update_Custom_Field_Values'
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/NotFound'
        '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: The payload sent when updating the custom fields on a Contact or Organization
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldValues'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
components:
  examples:
    Bad_Request_Update_Custom_Field_Values:
      description: There is an issue with the data or structure of the request that must be fixed before the request can be processed
      value:
        error:
          code: '4002'
          message: Only one value allowed for type Text
    NotFound:
      description: A generic response shown when the API cannot find a requested entity
      value:
        error:
          code: '4004'
          message: Not Found
    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.
  schemas:
    CustomFieldValues:
      type: object
      description: The set custom fields for a contact or organization and the associated values and options
      properties:
        EntityKey:
          type: string
          example: Lm4zGNmtYyZ
        CustomFieldValues:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
    CustomFieldDefinition:
      type: object
      description: The structure that defines a Custom Field in Karbon
      properties:
        Name:
          type: string
          example: Industry Type
          maxLength: 100
        Type:
          type: string
          example: ListSingleSelect
          enum:
          - Text
          - Number
          - Date
          - Boolean
          - Colleague
          - ListSingleSelect
          - ListMultipleSelect
        IsVisibleToContacts:
          type: boolean
          example: true
        IsVisibleToOrganizations:
          type: boolean
          example: false
        ListOptions:
          descriptions: A value or values assigned to the Custom Field, note that all values for all types are strings - this includes `number` and `boolean` types
          type: array
          items:
            type: string
            maxLength: 256
            examples:
            - Agriculture
            - Manufacturing
            - Professional, Scientific and Technical Services
    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
    CustomFieldDefinitions:
      type: object
      description: A list of the available custom fields in Karbon
      properties:
        '@odata.context':
          type: string
          example: https://api.karbonhq.com/v3/$metadata#CustomFields
        '@odata.count':
          type: number
          format: int32
          example: 3
        value:
          type: array
          items:
            allOf:
            - type: object
              properties:
                Key:
                  type: string
                  example: ZGNmtYyLm4z
                  required: true
            - $ref: '#/components/schemas/CustomFieldDefinition'
    CustomFieldValue:
      type: object
      description: A collection of Custom Fields
      properties:
        Key:
          type: string
          example: ZGNGtYyLm4z
        Name:
          type: string
          example: Industry Type
          maxLength: 100
        Type:
          type: string
          example: ListSingleSelect
          enum:
          - Text
          - Number
          - Date
          - Boolean
          - Colleague
          - ListSingleSelect
          - ListMultipleSelect
        Value:
          type: array
          items:
            type: string
            maxLength: 256
            example: Professional Services
  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