Ometria Custom Fields API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Custom Fields API
  description: 'Welcome to the Ometria API reference.


    The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.


    ### HTTPS


    All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.


    ### Message encoding


    The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.


    ### Rate limits


    The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.


    In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.'
  contact:
    name: Ometria
    email: support@ometria.com
    url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Custom Fields
paths:
  /custom_fields:
    get:
      tags:
      - Custom Fields
      summary: List Custom Fields
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldCategory'
          description: Filter for custom fields in the given category.
          title: Category
        description: Filter for custom fields in the given category.
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldType'
          description: Filter for custom fields of the given type.
          title: Type
        description: Filter for custom fields of the given type.
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldStatus'
          description: Filter for custom fields with the given status.
          title: Status
        description: Filter for custom fields with the given status.
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          description: Search for custom fields with the given label or id.
          title: Search
        description: Search for custom fields with the given label or id.
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldSortBy'
          description: Sort custom fields by the given field.
          title: Sort By
        description: Sort custom fields by the given field.
      responses:
        '200':
          description: The list of custom fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              example:
                detail: Invalid request.
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server error.
          content:
            application/json:
              example:
                detail: Internal Server error.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getCustomFields
      x-operation-id-source: derived
    post:
      tags:
      - Custom Fields
      summary: Create Custom Field
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCreate'
      responses:
        '200':
          description: The created custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              example:
                detail: Invalid request.
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server error.
          content:
            application/json:
              example:
                detail: Internal Server error.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postCustomFields
      x-operation-id-source: derived
    put:
      tags:
      - Custom Fields
      summary: Update Custom Field
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldUpdate'
      responses:
        '200':
          description: The updated custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              example:
                detail: Invalid request.
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '404':
          description: No custom field with the provided id and category found
          content:
            application/json:
              example:
                detail: Custom field with id 'example_id' not found in category 'contact'.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error.
          content:
            application/json:
              example:
                detail: Internal Server error.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: putCustomFields
      x-operation-id-source: derived
  /custom_fields/{category}/{id}:
    delete:
      tags:
      - Custom Fields
      summary: Delete Custom Field
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: category
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/CustomFieldCategory'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid request.
          content:
            application/json:
              example:
                detail: Invalid request.
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '404':
          description: No custom field with the provided id and category found
          content:
            application/json:
              example:
                detail: Custom field with id 'example_id' not found in category 'contact'.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error.
          content:
            application/json:
              example:
                detail: Internal Server error.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deleteCustomFieldsByCategoryById
      x-operation-id-source: derived
components:
  schemas:
    CustomFieldStatus:
      type: string
      enum:
      - active
      - archived
      title: CustomFieldStatus
    CustomFieldCategory:
      type: string
      enum:
      - contact
      - order
      title: CustomFieldCategory
    CustomFieldCreate:
      properties:
        id:
          type: string
          maxLength: 64
          pattern: ^\S+$
          title: Id
          description: The identifier of the custom field
          example: country_of_origin
        category:
          $ref: '#/components/schemas/CustomFieldCategory'
          description: The category of the custom field
          example: contact
        type:
          $ref: '#/components/schemas/CustomFieldType'
          description: The type of the custom field. The 'date' type can only be used with the 'contact' category.
          example: string
        title:
          type: string
          maxLength: 64
          title: Title
          description: The title of the custom field
          example: Custom Field
      additionalProperties: false
      type: object
      required:
      - id
      - category
      - type
      - title
      title: CustomFieldCreate
    CustomFieldType:
      type: string
      enum:
      - string
      - integer
      - decimal
      - date
      - blob
      - list of string
      - list of product ids
      title: CustomFieldType
    ValidationErrorResponse:
      properties:
        detail:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ValidationErrorDetailItem'
            type: array
          title: Detail
          description: The detail(s) giving more context why the request failed.
      additionalProperties: false
      type: object
      required:
      - detail
      title: ValidationErrorResponse
    CustomFieldResponse:
      properties:
        id:
          type: string
          maxLength: 64
          pattern: ^\S+$
          title: Id
          description: The identifier of the custom field
          example: country_of_origin
        category:
          $ref: '#/components/schemas/CustomFieldCategory'
          description: The category of the custom field
          example: contact
        type:
          $ref: '#/components/schemas/CustomFieldType'
          description: The type of the custom field. The 'date' type can only be used with the 'contact' category.
          example: string
        title:
          type: string
          maxLength: 64
          title: Title
          description: The title of the custom field
          example: Custom Field
        status:
          $ref: '#/components/schemas/CustomFieldStatus'
          description: The status of the custom field
          example: active
        date_created:
          anyOf:
          - type: string
            format: date-time
          title: Date Created
          description: The date the custom field was created
          example: '2024-07-15T11:45:13+00:00'
        created_by:
          anyOf:
          - type: integer
          title: Created By
          description: The user who created the custom field
          example: 1
      additionalProperties: false
      type: object
      required:
      - id
      - category
      - type
      - title
      - status
      - date_created
      - created_by
      title: CustomFieldResponse
    CustomFieldListResponse:
      properties:
        fields:
          items:
            $ref: '#/components/schemas/CustomFieldResponse'
          type: array
          title: Fields
          description: The list of paginated objects.
        offset:
          type: integer
          minimum: 0.0
          title: Offset
          description: The offset value applied for pagination.
          example: 0
        page_size:
          type: integer
          minimum: 0.0
          title: Page Size
          description: The actual number of objects in the current page.
          example: 1
        total_count:
          type: integer
          minimum: 0.0
          title: Total Count
          description: The total number of objects for the account.
          example: 1
        limit:
          type: integer
          minimum: 1.0
          title: Limit
          description: The limit number of custom fields allowed
          example: 50
      additionalProperties: false
      type: object
      required:
      - fields
      - offset
      - page_size
      - total_count
      - limit
      title: CustomFieldListResponse
    ValidationErrorDetailItem:
      properties:
        type:
          type: string
          title: Type
          description: The type of validation error.
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Loc
          description: The location of the field that caused the validation error.
        msg:
          type: string
          title: Msg
          description: The error message.
        input:
          anyOf:
          - type: string
          title: Input
          description: The input in the request that caused the validation error.
      additionalProperties: false
      type: object
      required:
      - type
      - loc
      - msg
      title: ValidationErrorDetailItem
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: The detail giving more context why the request failed.
      additionalProperties: false
      type: object
      required:
      - detail
      title: ErrorResponse
    CustomFieldUpdate:
      properties:
        id:
          type: string
          maxLength: 64
          pattern: ^\S+$
          title: Id
          description: The identifier of the custom field
          example: country_of_origin
        category:
          $ref: '#/components/schemas/CustomFieldCategory'
          description: The category of the custom field
          example: contact
        title:
          anyOf:
          - type: string
            maxLength: 64
          title: Title
          description: The title of the custom field
          example: Custom Field
        status:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldStatus'
          description: The status of the custom field
          example: active
      additionalProperties: false
      type: object
      required:
      - id
      - category
      title: CustomFieldUpdate
    CustomFieldSortBy:
      type: string
      enum:
      - created_by
      - -created_by
      - date_created
      - -date_created
      - category
      - -category
      - type
      - -type
      - status
      - -status
      - id
      - -id
      - title
      - -title
      title: CustomFieldSortBy
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: Ometria API key which can be obtained from your Ometria account administrator
    apiKeyReadTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
    apiKeyWriteTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
  proxy-enabled: true
  samples-enabled: true