openapi: 3.2.0
info:
  version: 1.0.0
  title: Encharge Custom Objects Schema API
  description: The Encharge.io API
  license:
    name: MIT
  contact:
    url: https://help.encharge.io
    name: unknown
servers:
- url: https://api.encharge.io/v1
tags:
- name: CustomObjectsSchema
paths:
  /schemas:
    get:
      operationId: GetCustomObjectsSchema
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  objects:
                    items:
                      $ref: '#/components/schemas/CustomObjectSchema'
                    type: array
                required:
                - objects
                type: object
      description: Get all custom objects.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2: []
      parameters: []
    post:
      operationId: CreateCustomObjectSchema
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  object:
                    $ref: '#/components/schemas/CustomObjectSchema'
                required:
                - object
                type: object
      description: Get custom objects counts.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2: []
      parameters: []
      requestBody:
        description: Objects to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Omit_CustomObjectSchemaCreatable.searchableFields_'
              description: Objects to add.
  /schemas/{objectName}:
    get:
      operationId: GetCustomObjectSchema
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  object:
                    $ref: '#/components/schemas/CustomObjectSchema'
                required:
                - object
                type: object
      description: Get custom object by name.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2: []
      parameters:
      - in: path
        name: objectName
        required: true
        schema:
          type: string
    patch:
      operationId: UpdateCustomObjectSchema
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  object:
                    $ref: '#/components/schemas/CustomObjectSchema'
                required:
                - object
                type: object
      description: Update custom object.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - account:write
      parameters:
      - in: path
        name: objectName
        required: true
        schema:
          type: string
      requestBody:
        description: Update data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomObjectSchemaUpdatable'
              description: Update data
    delete:
      operationId: DeleteCustomObjectSchema
      responses:
        '204':
          description: Deleted
      description: 'Remove custom object definition.


        Note that this will delete all data stored in these custom objects.'
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - account:write
      parameters:
      - in: path
        name: objectName
        required: true
        schema:
          type: string
  /schemas/{objectName}/fields:
    post:
      operationId: CreateObjectFields
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  fields:
                    items:
                      $ref: '#/components/schemas/PersonField'
                    type: array
                required:
                - fields
                type: object
      description: Create fields for Custom Object
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - personFields:write
      parameters:
      - in: path
        name: objectName
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/CustomObjectField'
              type: array
  /schemas/{objectName}/fields/{fieldName}:
    patch:
      operationId: EditObjectField
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  field:
                    $ref: '#/components/schemas/PersonField'
                required:
                - field
                type: object
      description: 'Modify field for Custom Object.


        Note: Field type and format can only be changed for People fields.'
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - personFields:write
      parameters:
      - in: path
        name: fieldName
        required: true
        schema:
          type: string
      - in: path
        name: objectName
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomObjectFieldEdit'
    delete:
      operationId: DeleteObjectField
      responses:
        '204':
          description: Deleted
      description: Delete Person Field
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - personFields:write
      parameters:
      - in: path
        name: fieldName
        required: true
        schema:
          type: string
      - in: path
        name: objectName
        required: true
        schema:
          type: string
  /schemas/associations:
    post:
      operationId: DefineCustomObjectsAssociationSchema
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  association:
                    $ref: '#/components/schemas/CustomObjectSchemaAssociation'
                required:
                - association
                type: object
      description: Define association between custom objects.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - account:write
      parameters: []
      requestBody:
        description: Association Data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomObjectSchemaAssociationCreatable'
              description: Association Data
  /schemas/associations/{id}:
    delete:
      operationId: RemoveCustomObjectsAssociationSchema
      responses:
        '204':
          description: Deleted
      description: Remove a defined association between custom objects.
      tags:
      - CustomObjectsSchema
      security:
      - oauth2:
        - account:write
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: double
          type: number
