> ## Documentation Index > Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new connection > Creates and returns a new connection for the authenticated application. Returns an onboarding URL for the user to complete the QuickBooks setup process. Only `name`, `redirect_url` and `type` can be set: sending `username`, `password`, `company_file`, `quickbooks_product_name` or `last_connected_at` is refused with `422` naming the field. Set a password with `POST /connections/{connection_id}/password`. A production app can have connections only once its organization has billing: until then every type is refused with `402 billing_required`. ## OpenAPI ````yaml /api-reference/v1/openapi.json post /connections openapi: 3.0.0 info: title: QuBe Sync API description: Integrate with QuickBooks Desktop or QuickBooks Enterprise in a few steps. version: 1.0.0 contact: email: support@qubesync.com servers: - url: https://qubesync.com/api/v1 description: v1 API - url: https://dev.qubesync.com/api/v1 description: Local development server security: [] tags: - name: Connections description: Endpoints for managing QuickBooks connections - name: Queued Requests description: Endpoints for managing queued API requests - name: Pre-built Queries description: >- Endpoints for executing pre-built queries against QuickBooks data. These endpoints simplify common data retrieval operations by providing a higher-level interface than the raw queued requests API. Each query is executed asynchronously and returns a queued request ID that can be used to check the status and retrieve results. paths: /connections: post: tags: - Connections summary: Create a new connection description: >- Creates and returns a new connection for the authenticated application. Returns an onboarding URL for the user to complete the QuickBooks setup process. Only `name`, `redirect_url` and `type` can be set: sending `username`, `password`, `company_file`, `quickbooks_product_name` or `last_connected_at` is refused with `422` naming the field. Set a password with `POST /connections/{connection_id}/password`. A production app can have connections only once its organization has billing: until then every type is refused with `402 billing_required`. requestBody: content: application/json: schema: type: object properties: name: type: string description: >- Optional name for the connection - if you leave this blank, the company name returned by QuickBooks will be used once the first request is processed. A blank name (empty or only whitespace) is stored as null, and surrounding whitespace is trimmed. A simulated connection left blank takes its simulated company's name (Simulated Company) straight away. redirect_url: $ref: '#/components/schemas/connection_redirect_url' type: type: string enum: - standard - realtime - simulated default: standard description: >- How QuickBooks is reached. 'simulated' creates a fake QuickBooks answered by QuBe Sync: connected immediately, no Web Connector, meant for development and tests (see the Quickstart). Simulated connections are in beta: they don't match real QuickBooks in every case yet. responses: '201': description: Connection created successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Connection' example: data: id: 123e4567-e89b-12d3-a456-426614174000 app_id: 550e8400-e29b-41d4-a716-446655440000 username: 550e8400-e29b-41d4-a716-446655440001 name: My Customer Inc. last_connected_at: null company_file: null type: standard qbxml_version: null quickbooks_product_name: null redirect_url: https://myapp.com/quickbooks-setup-callback links: self: /api/v1/connections/123e4567-e89b-12d3-a456-426614174000 ui: /app/connections/123e4567-e89b-12d3-a456-426614174000 onboarding: https://qubesync.com/onboarding/abcdef123456 inserted_at: '2023-01-01T12:00:00Z' updated_at: '2023-01-01T12:00:00Z' '401': $ref: '#/components/responses/Unauthorized' '402': description: >- `billing_required`: this is a production app, and its organization has no active billing yet. A production app can't have connections of any type, `simulated` included, until an owner of the organization sets up billing in the dashboard. Use the sandbox app to test before then. Nothing was saved. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: detail: >- This is a production app, and its organization doesn't have billing set up yet, so it can't have connections. An owner of the organization can set up billing in the QuBe Sync dashboard. To test before then, use the organization's sandbox app. code: billing_required '422': description: >- Invalid fields, such as a `type` that isn't one of the listed values, or a field that can't be set here, such as `last_connected_at`. `errors` names each one. Nothing was saved. content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' security: - apiKey: [] components: schemas: connection_redirect_url: type: string format: uri description: >- The URL to redirect the user to after they complete (or cancel) the QuickBooks setup process. This URL should be able to handle the query parameters: * `?state=connected` if they completed the process, * `?state=cancelled` if they cancelled it or * `?state=expired` if they visit the onboarding link after it has expired example: https://myapp.com/quickbooks-setup-callback Connection: type: object properties: id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 description: Unique identifier for the connection last_connected_at: type: string format: date-time example: '2023-01-01T12:00:00Z' description: Timestamp of when the connection was last used nullable: true name: type: string example: My Customer Inc. description: Name of the connection app_id: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 description: ID of the app this connection belongs to company_file: type: string example: My Company File.QBW description: Name of the QuickBooks company file nullable: true username: type: string example: 550e8400-e29b-41d4-a716-446655440001 description: Automatically generated username for the connection qbxml_version: type: string example: '14.0' description: >- The latest QBXML version supported by the connected QuickBooks instance nullable: true quickbooks_product_name: type: string example: QuickBooks Pro 2021 description: The product name of the connected QuickBooks instance nullable: true onboarding_token_expires_at: type: string format: date-time example: '2023-01-08T12:00:00Z' description: When `links.onboarding` stops working, UTC ISO 8601 nullable: true type: type: string example: standard description: >- How QuickBooks is reached: 'standard' (Web Connector every 5 minutes), 'realtime' (every 10 seconds) or 'simulated' (a fake QuickBooks answered by QuBe Sync itself, for development and tests; in beta: it doesn't match real QuickBooks in every case yet). enum: - standard - realtime - simulated redirect_url: $ref: '#/components/schemas/connection_redirect_url' links: type: object properties: self: type: string format: uri example: /api/v1/connections/123e4567-e89b-12d3-a456-426614174000 ui: type: string format: uri example: /app/connections/123e4567-e89b-12d3-a456-426614174000 onboarding: type: string format: uri example: >- https://qubesync.com/onboarding/123e4567-e89b-12d3-a456-426614174000 required: - id - app_id - username Error: description: >- What a refused request answers with. The one key is errors, and its shape says what went wrong: a sentence when the endpoint explains the refusal in words (a parameter the operation does not take, a key already taken, a run that has already ended); an object with detail, and a code when there is one, when the request named nothing that exists or may not do what it asked (402, 403, 404, and a CLI session's 401), or an answer to a run's question was refused (the decisions endpoint's 400, 409 and 422, which always carry a code to branch on); an object of fields, each a list of messages, when a record failed validation and nothing was saved; a list of {path, message} problems when a submitted document or input fails validation. A request without a usable API key gets a 401 Basic challenge with the plain-text body Unauthorized, not JSON. properties: errors: oneOf: - example: 'unknown parameter: "emial"' title: A sentence type: string - properties: code: example: read_only_session type: string detail: example: Not Found type: string required: - detail title: Detail and code type: object - additionalProperties: items: type: string type: array example: redirect_url: - must be a valid URL title: Field by field type: object - items: properties: message: example: is required type: string path: example: input.customer type: string required: - path - message type: object title: Located problems type: array required: - errors type: object ValidationErrors: type: object description: A field-by-field list of what was wrong. Nothing was saved. properties: errors: type: object additionalProperties: items: type: string type: array example: errors: last_connected_at: - >- is read-only: QuBe Sync sets it from the Web Connector and QuickBooks responses: Unauthorized: description: >- No usable API key. The key is Basic auth, so the answer is the challenge, with the plain-text body Unauthorized rather than JSON. headers: WWW-Authenticate: schema: type: string example: Basic realm="Application" content: text/plain: schema: type: string example: Unauthorized securitySchemes: apiKey: type: http scheme: basic description: Use your app's API_KEY as the username, and leave the password blank ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.