### GET /integrations/{provider}/setup-info

Source: https://docs.flowpayroll.ai/api-reference/billing/integrations/get-integration-setup-info

Returns setup info for the specified provider to assist with app configuration.

```APIDOC
## GET /integrations/{provider}/setup-info

### Description
Returns setup info (e.g. redirect URI) for the provider so the user can configure their app in the provider's developer portal.

### Method
GET

### Endpoint
/integrations/{provider}/setup-info

### Parameters
#### Path Parameters
- **provider** (string) - Required - The identifier of the integration provider.

### Response
#### Success Response (200)
- **redirectUri** (string) - The redirect URI for the provider, may be null.
```

--------------------------------

### Shift Pattern Configuration Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/set-the-employees-working-pattern-from-an-effective-date

Example of a shift pattern configuration including rotation start date and shift definitions.

```yaml
rotationStartDate: '2024-01-01'
shifts:
  - name: Morning Shift
    workingDays:
      monday: true
      tuesday: true
      wednesday: true
      thursday: true
      friday: true
      saturday: false
      sunday: false
    durationInDays: 5
    weekNumber: 1
  - name: Night Shift
    workingDays:
      monday: true
      tuesday: true
      wednesday: true
      thursday: true
      friday: true
      saturday: false
      sunday: false
    durationInDays: 5
    weekNumber: 2
patternType: FourOnFourOff
patternWeeks: 8
```

--------------------------------

### Get integration setup info OpenAPI specification

Source: https://docs.flowpayroll.ai/api-reference/billing/integrations/get-integration-setup-info

Defines the GET endpoint for retrieving integration setup information, including the required provider path parameter and the expected response schema.

```yaml
openapi: 3.0.1
info:
  title: Billing Service
  description: Billing API for FlowPayroll
  contact:
    name: FlowPayroll
    email: support@flowpayroll.com
  version: v1
servers:
  - url: https://api.sandbox.flowpayroll.ai/v1/billing
security:
  - X-Auth-Token: []
tags:
  - name: Account codes
    description: Create, update, archive, and delete accounting ledger codes.
  - name: Tax rates
    description: Manage default and custom tax rates.
  - name: Invoice & credit note templates
    description: >-
      Configure invoice and credit note templates, and list the available
      reference and description tokens.
  - name: Finance defaults
    description: >-
      Organisation finance defaults, pay element mappings, and attachment
      limits.
  - name: Invoices
  - name: Credit Notes
  - name: Clients
  - name: Integrations
  - name: Accounting Sync
paths:
  /integrations/{provider}/setup-info:
    get:
      tags:
        - Integrations
      summary: Get integration setup info
      description: >-
        Returns setup info (e.g. redirect URI) for the provider so the user can
        configure their app in the provider's developer portal.
      operationId: GetSetupInfo
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSetupInfoResponse'
        '404':
          description: Not Found
components:
  schemas:
    IntegrationSetupInfoResponse:
      type: object
      properties:
        redirectUri:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      description: Authentication token for API access
      name: X-Auth-Token
      in: header
```

--------------------------------

### Shift Pattern Configuration

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/create-a-new-employee

Example of a shift pattern configuration including rotation start date and shift details.

```json
{
  "rotationStartDate": "2024-01-01",
  "shifts": [
    {
      "name": "Morning Shift",
      "workingDays": {
        "monday": true,
        "tuesday": true,
        "wednesday": true,
        "thursday": true,
        "friday": true,
        "saturday": false,
        "sunday": false
      },
      "durationInDays": 5,
      "weekNumber": 1
    },
    {
      "name": "Night Shift",
      "workingDays": {
        "monday": true,
        "tuesday": true,
        "wednesday": true,
        "thursday": true,
        "friday": true,
        "saturday": false,
        "sunday": false
      },
      "durationInDays": 5,
      "weekNumber": 2
    }
  ],
  "patternType": "FourOnFourOff",
  "patternWeeks": 8
}
```

--------------------------------

### Organisation Name Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/payslip/get-all-payslip-data-for-an-employee-within-a-date-range

Example values for legal and trading names.

```yaml
example: Acme Corporation Ltd
        tradingName:
          type: string
          nullable: true
          description: Trading name of the organisation
          example: Acme Corp
```