components:
  schemas:
    PersonFieldFormat:
      type:
      - string
      - 'null'
      enum:
      - date
      - date-time
      description: Format of the field. Applies to String fields only. JSON schema compatible
    PersonField:
      properties:
        name:
          type: string
          description: 'Unique ID of the field.


            Use this "name" to refer to this field in any API operations.'
        title:
          type: string
          description: Human readable name of the field.
        type:
          $ref: '#/components/schemas/Exclude_JSONSchema6TypeName.object-or-array-or-null_'
          description: Type of the field. JSON schema compatible
        format:
          $ref: '#/components/schemas/PersonFieldFormat'
          description: Format of the field. Applies to String fields only. JSON schema compatible
        displayType:
          $ref: '#/components/schemas/FieldDisplayType'
          description: 'Reserved for future use.

            How to display the field in the UI. If empty, the display will be deduced from the field type and format.'
        readOnly:
          type: boolean
          description: Whether this field can be changed by the user or via the API.
        tooltip:
          type: string
          description: More information about this field (to be shown in a tooltip)
        icon:
          type: string
          description: Field icon, if set.
        array:
          type: boolean
          description: Whether this field holds an array of values.
        enum:
          items:
            type: string
          type: array
          description: Possible values for this field
        enumNames:
          items:
            type: string
          type: array
          description: Labels for enum values. If be omitted, the enum values will be used as enum labels.
        allowNewEnumValues:
          type: boolean
          description: If we allow other values than the ones in the "enum" property.
        canMapFrom:
          type: boolean
          description: Internal
        firstClassField:
          type: boolean
          description: Internal.
        createdBy:
          type: string
          description: Internal. Field creator.
      required:
      - name
      - type
      - title
      - format
      - readOnly
      - canMapFrom
      - firstClassField
      - array
      - createdBy
      type: object
      additionalProperties: false
    CustomObjectSchema:
      properties:
        associations:
          items:
            $ref: '#/components/schemas/CustomObjectSchemaAssociation'
          type: array
        fields:
          items:
            $ref: '#/components/schemas/CustomObjectField'
          type: array
          description: The fields of the custom object
        secondaryFields:
          items:
            type: string
          type: array
          description: Designate a list of secondary field used when displaying this object.
        primaryField:
          type: string
          description: Designate a primary field used when displaying this object.
        searchableFields:
          items:
            type: string
          type: array
          description: Fields that will be indexed for searching.
        displayNamePlural:
          type: string
          description: The display name of multiple instances the custom object. E.g. "Invoices"
        displayNameSingular:
          type: string
          description: The display name of one instance the custom object. E.g. "Invoice"
        description:
          type: string
          description: Description of the custom object
        name:
          type: string
          description: The name of the custom object
      required:
      - displayNamePlural
      - displayNameSingular
      - name
      type: object
    IPersonField:
      description: Represents a field (i.e. property) of a person in Encharge.
      properties:
        name:
          type: string
          description: 'Unique ID of the field.


            Use this "name" to refer to this field in any API operations.'
        title:
          type: string
          description: Human readable name of the field.
        type:
          $ref: '#/components/schemas/Exclude_JSONSchema6TypeName.object-or-array-or-null_'
          description: Type of the field. JSON schema compatible
        format:
          $ref: '#/components/schemas/PersonFieldFormat'
          description: Format of the field. Applies to String fields only. JSON schema compatible
        displayType:
          $ref: '#/components/schemas/FieldDisplayType'
          description: 'Reserved for future use.

            How to display the field in the UI. If empty, the display will be deduced from the field type and format.'
        readOnly:
          type: boolean
          description: Whether this field can be changed by the user or via the API.
        tooltip:
          type: string
          description: More information about this field (to be shown in a tooltip)
        icon:
          type: string
          description: Field icon, if set.
        array:
          type: boolean
          description: Whether this field holds an array of values.
        enum:
          items:
            type: string
          type: array
          description: Possible values for this field
        enumNames:
          items:
            type: string
          type: array
          description: Labels for enum values. If be omitted, the enum values will be used as enum labels.
        allowNewEnumValues:
          type: boolean
          description: If we allow other values than the ones in the "enum" property.
        canMapFrom:
          type: boolean
          description: Internal
        firstClassField:
          type: boolean
          description: Internal.
        createdBy:
          type: string
          description: Internal. Field creator.
      required:
      - name
      - type
      type: object
      additionalProperties: false
    Partial_Omit_CustomObjectSchema.fields-or-associations-or-name__:
      properties:
        description:
          type: string
          description: Description of the custom object
        displayNameSingular:
          type: string
          description: The display name of one instance the custom object. E.g. "Invoice"
        displayNamePlural:
          type: string
          description: The display name of multiple instances the custom object. E.g. "Invoices"
        searchableFields:
          items:
            type: string
          type: array
          description: Fields that will be indexed for searching.
        primaryField:
          type: string
          description: Designate a primary field used when displaying this object.
        secondaryFields:
          items:
            type: string
          type: array
          description: Designate a list of secondary field used when displaying this object.
      type: object
      description: Make all properties in T optional
    CustomObjectSchemaAssociationCreatable:
      $ref: '#/components/schemas/Omit_CustomObjectSchemaAssociation.id_'
    CustomObjectSchemaAssociation:
      properties:
        type:
          type: string
          enum:
          - '1:1'
          - 1:M
          - M:M
          description: Type of the association. 1 to 1, 1 to many, many to many
        name:
          type: string
          description: Optional name of the association. E.g. if defining a relation between a Person and a Company this can be "Employee", "Owner", "Manager", etc.
        toObject:
          type: string
          description: The name of the custom object that's the other side of this association. Associations are automatically defined as two-way. I.e. there is no need to associate from -> to and to -> from.
        fromObject:
          type: string
          description: The name of the custom object that's a side to this association. Associations are automatically defined as two-way. I.e. there is no need to associate from -> to and to -> from.
        id:
          type: number
          format: double
          description: Id of the association
      required:
      - type
      - toObject
      - fromObject
      - id
      type: object
    CustomObjectSchemaUpdatable:
      $ref: '#/components/schemas/Partial_Omit_CustomObjectSchema.fields-or-associations-or-name__'
    Omit_CustomObjectSchemaAssociation.id_:
      $ref: '#/components/schemas/Pick_CustomObjectSchemaAssociation.Exclude_keyofCustomObjectSchemaAssociation.id__'
      description: Construct a type with the properties of T except for those in type K.
    Omit_CustomObjectSchemaCreatable.searchableFields_:
      $ref: '#/components/schemas/Pick_CustomObjectSchemaCreatable.Exclude_keyofCustomObjectSchemaCreatable.searchableFields__'
      description: Construct a type with the properties of T except for those in type K.
    Pick_CustomObjectSchemaAssociation.Exclude_keyofCustomObjectSchemaAssociation.id__:
      properties:
        name:
          type: string
          description: Optional name of the association. E.g. if defining a relation between a Person and a Company this can be "Employee", "Owner", "Manager", etc.
        type:
          type: string
          enum:
          - '1:1'
          - 1:M
          - M:M
          description: Type of the association. 1 to 1, 1 to many, many to many
        fromObject:
          type: string
          description: The name of the custom object that's a side to this association. Associations are automatically defined as two-way. I.e. there is no need to associate from -> to and to -> from.
        toObject:
          type: string
          description: The name of the custom object that's the other side of this association. Associations are automatically defined as two-way. I.e. there is no need to associate from -> to and to -> from.
      required:
      - type
      - fromObject
      - toObject
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    Exclude_JSONSchema6TypeName.object-or-array-or-null_:
      type: string
      enum:
      - string
      - number
      - boolean
      - integer
      - any
      description: Exclude from T those types that are assignable to U
    Pick_CustomObjectSchemaCreatable.Exclude_keyofCustomObjectSchemaCreatable.searchableFields__:
      properties:
        name:
          type: string
          description: The name of the custom object
        description:
          type: string
          description: Description of the custom object
        displayNameSingular:
          type: string
          description: The display name of one instance the custom object. E.g. "Invoice"
        displayNamePlural:
          type: string
          description: The display name of multiple instances the custom object. E.g. "Invoices"
        primaryField:
          type: string
          description: Designate a primary field used when displaying this object.
        secondaryFields:
          items:
            type: string
          type: array
          description: Designate a list of secondary field used when displaying this object.
      required:
      - name
      - displayNameSingular
      - displayNamePlural
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    Partial_Pick_CustomObjectField.title-or-tooltip-or-displayType-or-icon-or-enumNames-or-enum-or-type-or-format__:
      properties:
        title:
          type: string
          description: Human readable name of the field.
        tooltip:
          type: string
          description: More information about this field (to be shown in a tooltip)
        displayType:
          $ref: '#/components/schemas/FieldDisplayType'
          description: 'Reserved for future use.

            How to display the field in the UI. If empty, the display will be deduced from the field type and format.'
        icon:
          type: string
          description: Field icon, if set.
        enumNames:
          items:
            type: string
          type: array
          description: Labels for enum values. If be omitted, the enum values will be used as enum labels.
        enum:
          items:
            type: string
          type: array
          description: Possible values for this field
        type:
          $ref: '#/components/schemas/Exclude_JSONSchema6TypeName.object-or-array-or-null_'
          description: Type of the field. JSON schema compatible
        format:
          $ref: '#/components/schemas/PersonFieldFormat'
          description: Format of the field. Applies to String fields only. JSON schema compatible
      type: object
      description: Make all properties in T optional
    CustomObjectFieldEdit:
      $ref: '#/components/schemas/Partial_Pick_CustomObjectField.title-or-tooltip-or-displayType-or-icon-or-enumNames-or-enum-or-type-or-format__'
    FieldDisplayType:
      type: string
      enum:
      - text
      - textarea
      - date
      - datetime
      - number
      - select
      - multiselect
      - checkbox
      - radio
      - email
      - url
      - phone
      - integer
      - decimal
      - currency
      - currencyCents
    CustomObjectField:
      $ref: '#/components/schemas/IPersonField'
  securitySchemes:
    apiKeyHeader:
      description: "You can use API key authentication if you are using the API for your Encharge account. If you are building an app for others to use, please use the OAuth2 authentication below. Find your API key from https://app.encharge.io/account/info . \n\n While all operations in the API specify oauth2 security, instead you can use an API key in the header or query string."
      type: apiKey
      in: header
      name: X-Encharge-Token
    apiKeyQuery:
      description: "You can use API key authentication if you are using the API for your Encharge account. \n\nIf you are building an app for others to use, please use the OAuth2 authentication below. Find your API key from https://app.encharge.io/account/info \n\n While all operations in the API specify oauth2 security, instead you can use an API key in the header or query string."
      type: apiKey
      in: query
      name: token
    oauth2:
      type: oauth2
      description: "The Encharge API uses OAuth 2 with the authorization code flow. \n\nGet for your OAuth credentials (Client ID and Client Secret) by filling out [this form](https://research.typeform.com/to/I680YtLA)."
      flows:
        authorizationCode:
          authorizationUrl: https://api.encharge.io/v1/oauth/authorize
          tokenUrl: https://api.encharge.io/v1/oauth/token
          refreshUrl: https://api.encharge.io/v1/oauth/token
          scopes: {}