> ## Documentation Index
> Fetch the complete documentation index at: https://docs.younegotiate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Tilled application

> Validate and save the creditor company's Tilled application. First-time full applications are stored with an encrypted onboarding payload and queued for background Tilled processing. Companies with an already completed Tilled profile only submit bank-account updates synchronously.



## OpenAPI

````yaml /api/creditor.openapi.yaml post /merchant-settings/tilled
openapi: 3.1.0
info:
  title: YouNegotiate Creditor API
  version: '2.0'
  description: >-
    Stateless API endpoints for creditor portal authentication and account
    access.
servers:
  - url: https://api.creditor.younegotiate.com
    description: Production
security: []
tags:
  - name: System
    description: Public creditor domain system and health endpoints.
  - name: Authentication
    description: Creditor registration, login, password, and email verification endpoints.
  - name: Account Settings
    description: >-
      Authenticated creditor profile, contact, operating-hours, and
      profile-image endpoints.
  - name: Account Profile
    description: >-
      Creditor onboarding profile, membership, billing, and setup status
      endpoints.
  - name: Setup Wizard
    description: >-
      Creditor setup wizard status, required-step completion, and optional-step
      completion.
  - name: Dashboard
    description: Creditor dashboard work queues and performance widgets.
  - name: Import / Export
    description: >-
      Creditor consumer import upload sessions, queued imports, history,
      downloads, and failed-row files.
  - name: Membership Settings
    description: >-
      Creditor membership dashboard, plan changes, payment method, cancellation,
      special-plan inquiry, and over-limit retry endpoints.
  - name: Merchant Account
    description: >-
      Existing merchant processor credentials, Tilled onboarding, and merchant
      application endpoints.
  - name: Header Profiles
    description: >-
      CSV header profile upload, mapping, download, and setup wizard completion
      endpoints.
  - name: SFTP Connections
    description: >-
      Creditor-managed SFTP connection profiles for imports, exports, and setup
      wizard completion.
  - name: Sub Accounts
    description: >-
      Creditor-managed sub account list, export, create, update, and delete
      endpoints.
  - name: Pay Terms Offers
    description: >-
      Creditor-managed master, sub-account, group, and group-sub-account Pay
      Terms endpoints.
  - name: Individual Custom Offers
    description: Creditor individual custom offer list endpoints.
  - name: Negotiations
    description: >-
      Creditor negotiation work queues, including notice responses and offer
      review counts.
  - name: Communications / CFPB Validation Letter
    description: >-
      CFPB Validation Letter tables, secure EcoLetter send/resend, CSV export,
      and print/download actions.
  - name: Communications / EcoLetter Template
    description: >-
      Creditor EcoLetter template management for secure eLetter communications
      and campaigns.
  - name: Communications / Groups
    description: >-
      Creditor communication group management for dynamic consumer targeting and
      campaign selection.
  - name: Communications / Schedule Campaign
    description: >-
      Creditor EcoLetter campaign scheduling, quote, immediate send, and
      delivery queue endpoints.
  - name: Communications / Campaign Tracker
    description: >-
      Creditor campaign tracker reporting, refresh, and consumer export
      endpoints.
  - name: Consumer Profiles
    description: Creditor Consumer Profiles list, filter options, and CSV export endpoints.
  - name: Terms & Conditions
    description: Creditor-managed master and sub-account Terms & Conditions templates.
  - name: About Us & Contact
    description: Creditor-managed company About Us content shown to consumers.
  - name: Logo & Links
    description: >-
      Creditor-managed master and sub-account personalized logo colors, size,
      and consumer link metadata.
  - name: Users
    description: >-
      Master creditor user management, invitations, and account deletion
      endpoints.
