openapi: 3.2.0
info:
  description: Close CRM REST API
  title: Close Forms API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: forms
  externalDocs:
    url: https://developer.close.com/api/resources/forms
paths:
  /form/:
    get:
      operationId: forms_list
      tags:
      - forms
      summary: List Forms
      description: List all forms and their published field definitions for your organization.
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SkipParam'
      - in: query
        name: is_archived
        required: false
        description: Filter by archive status.
        schema:
          type: boolean
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - date_created: '2024-01-15T10:00:00+00:00'
                  date_updated: '2024-03-01T12:30:00+00:00'
                  field_definitions:
                  - choices: null
                    id: formfld_def456
                    name: name
                    type: text
                  - choices: null
                    id: formfld_def789
                    name: email
                    type: email
                  - choices:
                    - label: Sales
                      value: sales
                    - label: Support
                      value: support
                    id: formfld_defabc
                    name: interest
                    type: select
                  id: form_abc123
                  is_archived: false
                  name: Contact Us
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                has_more: false
              schema:
                type: object
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Form'
                    type: array
                  has_more:
                    type: boolean
                required:
                - data
                - has_more
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /form/{id}/:
    get:
      operationId: forms_fetch
      tags:
      - forms
      summary: Retrieve a Form
      description: Retrieve a single form and its published field definitions by ID.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                date_created: '2024-01-15T10:00:00+00:00'
                date_updated: '2024-03-01T12:30:00+00:00'
                field_definitions:
                - choices: null
                  id: formfld_def456
                  name: name
                  type: text
                - choices: null
                  id: formfld_def789
                  name: email
                  type: email
                - choices:
                  - label: Sales
                    value: sales
                  - label: Support
                    value: support
                  id: formfld_defabc
                  name: interest
                  type: select
                id: form_abc123
                is_archived: false
                name: Contact Us
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
              schema:
                $ref: '#/components/schemas/Form'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  parameters:
    FieldsParam:
      description: Comma-separated list of fields to include in the response.
      in: query
      name: _fields
      required: false
      schema:
        type: string
    LimitParam:
      description: Number of results to return.
      in: query
      name: _limit
      required: false
      schema:
        default: 100
        type: integer
    SkipParam:
      description: Number of results to skip before returning, for pagination.
      in: query
      name: _skip
      required: false
      schema:
        default: 0
        type: integer
  schemas:
    FormFieldChoice:
      title: FormFieldChoice
      type: object
      properties:
        label:
          title: Label
          type: string
        value:
          title: Value
          type: string
      required:
      - label
      - value
    FormFieldDefinition:
      title: FormFieldDefinition
      type: object
      properties:
        choices:
          title: Choices
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/FormFieldChoice'
          - type: 'null'
        id:
          title: ID
          type: string
        name:
          title: Name
          type: string
        type:
          title: Type
          type: string
      required:
      - choices
      - id
      - name
      - type
    Form:
      title: Form
      type: object
      properties:
        date_created:
          title: Date Created
          type: string
          format: date-time
        date_updated:
          title: Date Updated
          type: string
          format: date-time
        field_definitions:
          title: Field Definitions
          type: array
          items:
            $ref: '#/components/schemas/FormFieldDefinition'
        id:
          title: ID
          type: string
        is_archived:
          title: Is Archived
          type: boolean
        name:
          title: Name
          type: string
        organization_id:
          title: Organization ID
          type: string
      required:
      - date_created
      - date_updated
      - field_definitions
      - id
      - is_archived
      - name
      - organization_id
  securitySchemes:
    ApiKeyAuth:
      description: Use your API key as the username and leave the password empty.
      scheme: basic
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://app.close.com/oauth2/authorize/
          scopes:
            all.full_access: Full access to all resources
            offline_access: Request a refresh token
          tokenUrl: https://api.close.com/oauth2/token/
      type: oauth2