--------------------------------

### Organisation Type Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/payslip/get-all-payslip-data-for-an-employee-within-a-date-range

Example value for organisation type.

```yaml
example: LimitedCompany
```

--------------------------------

### Employee Name Schema Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/find-employee-by-national-insurance-number

Example values for the EmployeeNameDto object.

```yaml
firstName: John
        middleName: Edward
        lastName: Smith
        title: Mr
```

--------------------------------

### NI Band Result Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/payslip/get-all-payslip-data-for-an-employee-within-a-date-range

Example values for NI band calculations.

```yaml
example: 12570
        employeeNiForBand:
          type: number
          format: decimal
          description: Employee NI contribution for this band
          example: 0
        employerNiForBand:
          type: number
          format: decimal
          description: Employer NI contribution for this band
          example: 0
```

--------------------------------

### Previous Employment Earnings Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/partially-update-an-existing-employee

Example structure for P45 earnings data.

```yaml
grossTaxable:
  type: number
  format: decimal
  description: Taxable gross earnings from the previous employer (P45 taxable pay).
  example: 15000
  default: 0
tax:
  type: number
  format: decimal
  description: Tax paid at the previous employer (P45 tax paid).
  example: 3000
  default: 0
```

--------------------------------

### New Starters CSV Import Template

Source: https://docs.flowpayroll.ai/guides/people/onboarding-employees

This CSV template defines the required columns and provides an example row for importing new employee data into the payroll system.

```csv
Payroll ID,Employee ID,Payroll Config,Title,First Name,Middle Name,Last Name,Email,Phone,Birth Date,Birth Gender,Marital Status,Start Date,Starter Declaration,Starter Reported to HMRC,Director NIC Type,Director Appointment Date,Director End Date,Partner NI Number,Partner First Name,Partner Last Name,Hours Worked,Job Title,Department,Salary,Tax Code,NI Category,NI Number,Student Loan Plan,Postgraduate Loan Plan,Student Loan Start Date,Student Loan End Date,PG Loan Start Date,PG Loan End Date,P45 Previous Taxable Pay,P45 Previous Tax Paid,Address Line 1,Address Line 2,City,County,Postcode,Country Code,Account Holder Name,Account Number,Sort Code,Secondary Email,Secondary Phone,Employee Code,Passport Number,Gender,Irregular Employment,Off Payroll Worker (IR35),Workplace Postcode,Tax Code W1/M1,Works Monday,Works Tuesday,Works Wednesday,Works Thursday,Works Friday,Works Saturday,Works Sunday
EMP001,,Monthly Payroll,Ms,Jane,Elizabeth,Smith,jane.smith@example.com,07700900123,15/06/1990,Female,Married,06/04/2024,B,No,No,01/04/2024,31/03/2025,AB123456C,John,Smith,30 hours or more,Payroll Manager,Finance,35000,1257L,A,AB123456C,Plan 2,No,01/09/2020,30/06/2025,01/09/2021,30/06/2026,15000,3000,10 Downing Street,,London,Greater London,SW1A 2AA,England,Jane Smith,12345678,200000,john.alt@example.com,07700900456,EMP001,123456789,Male,No,No,SW1A 1AA,No,Yes,Yes,Yes,Yes,Yes,No,No
```

--------------------------------

### Get line item description formula placeholders

Source: https://docs.flowpayroll.ai/llms.txt

Returns placeholders that can be used in the line description formula. Use the returned id in curly braces in the formula.

```APIDOC
## GET /billing/invoice-&-credit-note-templates/line-item-description-formula-placeholders

### Description
Returns placeholders that can be used in the line description formula (e.g. {description}, {employeeName}). Use the returned id in curly braces in the formula. When requiresTagGroup is true for a placeholder, set lineDescriptionTagGroupId on the invoice or credit note template when using that placeholder.
```

--------------------------------

### Get invoice reference formula tokens for a given invoice format

Source: https://docs.flowpayroll.ai/llms.txt

Returns available tokens that can be used in the invoice reference formula for a given invoice format.

