openapi: 3.0.1
info:
  title: Respond.io Developer Comments Custom Fields API
  description: REST API for the respond.io omnichannel customer-conversation management platform. Manage contacts, send and read messages across connected channels, open and close conversations, assign users, post internal comments, manage tags and custom fields, and configure webhooks. Requests and responses are JSON. Contacts are addressed by an identifier of the form `id:{id}`, `email:{email}`, or `phone:{phone}`.
  termsOfService: https://respond.io/terms-and-conditions
  contact:
    name: Respond.io Support
    url: https://developers.respond.io/
  version: '2.0'
servers:
- url: https://api.respond.io/v2
security:
- bearerAuth: []
tags:
- name: Custom Fields
  description: Structured contact metadata definitions.
paths:
  /custom_field:
    get:
      operationId: listCustomFields
      tags:
      - Custom Fields
      summary: List custom fields
      description: Lists all custom field definitions in the workspace.
      responses:
        '200':
          description: A list of custom fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createCustomField
      tags:
      - Custom Fields
      summary: Create a custom field
      description: Creates a new custom field definition.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomField'
      responses:
        '200':
          description: Custom field created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
    CustomField:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
          - text
          - number
          - date
          - list
          - checkbox
          - url
        options:
          type: array
          items:
            type: string
          description: Allowed values when type is list.
  responses:
    RateLimited:
      description: Too many requests. Limited to 5 requests per second per method.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Access Token from Settings > Integrations > Developer API, sent in the Authorization header as `Bearer {token}`.