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

# Direct Connection

<Info>
  This endpoint requires a valid authorisation for the user. If no active authorisation exists, the request will be rejected.
  You can optionally pass the `x-teal-authorisation-id` header to specify which authorisation to use; otherwise the system will resolve a valid authorisation automatically.
  See [Authorisations](/authorisations) for more details.
</Info>


## OpenAPI

````yaml POST /accounts/direct-connections
openapi: 3.0.1
info:
  title: Payroll API
  description: A full flagged payroll api provided by Teal
  version: 1.0.0
servers:
  - url: https://api.sandbox.goteal.co
    description: Sandbox server for experiments
  - url: https://api.goteal.co
    description: Production server
security:
  - ApiKeyAuth: []
  - MemberBearerAuth: []
paths:
  /accounts/direct-connections:
    post:
      summary: Creates a direct connection for a user.
      parameters:
        - $ref: '#/components/parameters/XAuthorisationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: string
                  description: The id of the user
                  example: 95a0e70b-fe02-4f47-aef9-2efff279df71
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                  - pagination
                  - payroll_submissions
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  payroll_submissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayrollSubmission'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedApiKey'
components:
  parameters:
    XAuthorisationId:
      name: x-teal-authorisation-id
      in: header
      required: false
      description: >-
        Optional authorisation ID to associate with this request. If not
        provided, the system will attempt to resolve a valid authorisation for
        the user automatically.
      schema:
        type: string
        format: uuid
        example: 7f3b8c2a-1d4e-4f6a-8b8c-9a0b1c2d3e4f
  schemas:
    Pagination:
      type: object
      required:
        - offset
        - limit
        - count
      properties:
        offset:
          description: The offset to start at - zero based
          type: integer
          format: int32
          minimum: 1
          default: 0
          example: 75
        limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 20
          example: 25
        count:
          type: integer
          format: int32
          example: 14
          minimum: 0
        total_count:
          type: integer
          format: int32
          example: 89
    PayrollSubmission:
      type: object
      required:
        - id
        - account_id
        - entry_id
        - created_at
        - identity_information
        - employment_information
        - income_information
      properties:
        id:
          type: string
          format: uuid
          example: 95a0e70b-fe02-4f47-aef9-2efff279df71
        account_id:
          type: string
          format: uuid
          description: The id of the account
          example: 674744df-9626-47ef-ae2b-4a491be136b5
        entry_id:
          type: string
          format: uuid
          description: The id of the entry
          example: be770ba4-1362-46cd-8c1c-2330ce3a8b69
        created_at:
          $ref: '#/components/schemas/Date'
          description: The date the payroll was submitted
          example: '2019-05-17T00:00:00.000Z'
        document_id:
          type: string
          nullable: true
          format: uuid
          description: The id of the document
          example: 95a0e70b-fe02-4f47-aef9-2efff279df71
        document_external_id:
          type: string
          nullable: true
          description: >-
            A string coming from the parameters of the uploaded payslip1.pdf
            either the form field name or `external_document_id` header for the
            file part. It might not be unique and depends on what's passed when
            uploading. If the payroll submission doesn't originate from a
            payslip this will be null.
          example: payslip123456
        document_filename:
          type: string
          nullable: true
          description: >-
            If the payroll submission originates from a payslip this will be the
            file name of the uploaded payslip. It will be duplicate if same file
            names are uploaded If the payroll submission doesn't originate from
            a payslip this will be null.
          example: file1-payslip.pdf
        identity_information:
          $ref: '#/components/schemas/IdentityInformation'
        employment_information:
          $ref: '#/components/schemas/EmploymentInformation'
        income_information:
          $ref: '#/components/schemas/IncomeInformation'
        trust_score:
          $ref: '#/components/schemas/TrustScore'
          nullable: true
        source:
          type: string
          description: The source of the payroll data
          example: Payroll (via Direct Connection)
          enum:
            - Payroll (via Direct Connection)
            - Payroll (via User Connection)
            - Payslip (via Doc Scan)
    Date:
      type: string
      format: date-time
      example: '2019-05-17T00:00:00.000Z'
    IdentityInformation:
      type: object
      properties:
        name:
          type: string
          description: The full name of the user
          example: John Smith
        date_of_birth:
          $ref: '#/components/schemas/Date'
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
          description: The email of the user
          format: email
          example: john.smith@company.com
        phone:
          type: string
          description: The phone number of the user
          example: 447123456789
        NI_number:
          type: string
          description: The national insurance number of the user
          example: AB123456C
    EmploymentInformation:
      type: object
      properties:
        employer_name:
          type: string
          description: The name of the employer
          example: Acme Ltd
        role:
          type: string
          description: The role of the user
          example: Software Engineer
        type:
          type: string
          description: The type of employment
          example: Full-time
        status:
          type: string
          description: >
            The status of the employment. Status `active` will be used when the
            user is employed in the company,  alternatively `inactive` will be
            used when the user is not employed in the company anymore.
          enum:
            - active
            - inactive
          example: active
        start_date:
          $ref: '#/components/schemas/Date'
        leave_date:
          $ref: '#/components/schemas/Date'
          nullable: true
    IncomeInformation:
      type: object
      properties:
        pay_date:
          $ref: '#/components/schemas/Date'
          type: string
          description: The date the payroll was submitted
          example: '2023-05-27T00:00:00.000Z'
        pay_interval_start:
          $ref: '#/components/schemas/Date'
          type: string
          description: The start date of the pay interval
          example: '2023-05-01T00:00:00.000Z'
        pay_interval_end:
          $ref: '#/components/schemas/Date'
          type: string
          description: The end date of the pay interval
          example: '2023-05-31T00:00:00.000Z'
        pay_frequency:
          type: string
          description: The frequency of the pay
          example: Monthly
        earnings:
          $ref: '#/components/schemas/Earnings'
        deductions:
          $ref: '#/components/schemas/Deductions'
    TrustScore:
      type: string
      description: >-
        The document trust score assessment. Trust score will be present if the
        payroll data is coming from a payslip source
      enum:
        - Low
        - Medium
        - High
      example: High
    Error:
      required:
        - errors
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: An array of messages describing the errors
          example:
            - The request is missing the required field `name`
    Unauthorized:
      type: object
      properties:
        errors:
          type: string
          description: An array of messages describing the errors
          example:
            - No X-API-KEY header provided or wrong value
    Address:
      type: object
      properties:
        street:
          type: string
          description: The street of the address
          example: 123 Main Street
        county:
          type: string
          description: The county of the address
          example: Greater London
        city:
          type: string
          description: The city of the address
          example: London
        post_code:
          type: string
          description: The post code of the address
          example: SW1A 1AA
        country:
          type: string
          description: The country of the address
          example: United Kingdom
    Earnings:
      type: object
      properties:
        gross_pay:
          type: number
          description: The gross pay
          example: 3500
        net_pay:
          type: number
          description: The net pay
          example: 2500
        base_salary:
          type: number
          description: The base salary
          example: 3000
        bonus:
          type: number
          description: The bonus
          example: 500
    Deductions:
      type: object
      properties:
        income_tax:
          type: number
          description: The income tax
          example: 500
        employee_ni:
          type: number
          description: The employee national insurance
          example: 200
        employee_pension:
          type: number
          description: The employee pension
          example: 300
        total_deductions:
          type: number
          description: The total deductions
          example: 1000
  responses:
    BadRequest:
      description: Bad request if one of the required parameters is missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedApiKey:
      description: Unauthorized if the X-API-KEY is not provided or is wrong
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    MemberBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token for authentication. The token should be the one returned by
        the "/members/signin"

````