```APIDOC
## GET /billing/invoice-&-credit-note-templates/invoice-reference-formula-tokens

### Description
Returns available tokens that can be used in the invoice reference formula for a given invoice format. Use the returned id in curly braces in the formula (e.g. {payrollConfigName}). Separators (space, dash, underscore, slash) are always available.
```

--------------------------------

### Get OAuth login URI

Source: https://docs.flowpayroll.ai/llms.txt

Returns the provider OAuth login URI for the current organisation.

```APIDOC
## GET /billing/integrations/oauth-login-uri

### Description
Returns the provider OAuth login URI for the current organisation. Frontend redirects the user to this URI to start the connection flow.
```

--------------------------------

### Get Invoice Line Items

Source: https://docs.flowpayroll.ai/llms.txt

Retrieves line items for an invoice.

```APIDOC
## GET /billing/invoices/{id}/line-items

### Description
Retrieves line items for an invoice (paginated; default page size 100, max 1000 to stay under API Gateway 10 MB limit).
```

--------------------------------

### Get Invoice by Id

Source: https://docs.flowpayroll.ai/llms.txt

Retrieves an invoice by its unique identifier.

```APIDOC
## GET /billing/invoices/{id}

### Description
Retrieves an invoice by its unique identifier.
```

--------------------------------

### POST /notifications/pagination/initialise

Source: https://docs.flowpayroll.ai/api-reference/hmrc-dps/overview

Sets up pagination state for data retrieval.

```APIDOC
## POST /notifications/pagination/initialise

### Description
Sets up pagination state for the chosen data types and service from a given date.

### Method
POST

### Endpoint
/notifications/pagination/initialise

### Parameters
#### Request Body
- **overwriteExisting** (boolean) - Optional - Replace state that already exists
```

--------------------------------

### Payment Configuration Example

Source: https://docs.flowpayroll.ai/api-reference/payment/organisationpaymentconfig/get-payment-configuration-for-an-organisation

Example structure for payment configuration including sort code, account number, service user number, and account name.

```yaml
sortCode: 12-34-56
accountNumber: '12345678'
serviceUserNumber: SUN123
accountName: ACME CORP LTD
```

--------------------------------

### POST /employees/{employeeId}/student-loan/start

Source: https://docs.flowpayroll.ai/api-reference/pay-api/student-loans/start-a-student-loan-for-an-employee

Starts a student loan for a specified employee.

```APIDOC
## POST /employees/{employeeId}/student-loan/start

### Description
Starts a student loan for an employee by providing the loan type and start date.

### Method
POST

### Endpoint
/employees/{employeeId}/student-loan/start

### Parameters
#### Path Parameters
- **employeeId** (string) - Required - The ID of the employee

#### Request Body
- **loanType** (string) - Required - Type of student loan. Valid values: 'Plan1', 'Plan2', 'Plan4', 'Plan5'
- **startDate** (string) - Required - The start date of the student loan in YYYY-MM-DD format

### Request Example
{
  "loanType": "Plan2",
  "startDate": "2024-04-06"
}

### Response
#### Success Response (200)
- **content** (object) - Contains the updated employee data

#### Response Example
{
  "content": {
    "data": {
      "id": "emp_12345"
    }
  }
}
```

--------------------------------

### OpenAPI Specification for List Available Payment Configurations

Source: https://docs.flowpayroll.ai/api-reference/payment/availablepaymentconfig/list-all-available-payment-configurations

Defines the GET /available/config endpoint, including the response schema and an example of the returned data structure.

