openapi: 3.0.0
info:
  title: Spruce Health API — Contact Fields
  version: 1.0.0
  description: The Contact Fields operations of the Spruce Health API, split by tag from the OpenAPI Spruce
    Health publishes for developer.sprucehealth.com (ReadMe registry @spruce/v1.0#13needamst2v4m6). Base
    https://api.sprucehealth.com/v1, Bearer organization token.
  contact:
    name: Spruce Health
    url: https://developer.sprucehealth.com
servers:
- url: https://api.sprucehealth.com/v1
  variables:
    domain:
      default: api.sprucehealth.com
security:
- spruceAPIToken: []
tags:
- name: Contact Fields
paths:
  /contacts/fields:
    get:
      description: This operation lists all organization contact fields. These fields appear on all contacts
        in the interface.
      operationId: ContactFields
      parameters:
      - description: How many tags to return at one time (max 500)
        in: query
        name: pageSize
        required: false
        schema:
          format: int32
          maximum: 500
          minimum: 1
          type: integer
      - in: query
        name: paginationToken
        required: false
        schema:
          $ref: '#/components/schemas/paginationToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  fields:
                    $ref: '#/components/schemas/contact_organizationContactFieldNames'
                  hasMore:
                    $ref: '#/components/schemas/hasMore'
                  paginationToken:
                    $ref: '#/components/schemas/paginationToken'
                  totalCount:
                    $ref: '#/components/schemas/totalCount'
                required:
                - totalCount
                - fields
                - hasMore
                type: object
          description: Expected response to a valid request
          headers:
            s-ratelimit-limit:
              $ref: '#/components/headers/s-ratelimit-limit'
            s-ratelimit-remaining:
              $ref: '#/components/headers/s-ratelimit-remaining'
            s-request-id:
              $ref: '#/components/headers/s-request-id'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: bad request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: List all organization contact fields available to the organization
      tags:
      - Contact Fields
    post:
      description: This operation creates an organization contact field for the given organization. This
        field will appear on all contacts in the interface. Requesting creation of an already existing
        field will result in a `201` response and the response will contain the existing field.
      operationId: CreateContactField
      parameters:
      - $ref: '#/components/parameters/s-idempotency-key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contact_customFieldNameContent'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact_organizationContactFieldName'
          description: created
          headers:
            s-ratelimit-limit:
              $ref: '#/components/headers/s-ratelimit-limit'
            s-ratelimit-remaining:
              $ref: '#/components/headers/s-ratelimit-remaining'
            s-request-id:
              $ref: '#/components/headers/s-request-id'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: bad request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: duplicate request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: Create an organization contact field
      tags:
      - Contact Fields
components:
  headers:
    s-ratelimit-limit:
      description: Request limit per minute
      example: 100
      schema:
        type: integer
    s-ratelimit-remaining:
      description: Requests remaining this minute
      example: 94
      schema:
        type: integer
    s-request-id:
      description: The ID of the request
      example: 0E5QDGJC030000E5QDGJC03000
      schema:
        type: string
  parameters:
    s-idempotency-key:
      description: A unique value generated by the client used to recognize subsequent retries of the
        same request. Idempotency keys can be up to 255 characters long.
      example: S7uiKYMMRzAcuG8S
      in: header
      name: s-idempotency-key
      required: false
      schema:
        type: string
  schemas:
    contact_customFieldName:
      description: A name for the field
      example: Preferred Pharmacy
      type: string
    contact_customFieldNameContent:
      properties:
        name:
          $ref: '#/components/schemas/contact_customFieldName'
      required:
      - name
      type: object
    contact_organizationContactFieldId:
      description: Spruce's contact organization contact custom field ID
      example: managedCustomField_0E5QDGJC03000
      type: string
    contact_organizationContactFieldName:
      properties:
        id:
          $ref: '#/components/schemas/contact_organizationContactFieldId'
        name:
          $ref: '#/components/schemas/contact_customFieldName'
      required:
      - id
      - name
      type: object
    contact_organizationContactFieldNames:
      description: Field names declared by the organization that can be applied to a contact
      items:
        $ref: '#/components/schemas/contact_organizationContactFieldName'
      type: array
    error:
      properties:
        message:
          example: Invalid Contact ID
          type: string
        statusCode:
          example: 400
          type: integer
        type:
          example: BAD_PARAMETER
          type: string
      required:
      - message
      - statusCode
      - type
      type: object
    hasMore:
      type: boolean
    paginationToken:
      description: Token given in a previous response to allow requesting the next page
      example: abcdefghijklmnop
      type: string
    totalCount:
      example: 750
      format: int32
      type: integer
  securitySchemes:
    spruceAPIToken:
      description: API token provided by Spruce should be passed in an "Authorization" header with the
        value "Bearer <token>"
      scheme: bearer
      type: http