paths:
  /merchant-settings/tilled:
    post:
      tags:
        - Merchant Account
      summary: Submit Tilled application
      description: >-
        Validate and save the creditor company's Tilled application. First-time
        full applications are stored with an encrypted onboarding payload and
        queued for background Tilled processing. Companies with an already
        completed Tilled profile only submit bank-account updates synchronously.
      operationId: creditorSubmitTilledApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitTilledApplicationRequest'
            example:
              legal_name: ABC Collections LLC
              dba_name: ABC Collections
              structure: limited_liability_company
              fed_tax_id: '123456789'
              date_of_incorporation: '2020-01-15'
              website: https://abc-collections.example
              support_phone: '2125550100'
              support_email: support@abc-collections.example
              address: 100 Main Street
              address2: Suite 200
              country: US
              state: NY
              city: New York
              zip: '10001'
              first_name: Jane
              middle_name: ''
              last_name: Admin
              dob: '1985-05-20'
              ssn: '123456789'
              job_title: owner
              percent_ownership: 100
              owner_phone: '2125550100'
              owner_email: jane.admin@example.com
              principle_address: 100 Main Street
              principle_address2: Suite 200
              principle_country: US
              principle_state: NY
              principle_city: New York
              principle_zip: '10001'
              years_at_address: 3
              company_category: '7322'
              high_ticket_amount: 5000
              average_transaction_amount_card: 500
              monthly_transaction_count: 100
              account_holder_name: ABC Collections LLC
              bank_name: Example Bank
              bank_account_type: checking
              bank_account_number: '1234567890'
              bank_routing_number: '021000021'
              industry_type: LLC
              tos_acceptance: true
      responses:
        '200':
          description: Tilled application submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TilledApplicationSubmitResponse'
              examples:
                queued_full_application:
                  summary: First-time full application queued
                  value:
                    message: >-
                      Merchant application submitted. We will continue
                      processing it in the background.
                    data:
                      is_profile_completed: false
                      requires_full_profile: true
                      has_actionable_document_requests: false
                      form:
                        legal_name: ABC Collections LLC
                        website: https://abc-collections.example
                        bank_account_number: '90'
                        ssn: ''
                      options: {}
                bank_update:
                  summary: Completed profile bank update submitted
                  value:
                    message: Tilled bank account update submitted.
                    data:
                      is_profile_completed: true
                      requires_full_profile: false
                      has_actionable_document_requests: false
                      form:
                        legal_name: ABC Collections LLC
                        account_holder_name: ABC Collections LLC
                        bank_account_number: '90'
                        ssn: ''
                      options: {}
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/ActiveMembershipRequired'
        '422':
          description: >-
            Validation failed, or the synchronous bank-account update for a
            completed Tilled profile was rejected.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TilledApplicationSubmitResponse'
                  - $ref: '#/components/schemas/ValidationErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    SubmitTilledApplicationRequest:
      type: object
      required:
        - legal_name
        - structure
        - fed_tax_id
        - date_of_incorporation
        - website
        - support_phone
        - support_email
        - address
        - state
        - city
        - zip
        - first_name
        - last_name
        - dob
        - job_title
        - percent_ownership
        - owner_phone
        - owner_email
        - principle_address
        - principle_country
        - principle_state
        - principle_city
        - principle_zip
        - years_at_address
        - company_category
        - high_ticket_amount
        - average_transaction_amount_card
        - monthly_transaction_count
        - bank_account_type
        - bank_account_number
        - bank_routing_number
        - tos_acceptance
      properties:
        legal_name:
          type: string
          minLength: 2
          maxLength: 100
        dba_name:
          type: string
          minLength: 2
          maxLength: 100
          nullable: true
        structure:
          type: string
          enum:
            - community_interest_company
            - corporation
            - government
            - limited_liability_company
            - limited_liability_partnership
            - non_profit
            - partnership
            - sole_proprietorship
            - trust
        fed_tax_id:
          type: string
          pattern: ^\d{9}$
        date_of_incorporation:
          type: string
          format: date
        website:
          type: string
          format: uri
        support_phone:
          type: string
          maxLength: 20
        support_email:
          type: string
          format: email
          maxLength: 100
        address:
          type: string
          maxLength: 100
        address2:
          type: string
          maxLength: 100
          nullable: true
        country:
          type: string
          enum:
            - US
            - CA
          nullable: true
        state:
          type: string
          minLength: 2
          maxLength: 2
        city:
          type: string
          maxLength: 30
        zip:
          type: string
          maxLength: 10
        first_name:
          type: string
          minLength: 2
          maxLength: 20
        middle_name:
          type: string
          maxLength: 20
          nullable: true
        last_name:
          type: string
          minLength: 2
          maxLength: 30
        dob:
          type: string
          format: date
        ssn:
          type: string
          pattern: ^\d{9}$
          description: Required unless structure is government.
        job_title:
          type: string
          enum:
            - chief_executive_officer
            - co_owner
            - controller
            - director
            - financial_officer
            - general_manager
            - general_partner
            - limited_partner
            - manager
            - member
            - owner
            - president
            - secretary
            - treasurer
            - senior_vice_president
            - vice_president
        percent_ownership:
          type: integer
          minimum: 1
          maximum: 100
        owner_phone:
          type: string
          maxLength: 20
        owner_email:
          type: string
          format: email
          maxLength: 100
        principle_address:
          type: string
          maxLength: 100
        principle_address2:
          type: string
          maxLength: 100
          nullable: true
        principle_country:
          type: string
          enum:
            - US
            - CA
        principle_state:
          type: string
          minLength: 2
          maxLength: 2
        principle_city:
          type: string
          maxLength: 30
        principle_zip:
          type: string
          maxLength: 10
        years_at_address:
          type: integer
          minimum: 1
          maximum: 99
        additional_address:
          type: string
          minLength: 2
          maxLength: 100
          nullable: true
        additional_address2:
          type: string
          maxLength: 100
          nullable: true
        additional_country:
          type: string
          enum:
            - US
            - CA
          nullable: true
        additional_state:
          type: string
          nullable: true
          minLength: 2
          maxLength: 2
        additional_city:
          type: string
          minLength: 2
          maxLength: 30
          nullable: true
        additional_zip:
          type: string
          nullable: true
          maxLength: 10
        company_category:
          type: string
          enum:
            - '4119'
            - '7389'
            - '8011'
            - '6012'
            - '6051'
            - '8398'
            - '8099'
            - '8062'
            - '6300'
            - '8050'
            - '8049'
            - '9311'
            - '6513'
            - '5999'
            - '7322'
            - '4814'
            - '7549'
            - '4900'
            - '0742'
        high_ticket_amount:
          type: integer
          minimum: 1
        average_transaction_amount_card:
          type: integer
          minimum: 1
        monthly_transaction_count:
          type: integer
          minimum: 1
        account_holder_name:
          type: string
          minLength: 2
          maxLength: 50
          nullable: true
        bank_name:
          type: string
          minLength: 2
          maxLength: 50
          nullable: true
        bank_account_type:
          type: string
          enum:
            - checking
            - savings
        bank_account_number:
          type: string
          pattern: ^\d{4,17}$
        bank_routing_number:
          type: string
          pattern: ^\d{9}$
        industry_type:
          type: string
          enum:
            - CHARITY
            - CIC
            - CORP
            - LTD
            - LLC
            - LLP
            - NPCORP
            - PARTNERSHIP
            - PLC
            - GOV
            - SOLEPROP
            - TRUST
          nullable: true
        tos_acceptance:
          type: boolean
          description: Must be accepted.
    TilledApplicationSubmitResponse:
      type: object
      required:
        - message
        - data
      properties:
        message:
          type: string
          example: >-
            Merchant application submitted. We will continue processing it in
            the background.
        data:
          $ref: '#/components/schemas/TilledApplication'
    ValidationErrorResponse:
      type: object
      required:
        - message
        - errors
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    TilledApplication:
      type: object
      required:
        - is_profile_completed
        - requires_full_profile
        - has_actionable_document_requests
        - form
        - options
      properties:
        is_profile_completed:
          type: boolean
        requires_full_profile:
          type: boolean
          description: >-
            When true, the full business, owner, transaction, and bank sections
            must be submitted.
        has_actionable_document_requests:
          type: boolean
        form:
          $ref: '#/components/schemas/TilledApplicationForm'
        options:
          $ref: '#/components/schemas/TilledApplicationOptions'
    MessageResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    TilledApplicationForm:
      type: object
      additionalProperties: true
      properties:
        legal_name:
          type: string
        dba_name:
          type: string
        structure:
          type: string
        fed_tax_id:
          type: string
        date_of_incorporation:
          type: string
          format: date
          description: >-
            Business incorporation date. The backend accepts parseable date
            input and stores it as `YYYY-MM-DD`.
        website:
          type: string
        support_phone:
          type: string
        support_email:
          type: string
          format: email
        address:
          type: string
        address2:
          type: string
        country:
          type: string
        state:
          type: string
        city:
          type: string
        zip:
          type: string
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        dob:
          type: string
          format: date
          description: >-
            Principal date of birth. The backend accepts parseable date input
            and stores it as `YYYY-MM-DD`.
        ssn:
          type: string
          description: Empty in responses.
        job_title:
          type: string
        percent_ownership:
          oneOf:
            - type: integer
            - type: string
        owner_phone:
          type: string
        owner_email:
          type: string
          format: email
        principle_address:
          type: string
        principle_address2:
          type: string
        principle_country:
          type: string
        principle_state:
          type: string
        principle_city:
          type: string
        principle_zip:
          type: string
        years_at_address:
          oneOf:
            - type: integer
            - type: string
        additional_address:
          type: string
        additional_address2:
          type: string
        additional_country:
          type: string
        additional_state:
          type: string
        additional_city:
          type: string
        additional_zip:
          type: string
        company_category:
          type: string
        high_ticket_amount:
          oneOf:
            - type: integer
            - type: string
        average_transaction_amount_card:
          oneOf:
            - type: integer
            - type: string
        monthly_transaction_count:
          oneOf:
            - type: integer
            - type: string
        account_holder_name:
          type: string
        bank_name:
          type: string
        bank_account_type:
          type: string
        bank_account_number:
          type: string
          description: Response contains the stored masked value.
        bank_routing_number:
          type: string
        industry_type:
          type: string
        tos_acceptance:
          type: boolean
    TilledApplicationOptions:
      type: object
      additionalProperties: true
      properties:
        bank_account_types:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        company_categories:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        countries:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        industry_types:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        job_titles:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        structures:
          type: array
          items:
            $ref: '#/components/schemas/Option'
    Option:
      type: object
      additionalProperties: true
      properties:
        value:
          oneOf:
            - type: string
            - type: integer
        label:
          type: string
  responses:
    Unauthenticated:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
    ActiveMembershipRequired:
      description: Authenticated creditor does not have an active membership.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
          example:
            message: An active membership is required.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum token

````