```yaml
openapi: 3.0.3
info:
  title: FlowPayroll Payment API
  description: >-
    Payment Service API for FlowPayroll. Generates and serves BACS (Standard 18,
    Barclays CSV/TXT, Allica) payment files for completed pay runs, manages
    per-organisation payment configuration, and handles retry of failed
    payment-file generation.
  version: 0.1.0
servers:
  - url: https://api.sandbox.flowpayroll.ai/v1/payment
security:
  - XAuthToken: []
    XOrgId: []
tags:
  - name: PaymentFile
    description: >-
      Generated BACS payment file for a completed pay run. Status transitions:
      GENERATED | PARTIAL_SUCCESS | FAILED → (admin retries) RETRYING →
      GENERATED | PARTIAL_SUCCESS | FAILED. PARTIAL_SUCCESS means the file was
      generated for the employees that passed BACS validation AND
      `failure.affectedEmployees` lists the ones that need attention. When
      status is FAILED, no file was generated; `failure.affectedEmployees` lists
      every employee blocking the file. The UI can render affected employees
      with anchors to their profiles in both PARTIAL_SUCCESS and FAILED states.
  - name: AvailablePaymentConfig
    description: >-
      List of BACS payment methods and formats available for an organisation to
      configure.
  - name: OrganisationPaymentConfig
    description: >-
      Per-organisation payment configuration. Stores the BACS source bank
      account, service user number, and which (method, format, file-format)
      combination drives payment file generation for that org's completed pay
      runs.
paths:
  /available/config:
    get:
      tags:
        - AvailablePaymentConfig
      summary: List all available payment configurations
      operationId: listAvailablePaymentConfigs
      responses:
        '200':
          description: List of available payment configurations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseBody'
                  - type: object
                    properties:
                      content:
                        type: object
                        properties:
                          data:
                            type: array
                            items:
                              $ref: >-
                                #/components/schemas/AvailablePaymentConfigResponse
                          metadata:
                            $ref: '#/components/schemas/ContentMetadataResponse'
              example:
                message:
                  text: >-
                    List of available payment configurations retrieved
                    successfully
                  token: listAvailablePaymentConfigsSuccess
                  tokenArguments: []
                content:
                  data:
                    - method: BACS
                      format: Barclays
                      supportedFileFormats:
                        - txt
                        - csv
                    - method: BACS
                      format: Standard18
                      supportedFileFormats:
                        - txt
                  metadata:
                    dateFormat: yyyy-MM-dd
                    dateTimeFormat: yyyy-MM-ddTHH:mm:ss.fffZ
                    paginationToken: null
                validationIssues: []
                messageToken: listAvailablePaymentConfigsSuccess
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
components:
  schemas:
    ResponseBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessageWithTokenResponse'
        content:
          type: object
          properties:
            data:
              type: object
              nullable: true
            metadata:
              type: object
              nullable: true
              properties:
                dateFormat:
                  type: string
                  default: yyyy-MM-dd
                dateTimeFormat:
                  type: string
                  default: yyyy-MM-ddTHH:mm:ss.fffZ
                paginationToken:
                  type: string
                  nullable: true
        validationIssues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        messageToken:
          type: string
    AvailablePaymentConfigResponse:
      type: object
      properties:
        method:
          type: string
          example: BACS
        format:
          type: string
```

--------------------------------

### Standard Working Days Configuration Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/set-the-employees-working-pattern-from-an-effective-date

Example of a standard working days configuration object.

```yaml
monday: true
monday: true
tuesday: true
wednesday: true
thursday: true
friday: true
saturday: false
sunday: false
```

--------------------------------

### GET /integrations/{provider}/connect

Source: https://docs.flowpayroll.ai/api-reference/billing/integrations/get-oauth-login-uri

Returns the provider OAuth login URI for the current organisation. Frontend redirects the user to this URI to start the connection flow.

```APIDOC
## GET /integrations/{provider}/connect

### Description
Returns the provider OAuth login URI for the current organisation. Frontend redirects the user to this URI to start the connection flow.

### Method
GET

### Endpoint
/integrations/{provider}/connect

### Parameters
#### Path Parameters
- **provider** (string) - Required - The identifier of the integration provider.

#### Query Parameters
- **redirectUri** (string) - Optional - The URI to redirect to after successful authentication.
- **state** (string) - Optional - An opaque value used by the client to maintain state between the request and callback.

### Response
#### Success Response (200)
- **loginUri** (string) - The OAuth login URI for the provider.

#### Response Example
{
  "loginUri": "https://provider.com/oauth/authorize?client_id=..."
}
```

--------------------------------

### EmployeeTaxCodeDto Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/student-loans/start-a-postgraduate-loan-for-an-employee

Example structure for the EmployeeTaxCodeDto object.

```json
{
  "code": "1257L",
  "effectiveDate": "2024-04-06",
  "reason": "Standard tax code",
  "issuedBy": "HMRC",
  "week1Month1": false
}
```

--------------------------------

### POST /employees/{employeeId}/postgraduate-loan/start

