Fintary

Fintary AMS API

Agency Management System REST API covering the policy, customer and agent record core — policy detail, status changes, teams, tasks, commission breakdown and the two-phase document repository upload; customer CRUD, summaries and bulk update; agent CRUD, contracts, hierarchy and full upline/downline tree; task management and escalation; custom-field and status configuration; and a page-config/capabilities registry that publishes bindable fields, widget vocabulary and an endpoint allowlist for AI and wire clients. Sixty operations under `/api/ams/` on api.fintary.com, authenticated with an HTTP bearer token.

GitHub OpenAPI

Documentation

📖
APIReference
https://api.fintary.com/api-doc
📖
Documentation
https://api.fintary.com/documentation

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/openapi/fintary-ams-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/overlays/fintary-ams-api-overlay.yaml

OpenAPI Specification

fintary-ams-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  title: Fintary AMS API documentation
  version: '1.0'
tags:
- name: AMS - Policies
  description: Policy management endpoints
- name: AMS - Customers
  description: Customer management endpoints
- name: AMS - Agents
  description: Agent management endpoints
- name: AMS - Configs
  description: AMS configuration endpoints (statuses, roles)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
  schemas:
    AgentDetailResponseSchema:
      type: object
      properties:
        strId:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        agentCode:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        geoState:
          type: string
          nullable: true
        startDate:
          type: string
          nullable: true
        endDate:
          type: string
          nullable: true
        userStrId:
          type: string
          nullable: true
        middleName:
          type: string
          nullable: true
        nickname:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        birthday:
          type: string
          nullable: true
        phoneType:
          type: string
          nullable: true
        phone2:
          type: string
          nullable: true
        phone2Type:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        payableStatus:
          type: string
          nullable: true
        payoutLevel:
          type: string
          nullable: true
        brokerCommPayTo:
          type: string
          nullable: true
        gaFieldRep:
          type: string
          nullable: true
        gaRepresentative:
          type: string
          nullable: true
        qbVendor:
          type: string
          nullable: true
        street:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        hierarchy:
          type: array
          items:
            type: object
            properties:
              parentContactStrId:
                type: string
              parentContactName:
                type: string
                nullable: true
              relationship:
                type: string
            required:
            - parentContactStrId
            - parentContactName
            - relationship
        policies:
          type: array
          items:
            type: object
            properties:
              strId:
                type: string
              policyId:
                type: string
                nullable: true
              policyStatus:
                type: string
                nullable: true
              customerName:
                type: string
                nullable: true
              role:
                type: string
              premiumAmount:
                type: string
                nullable: true
            required:
            - strId
            - policyId
            - policyStatus
            - customerName
            - role
            - premiumAmount
        customers:
          type: array
          items:
            type: object
            properties:
              strId:
                type: string
                nullable: true
              firstName:
                type: string
                nullable: true
              lastName:
                type: string
                nullable: true
              companyName:
                type: string
                nullable: true
              relationshipType:
                type: string
            required:
            - strId
            - firstName
            - lastName
            - companyName
            - relationshipType
        commissionProfiles:
          type: array
          items:
            type: object
            properties:
              strId:
                type: string
              profileName:
                type: string
                nullable: true
              rate:
                type: string
                nullable: true
              method:
                type: string
                nullable: true
            required:
            - strId
            - profileName
            - rate
            - method
        contracts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              companyId:
                type: string
              company:
                type: object
                nullable: true
                properties:
                  id:
                    type: string
                  companyName:
                    type: string
                    nullable: true
                  companyId:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  phone:
                    type: string
                    nullable: true
                  website:
                    type: string
                    nullable: true
                  address:
                    type: string
                    nullable: true
                required:
                - id
                - companyName
                - companyId
                - email
                - phone
                - website
                - address
              canonicalCompany:
                type: object
                nullable: true
                properties:
                  id:
                    type: string
                  companyName:
                    type: string
                    nullable: true
                  companyId:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  phone:
                    type: string
                    nullable: true
                  website:
                    type: string
                    nullable: true
                  address:
                    type: string
                    nullable: true
                required:
                - id
                - companyName
                - companyId
                - email
                - phone
                - website
                - address
              contractLevel:
                type: string
                nullable: true
              licenseNumber:
                type: string
                nullable: true
              status:
                type: string
                nullable: true
              effectiveDate:
                type: string
                nullable: true
            required:
            - id
            - companyId
            - contractLevel
            - licenseNumber
            - status
            - effectiveDate
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - strId
      - firstName
      - lastName
      - name
      - email
      - phone
      - agentCode
      - status
      - level
      - type
      - companyName
      - geoState
      - startDate
      - endDate
      - userStrId
      - middleName
      - nickname
      - title
      - gender
      - birthday
      - phoneType
      - phone2
      - phone2Type
      - externalId
      - notes
      - payableStatus
      - payoutLevel
      - brokerCommPayTo
      - gaFieldRep
      - gaRepresentative
      - qbVendor
      - street
      - city
      - country
      - zip
      - hierarchy
      - policies
      - customers
      - commissionProfiles
      - createdAt
      - updatedAt
    AgentHierarchyNodeSchema:
      type: object
      properties:
        strId:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        agentCode:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        splitPercentage:
          type: number
          nullable: true
        hierarchyId:
          type: string
          nullable: true
        children:
          type: array
          items:
            $ref: '#/components/schemas/AgentHierarchyNodeSchema'
      required:
      - strId
      - firstName
      - lastName
      - name
      - email
      - agentCode
      - level
      - splitPercentage
      - hierarchyId
      - children
    AgentHierarchyResponseSchema:
      type: object
      properties:
        strId:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        agentCode:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        uplines:
          type: array
          items:
            $ref: '#/components/schemas/AgentHierarchyNodeSchema'
        downlines:
          type: array
          items:
            $ref: '#/components/schemas/AgentHierarchyNodeSchema'
      required:
      - strId
      - firstName
      - lastName
      - name
      - email
      - agentCode
      - level
      - uplines
      - downlines
    AgentListItemSchema:
      type: object
      properties:
        strId:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        agentCode:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        policyCount:
          type: integer
        customerCount:
          type: integer
        companyName:
          type: string
          nullable: true
        geoState:
          type: string
          nullable: true
        startDate:
          type: string
          nullable: true
        endDate:
          type: string
          nullable: true
        middleName:
          type: string
          nullable: true
        nickname:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        birthday:
          type: string
          nullable: true
        phoneType:
          type: string
          nullable: true
        phone2:
          type: string
          nullable: true
        phone2Type:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        payableStatus:
          type: string
          nullable: true
        payoutLevel:
          type: string
          nullable: true
        brokerCommPayTo:
          type: string
          nullable: true
        gaFieldRep:
          type: string
          nullable: true
        gaRepresentative:
          type: string
          nullable: true
        qbVendor:
          type: string
          nullable: true
        street:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        createdAt:
          type: string
      required:
      - strId
      - firstName
      - lastName
      - name
      - email
      - phone
      - agentCode
      - status
      - level
      - policyCount
      - customerCount
      - companyName
      - geoState
      - startDate
      - endDate
      - middleName
      - nickname
      - title
      - gender
      - birthday
      - phoneType
      - phone2
      - phone2Type
      - externalId
      - notes
      - payableStatus
      - payoutLevel
      - brokerCommPayTo
      - gaFieldRep
      - gaRepresentative
      - qbVendor
      - street
      - city
      - country
      - zip
      - createdAt
    AgentListResponseSchema:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentListItemSchema'
        pagination:
          $ref: '#/components/schemas/AmsPaginationSchema'
      required:
      - data
      - pagination
    AgentSummaryResponseSchema:
      type: object
      properties:
        total:
          type: integer
        active:
          type: integer
        writingAgents:
          type: integer
        salesReps:
          type: integer
      required:
      - total
      - active
      - writingAgents
      - salesReps
    AgentTreeNodeSchema:
      type: object
      properties:
        strId:
          type: string
        name:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        agentCode:
          type: string
        level:
          type: string
        splitPercentage:
          type: number
        depth:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/AgentTreeNodeSchema'
        parentContactId:
          type: string
      required:
      - strId
      - depth
      - children
    AgentTreeResponseSchema:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/AgentTreeNodeSchema'
        ancestors:
          type: array
          items:
            $ref: '#/components/schemas/AgentTreeNodeSchema'
        descendants:
          type: array
          items:
            $ref: '#/components/schemas/AgentTreeNodeSchema'
      required:
      - ancestors
      - descendants
    AmsAgentContractPathParamsSchema:
      type: object
      properties:
        strId:
          type: string
          minLength: 1
        contractId:
          type: string
          minLength: 1
      required:
      - strId
      - contractId
    AmsAgentListQuerySchema:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          default: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        search:
          type: string
        sortBy:
          type: string
        sortOrder:
          type: string
          enum:
          - asc
          - desc
          default: desc
        status:
          type: string
        role:
          type: string
        email:
          type: string
        agentCode:
          type: string
        level:
          type: string
        createdFrom:
          type: string
        createdTo:
          type: string
      required:
      - page
      - pageSize
      - sortOrder
    AmsAgentPathParamsSchema:
      type: object
      properties:
        strId:
          type: string
          minLength: 1
      required:
      - strId
    AmsAgentTreeQuerySchema:
      type: object
      properties:
        strId:
          type: string
          minLength: 1
        effectiveDate:
          type: string
      required:
      - strId
    AmsBindableFieldSchema:
      allOf:
      - $ref: '#/components/schemas/AmsFilterFieldSchema'
      properties:
        source:
          type: string
          enum:
          - static
          - customField
      required:
      - source
    AmsBulkUpdateAgentDataSchema:
      type: object
      properties:
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        phone:
          type: string
          nullable: true
        agentCode:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        geoState:
          type: string
          nullable: true
        startDate:
          type: string
          nullable: true
        endDate:
          type: string
          nullable: true
        userStrId:
          type: string
          nullable: true
    AmsBulkUpdateAgentsBodySchema:
      type: object
      properties:
        strIds:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
        data:
          $ref: '#/components/schemas/AmsBulkUpdateAgentDataSchema'
      required:
      - strIds
      - data
    AmsBulkUpdateCustomerDataSchema:
      type: object
      properties:
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        middleName:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        phone:
          type: string
          nullable: true
        dob:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
          enum:
          - male
          - female
          - null
        type:
          type: string
          nullable: true
          enum:
          - individual
          - group
          - null
        status:
          type: string
          nullable: true
        parentId:
          type: integer
          nullable: true
        acquisitionChannel:
          type: string
          nullable: true
        primaryAddressStrId:
          type: string
          nullable: true
    AmsBulkUpdateCustomersBodySchema:
      type: object
      properties:
        strIds:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
        data:
          $ref: '#/components/schemas/AmsBulkUpdateCustomerDataSchema'
      required:
      - strIds
      - data
    AmsBulkUpdatePoliciesBodySchema:
      type: object
      properties:
        strIds:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
        data:
          $ref: '#/components/schemas/AmsBulkUpdatePolicyDataSchema'
      required:
      - strIds
      - data
    AmsBulkUpdatePolicyDataSchema:
      type: object
      properties:
        policyId:
          type: string
          nullable: true
        policyStatus:
          type: string
          nullable: true
        caseStatus:
          type: string
          nullable: true
        customerId:
          type: integer
          nullable: true
        productName:
          type: string
          nullable: true
        productType:
          type: string
          nullable: true
        productSubType:
          type: string
          nullable: true
        writingCarrierName:
          type: string
          nullable: true
        effectiveDate:
          type: string
          nullable: true
        expirationDate:
          type: string
          nullable: true
        premiumAmount:
          type: number
          nullable: true
        commissionablePremiumAmount:
          type: number
          nullable: true
        paymentMode:
          type: string
          nullable: true
        geoState:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
    AmsBulkUpdateResponseSchema:
      type: object
      properties:
        totalUpdated:
          type: integer
      required:
      - totalUpdated
    AmsCapabilitiesResponseSchema:
      type: object
      properties:
        bindableFields:
          type: array
          items:
            $ref: '#/components/schemas/AmsBindableFieldSchema'
        widgetVocabulary:
          $ref: '#/components/schemas/AmsWidgetVocabularySchema'
        endpoints:
          type: array
          items:
            type: string
        limits:
          $ref: '#/components/schemas/AmsLimitsSchema'
        schemaVersion:
          type: number
        etag:
          type: string
      required:
      - bindableFields
      - widgetVocabulary
      - endpoints
      - limits
      - schemaVersion
      - etag
    AmsContractListQuerySchema:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
        search:
          type: string
        sortBy:
          type: string
        sortOrder:
          type: string
          enum:
          - asc
          - desc
        status:
          type: string
    AmsContractStatusSchema:
      type: string
      enum:
      - active
      - inactive
    AmsCreateAgentSchema:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        agentCode:
          type: string
        status:
          type: string
        level:
          type: string
        type:
          type: string
        companyName:
          type: string
        geoState:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        userStrId:
          type: string
        hierarchy:
          type: array
          items:
            type: object
            properties:
              parentContactStrId:
                type: string
                minLength: 1
              relationship:
                type: string
            required:
            - parentContactStrId
        commissionProfiles:
          type: array
          items:
            type: object
            properties:
              profileId:
                type: integer
              rate:
                type: number
              method:
                type: string
              startDate:
                type: string
              endDate:
                type: string
            required:
            - profileId
    AmsCreateContractSchema:
      type: object
      properties:
        companyId:
          type: string
          minLength: 1
        contractLevel:
          type: string
        licenseNumber:
          type: string
        status:
          $ref: '#/components/schemas/AmsContractStatusSchema'
        effectiveDate:
          type: string
        endDate:
          type: string
        notes:
          type: string
      required:
      - companyId
    AmsCreateCustomFieldDefinitionSchema:
      type: object
      properties:
        entityType:
          type: string
          minLength: 1
        fieldKey:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        dataType:
          type: string
          enum:
          - text
          - number
          - boolean
          - date
          - json
        isRequired:
          type: boolean
          default: false
        isSearchable:
          type: boolean
          default: false
        isFilterable:
          type: boolean
          default: false
        isReportable:
          type: boolean
          default: false
        validationRulesJson:
          type: string
          nullable: true
        defaultValue:
          type: string
          nullable: true
        enumOptionsJson:
          type: string
          nullable: true
        sortOrder:
          type: integer
          default: 0
      required:
      - entityType
      - fieldKey
      - displayName
      - dataType
      - isRequired
      - isSearchable
      - isFilterable
      - isReportable
      - sortOrder
    AmsCreateCustomerSchema:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        middleName:
          type: string
        companyName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        dob:
          type: string
        gender:
          type: string
          enum:
          - male
          - female
          - other
        type:
          type: string
          enum:
          - individual
          - group
        status:
          type: string
        parentId:
          type: integer
        acquisitionChannel:
          type: string
        primaryAddressStrId:
          type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/AmsCustomerAddressSchema'
        owners:
          type: array
          items:
            type: object
            properties:
              contactStrId:
                type: string
                minLength: 1
              relationshipType:
                type: string
                minLength: 1
            required:
            - contactStrId
            - relationshipType
    AmsCreateMyTaskSchema:
      type: object
      properties:
        title:
          type: string
          minLength: 1
        targetAudience:
          type: string
          enum:
          - agent
          - account
          - policy
          - customer
          - case
        targetId:
          type: string
          minLength: 1
        status:
          type: string
          default: pending
        assigneeUids:
          type: array
          items:
            type: string
            minLength: 1
        notes:
          type: string
        priority:
          type: string
          enum:
          - urgent
          - high
          - medium
          - low
          default: medium
        dueDate:
          type: string
          minLength: 1
        type:
          type: string
          enum:
          - document
          - general
          - missing_requirement
          - need_document
          - status_update
          - new_note
          default: general
      required:
      - title
      - targetAudience
      - targetId
      - status
      - priority
      - type
    AmsCreatePolicyDocumentSchema:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        fileName:
          type: string
          minLength: 1
        mimeType:
          type: string
          minLength: 1
        fileSize:
          type: integer
          minimum: 0
        expiryDate:
          type: string
      required:
      - name
      - fileName
      - mimeType
    AmsCreatePolicySchema:
      type: object
      properties:
        policyId:
          type: string
        policyStatus:
          type: string
        caseStatus:
          type: string
        customerId:
          type: integer
        productName:
          type: string
        productType:
          type: string
        productSubType:
          type: string
        productOptionName:
          type: string
        writingCarrierName:
          type: string
        effectiveDate:
          type: string
        expirationDate:
          type: string
        signedDate:
          type: string
        policyDate:
          type: string
        cancellationDate:
          type: string
        reinstatementDate:
          type: string
        firstPaymentDate:
          type: string
        firstProcessedDate:
          type: string
        premiumAmount:
          type: number
        commissionablePremiumAmount:
          type: number
        excessAmount:
          type: number
        commissionsExpected:
          type: number
        customerPaidPremiumAmount:
          type: number
        splitPercentage:
          type: number
        paymentMode:
          type: string
        policyTermMonths:
          type: integer
        geoState:
          type: string
        notes:
          type: string
        dba:
          type: string
        internalId:
          type: string
        transactionType:
          type: string
        accountType:
          type: string
        groupId:
          type: string
        groupName:
          type: string
        aggregationId:
          type: string
        aggregationPrimary:
          type: boolean
        type:
          type: string
        documentId:
          type: string
        processingStatus:
          type: string
        commissionProfileId:
          type: string
        syncId:
          type: string
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/AmsCustomFieldValueInputSchema'
    AmsCreatePolicyTaskSchema:
      type: object
      properties:
        title:
          type: string
          minLength: 1
        status:
          type: string
          default: in_progress
        assigneeUids:
          type: array
          items:
            type: string
            minLength: 1
        notes:
          type: string
        priority:
          type: string
          enum:
          - urgent
          - high
          - medium
          - low
          default: medium
        dueDate:
          type: string
          minLength: 1
      required:
      - title
      - status
      - priority
      - dueDate
    AmsCustomFieldDefinitionSchema:
      type: object
      properties:
        id:
          type: string
        strId:
          type: string
        entityType:
          type: string
        fieldKey:
          type: string
        displayName:
          type: string
        dataType:
          type: string
          nullable: true
          enum:
          - text
          - number
          - boolean
          - date
          - json
          - null
        isRequired:
          type: boolean
        isSearchable:
          type: boolean
        isFilterable:
          type: boolean
        isReportable:
          type: boolean
        validationRulesJson:
          type: string
          nullable: true
        defaultValue:
          type: string
          nullable: true
        enumOptionsJson:
          type: string
          nullable: true
        sortOrder:
          type: integer
      required:
      - strId
      - entityType
      - fieldKey
      - displayName
      - dataType
      - isRequired
      - isSearchable
      - isFilterable
      - isReportable
      - validationRulesJson
      - defaultValue
      - enumOptionsJson
      - sortOrder
    AmsCustomFieldListQuerySchema:
      type: object
      properties:
        entityType:
          type: string
    AmsCustomFieldValueInputSchema:
      type: object
      properties:
        fieldDefinitionId:
          type: string
          minLength: 1
        valueText:
          type: string
          nullable: true
        valueNumber:
          type: number
          nullable: true
        valueBoolean:
          type: boolean
          nullable: true
        valueDate:
          type: string
          nullable: true
        valueJson:
          type: string
          nullable: true
      required:
      - fieldDefinitionId
    AmsCustomFieldValueSchema:
      type: object
      properties:
        fieldDe

# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/openapi/fintary-ams-api-openapi.yml