> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Finish connecting with the provider's authorisation code > Exchanges the code from the provider's sign-in for access. A provider organisation is connected at most once per organisation here: if it is already held by a connection that is not live (for example one that was disconnected), that connection is reconnected instead and the one in the path is deleted, so the response carries the EXISTING connection's id. Always continue with the id in the response. Returns 409 tenant_already_connected, and deletes the connection in the path, when a live connection already holds that provider organisation. Returns 409 tenant_mismatch when the connection is in use (it has bindings) and the sign-in chose a different provider organisation from the one it is tied to: the new sign-in is discarded, the connection stays disconnected with its bindings untouched, and the message carries tokenArguments currentTenantName and chosenTenantName. ## OpenAPI ````yaml /api-reference/specs/integrations.json post /connections/{connectionId}/exchange openapi: 3.0.1 info: title: Integrations Service description: Integrations API for FlowPayroll version: v1 servers: - url: https://api.sandbox.flowpayroll.ai/v1/integrations security: - X-Auth-Token: [] tags: - name: Providers description: >- The providers Flow Payroll can send to, what each can do, and the sign-in details it needs. - name: Connections description: >- Your organisation's provider accounts: create one, save its sign-in details, test it, pause it, disconnect it or remove it. - name: Scheme links description: >- Which pension scheme sends through which connection. Linking is the opt-in: nothing is sent for a scheme until it is linked. - name: Activity description: >- Every submission to a provider and every read from it, with status, attempts and the provider reference. Retry what failed, cancel what has not gone yet. - name: Provider data description: >- How fresh the data read from the provider is, and how to refresh it on demand. - name: Initial import description: >- Read everything the provider already holds for the employer, so Flow Payroll starts in step with it. paths: /connections/{connectionId}/exchange: post: tags: - Connections summary: Finish connecting with the provider's authorisation code description: >- Exchanges the code from the provider's sign-in for access. A provider organisation is connected at most once per organisation here: if it is already held by a connection that is not live (for example one that was disconnected), that connection is reconnected instead and the one in the path is deleted, so the response carries the EXISTING connection's id. Always continue with the id in the response. Returns 409 tenant_already_connected, and deletes the connection in the path, when a live connection already holds that provider organisation. Returns 409 tenant_mismatch when the connection is in use (it has bindings) and the sign-in chose a different provider organisation from the one it is tied to: the new sign-in is discarded, the connection stays disconnected with its bindings untouched, and the message carries tokenArguments currentTenantName and chosenTenantName. operationId: ExchangeConnection parameters: - name: connectionId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ExchangeAuthorisationCodeRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConnectionResponseResponseBody' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' components: schemas: ExchangeAuthorisationCodeRequest: required: - code - state type: object properties: code: minLength: 1 type: string state: minLength: 1 type: string additionalProperties: false ConnectionResponseResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ConnectionResponseContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false ObjectResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ObjectContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ConnectionResponseContentResponse: type: object properties: data: $ref: '#/components/schemas/ConnectionResponse' metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssue: type: object properties: field: type: string reason: type: string reasonToken: type: string reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ObjectContentResponse: type: object properties: data: nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssueArgument: type: object properties: name: type: string value: nullable: true additionalProperties: false ConnectionResponse: type: object properties: id: type: string organisationId: type: string providerSlug: type: string displayName: type: string state: enum: - None - PendingAuth - Authorised - Callable - Invalid - Deauthorised type: string enabled: type: boolean externalTenantId: type: string nullable: true externalTenantName: type: string nullable: true externalEmployerReference: type: string nullable: true tokenExpiresAt: type: string nullable: true lastSuccessDate: type: string nullable: true consecutiveFailures: type: integer format: int32 circuitOpenUntil: type: string nullable: true boundResourceCount: type: integer format: int32 createdBy: type: string createdDate: type: string updatedBy: type: string updatedDate: type: string additionalProperties: false ContentMetadataResponse: type: object properties: dateFormat: type: string dateTimeFormat: type: string paginationToken: type: string nullable: true additionalProperties: false securitySchemes: X-Auth-Token: type: apiKey description: FlowPayroll JWT (raw token, no Bearer prefix) name: X-Auth-Token in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.