Source: https://docs.flowpayroll.ai/api-reference/pay-api/student-loans/start-a-postgraduate-loan-for-an-employee

Starts a postgraduate loan for a specified employee.

```APIDOC
## POST /employees/{employeeId}/postgraduate-loan/start

### Description
Starts a postgraduate loan for an employee by providing the start date.

### Method
POST

### Endpoint
/employees/{employeeId}/postgraduate-loan/start

### Parameters
#### Path Parameters
- **employeeId** (string) - Required - The ID of the employee

#### Request Body
- **startDate** (string) - Required - The start date of the postgraduate loan in YYYY-MM-DD format

### Request Example
{
  "startDate": "2024-04-06"
}

### Response
#### Success Response (200)
- **content** (object) - Contains the updated employee data

#### Response Example
{
  "content": {
    "data": {
      "id": "emp_12345"
    }
  }
}
```

--------------------------------

### Tag DTO Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/partially-update-an-existing-employee

Example structure for tag definitions.

```yaml
name:
  type: string
  example: FullTime
group:
  type: string
  example: EmploymentType
value:
  type: string
  example: FullTime
```

--------------------------------

### Employee Starter Details Schema

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/partially-update-an-existing-employee

Defines the structure for employee starter information, including start date and HMRC declaration status.

```yaml
EmployeeStarterDetailsDto:
  type: object
  required:
    - startDate
    - starterDeclaration
    - alreadySentToHmrcFps
  properties:
    startDate:
      type: string
      description: The start date of the employee.
      example: '2024-01-15'
    starterDeclaration:
      type: string
      description: >-
        The starter declaration of the employee. Use
        'ThisIsMyFirstJobSince6thApril', 'ThisIsMyOnlyJob', or
        'IHaveAnotherJobOrPension' for a new starter. Use 'None' for an
        existing employee who has already been reported to HMRC (for
        example, one migrated mid-year from another payroll provider); in
        that case alreadySentToHmrcFps must be true.
      example: ThisIsMyOnlyJob
      enum:
        - ThisIsMyFirstJobSince6thApril
        - ThisIsMyOnlyJob
        - IHaveAnotherJobOrPension
        - None
    secondedDetails:
      $ref: '#/components/schemas/EmployeeSecondedDetailsDto'
      nullable: true
    alreadySentToHmrcFps:
      type: boolean
      description: >-
        Whether the employee's starter details have already been reported to
        HMRC on an FPS. Set to false for a new starter (the starter
        declaration is reported on the next FPS). Set to true for an
        existing employee already reported to HMRC; this is required when
        starterDeclaration is 'None'.
      example: false
```

--------------------------------

### Employee Postgraduate Loan Details

Source: https://docs.flowpayroll.ai/api-reference/pay-api/starters-&-leavers/update-the-starter-details-for-a-specific-employee

Example configuration for an employee's postgraduate loan details.

```json
loanType: PostgraduateLoan
startDate: '2015-09-01'
```

--------------------------------

### Address Schema Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/find-employee-by-national-insurance-number

Example values for the AddressDto object.

```yaml
line1: 123 Main Street
        line2: Apt 4B
        city: London
        county: Greater London
```

--------------------------------

### Statutory Payments Reclaim Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/payslip/get-all-payslips-by-pay-run

Example values for the StatutoryPaymentsReclaimDto schema.

```json
{
  "reclaimed": 100,
  "nicCompensationRecovered": 50
}
```

--------------------------------

### PatchEmployeeDto Schema Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/create-a-new-employee

Example values for fields within the PatchEmployeeDto schema, including tax codes and previous employment earnings.

```yaml
taxCodesPerYear:
  '2025':
    - code: 1257L
      effectiveDate: '2025-04-06'
      reason: HMRC Update
      issuedBy: HMRC
      week1Month1: false
```

```yaml
previousEmployment:
  '2026':
    grossTaxable: 15000
    tax: 3000
```

--------------------------------

### Employee Workplace Details Example

Source: https://docs.flowpayroll.ai/api-reference/pay-api/employees/partially-update-an-existing-employee

Example structure for workplace identification.

```yaml
workplaceId:
  type: string
  example: workplace_001
workplaceName:
  type: string
  example: Head Office
```