> For the complete documentation index, see [llms.txt](https://docs.zwapgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zwapgrid.com/api-guide/consents-api-guide/connections.md). # Connections ## Get connection > \*\*Preview (beta):\*\* Headless Onboarding and its API may change or improve with short notice.\ > \ > Get the connection linked to this Consent. Returns its ID, accounting system and state.\ > \ > See the \[onboarding overview]\() and \[recovery steps]\(). ```json {"openapi":"3.0.4","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Connections"}],"servers":[{"url":"https://apione.zwapgrid.com/consents"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"You must generate an API Key by logging into the [Client Portal](https://clients.zwapgrid.com).

You should use the API Key when calling all API endpoints in API.1.","name":"x-api-key","in":"header"}},"schemas":{"ConnectionResponse":{"title":"Completed connection","required":["id","source","state"],"type":"object","properties":{"id":{"type":"string","description":"Connection ID.","format":"uuid"},"source":{"enum":["fortnox","xero","businesscentral","procountor","vismaeaccounting","bjornlunden","vismanetvisor"],"type":"string"},"state":{"enum":["completed"],"type":"string"}},"additionalProperties":false}}},"paths":{"/api/v1/consents/{consentId}/connection":{"get":{"tags":["Connections"],"summary":"Get connection","description":"**Preview (beta):** Headless Onboarding and its API may change or improve with short notice.\n\nGet the connection linked to this Consent. Returns its ID, accounting system and state.\n\nSee the [onboarding overview](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding) and [recovery steps](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding#if-the-result-is-uncertain).","operationId":"GetConnection","parameters":[{"name":"consentId","in":"path","required":true,"schema":{"type":"string","description":"Consent ID.","format":"uuid"}},{"name":"x-correlation-id","in":"header","required":true,"schema":{"type":"string","description":"New non-empty request correlation UUID.","format":"uuid"}}],"responses":{"200":{"description":"Completed connection linked to the Consent.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionResponse"}}}},"400":{"description":"Invalid request or unexpected query parameters.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"401":{"description":"Authentication failed or correlation ID is missing or empty.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"403":{"description":"Access denied.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"404":{"description":"Consent unavailable or no connection found.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"409":{"description":"Consent inactive or linked connection incomplete/unsupported.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"429":{"description":"Request rate limit reached. Do not automatically retry a credential submission.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"502":{"description":"Provider verification or communication failed.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"503":{"description":"Service temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"504":{"description":"Upstream timeout.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}}}}}}} ``` ## Create connection > \*\*Preview (beta):\*\* Headless Onboarding and its API may change or improve with short notice.\ > \ > Create a connection for this Consent using the request body for your accounting system. Submit once; if the result is uncertain, read the connection before taking further action.\ > \ > See the \[onboarding overview]\() for setup and security guidance, and \[recovery steps]\() for an uncertain result. Each system schema links to its guide. ```json {"openapi":"3.0.4","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Connections"}],"servers":[{"url":"https://apione.zwapgrid.com/consents"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"You must generate an API Key by logging into the [Client Portal](https://clients.zwapgrid.com).

You should use the API Key when calling all API endpoints in API.1.","name":"x-api-key","in":"header"}},"schemas":{"FortnoxConnectionRequest":{"title":"Fortnox","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["fortnox"],"type":"string"},"credentials":{"$ref":"#/components/schemas/FortnoxConnectionCredentials"}},"additionalProperties":false,"description":"[Fortnox onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/fortnox). PKCE is not currently supported; support is planned."},"FortnoxConnectionCredentials":{"title":"Fortnox credentials","required":["authorizationCode","redirectUri"],"type":"object","properties":{"authorizationCode":{"maxLength":2048,"minLength":1,"type":"string","description":"Unused authorization code.","writeOnly":true},"redirectUri":{"maxLength":2048,"minLength":1,"type":"string","description":"Registered HTTPS redirect URI, or HTTP loopback. No fragment or user information.","format":"uri"}},"additionalProperties":false},"XeroConnectionRequest":{"title":"Xero","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["xero"],"type":"string"},"credentials":{"$ref":"#/components/schemas/XeroConnectionCredentials"}},"additionalProperties":false,"description":"[Xero onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/xero)."},"XeroConnectionCredentials":{"title":"Xero credentials","required":["accessToken","refreshToken","tenantId"],"type":"object","properties":{"accessToken":{"maxLength":8192,"minLength":1,"type":"string","description":"Access token.","writeOnly":true},"refreshToken":{"maxLength":4096,"minLength":1,"type":"string","description":"Refresh token.","writeOnly":true},"tenantId":{"type":"string","description":"Selected tenant or organization UUID.","format":"uuid"}},"additionalProperties":false},"BusinessCentralConnectionRequest":{"title":"Business Central","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["businesscentral"],"type":"string"},"credentials":{"$ref":"#/components/schemas/BusinessCentralConnectionCredentials"}},"additionalProperties":false,"description":"[Business Central onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/business-central)."},"BusinessCentralConnectionCredentials":{"title":"Business Central credentials","required":["accessToken","refreshToken","tenantId","environment","companyId"],"type":"object","properties":{"accessToken":{"maxLength":8192,"minLength":1,"type":"string","description":"Access token.","writeOnly":true},"refreshToken":{"maxLength":4096,"minLength":1,"type":"string","description":"Refresh token.","writeOnly":true},"tenantId":{"type":"string","description":"Selected tenant or organization UUID.","format":"uuid"},"environment":{"maxLength":100,"minLength":1,"type":"string","description":"Environment name: letters, digits, underscores or hyphens.","writeOnly":true},"companyId":{"type":"string","description":"Selected company UUID.","format":"uuid"}},"additionalProperties":false},"ProcountorConnectionRequest":{"title":"Procountor","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["procountor"],"type":"string"},"credentials":{"$ref":"#/components/schemas/ProcountorConnectionCredentials"}},"additionalProperties":false,"description":"[Procountor onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/procountor)."},"ProcountorConnectionCredentials":{"title":"Procountor credentials","required":["authorizationCode","redirectUri"],"type":"object","properties":{"authorizationCode":{"maxLength":2048,"minLength":1,"type":"string","description":"Unused authorization code.","writeOnly":true},"redirectUri":{"maxLength":2048,"minLength":1,"type":"string","description":"Registered HTTPS redirect URI, or HTTP loopback. No fragment or user information. No query string.","format":"uri"}},"additionalProperties":false},"SpirisConnectionRequest":{"title":"Spiris","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["vismaeaccounting"],"type":"string"},"credentials":{"$ref":"#/components/schemas/SpirisConnectionCredentials"}},"additionalProperties":false,"description":"[Spiris onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/spiris)."},"SpirisConnectionCredentials":{"title":"Spiris credentials","required":["authorizationCode","redirectUri"],"type":"object","properties":{"authorizationCode":{"maxLength":2048,"minLength":1,"type":"string","description":"Unused authorization code.","writeOnly":true},"redirectUri":{"maxLength":2048,"minLength":1,"type":"string","description":"Registered HTTPS redirect URI, or HTTP loopback. No fragment or user information.","format":"uri"},"codeVerifier":{"maxLength":128,"type":"string","description":"Original PKCE verifier when used: 43–128 ASCII letters, digits or -._~. Omit, null or empty if unused.","nullable":true,"writeOnly":true}},"additionalProperties":false},"BjornLundenConnectionRequest":{"title":"Björn Lundén","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["bjornlunden"],"type":"string"},"credentials":{"$ref":"#/components/schemas/BjornLundenConnectionCredentials"}},"additionalProperties":false,"description":"[Björn Lundén onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/bjorn-lunden)."},"BjornLundenConnectionCredentials":{"title":"Björn Lundén credentials","required":["companyPublicKey"],"type":"object","properties":{"companyPublicKey":{"maxLength":256,"minLength":1,"type":"string","description":"Company public key obtained through the provider setup process. Treat it as a credential.","writeOnly":true}},"additionalProperties":false},"NetvisorConnectionRequest":{"title":"Netvisor","required":["source","credentials"],"type":"object","properties":{"source":{"enum":["vismanetvisor"],"type":"string"},"credentials":{"$ref":"#/components/schemas/NetvisorConnectionCredentials"}},"additionalProperties":false,"description":"[Netvisor onboarding guide](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/netvisor)."},"NetvisorConnectionCredentials":{"title":"Netvisor credentials","required":["userIdentifier","customerKey","businessId"],"type":"object","properties":{"userIdentifier":{"maxLength":256,"minLength":1,"type":"string","description":"Netvisor integration user identifier.","writeOnly":true},"customerKey":{"maxLength":256,"minLength":1,"type":"string","description":"Netvisor customer key; visible ASCII without whitespace.","writeOnly":true},"businessId":{"maxLength":9,"minLength":1,"type":"string","description":"Finnish business ID: seven digits, a hyphen and one digit.","writeOnly":true}},"additionalProperties":false},"ConnectionResponse":{"title":"Completed connection","required":["id","source","state"],"type":"object","properties":{"id":{"type":"string","description":"Connection ID.","format":"uuid"},"source":{"enum":["fortnox","xero","businesscentral","procountor","vismaeaccounting","bjornlunden","vismanetvisor"],"type":"string"},"state":{"enum":["completed"],"type":"string"}},"additionalProperties":false}}},"paths":{"/api/v1/consents/{consentId}/connection":{"post":{"tags":["Connections"],"summary":"Create connection","description":"**Preview (beta):** Headless Onboarding and its API may change or improve with short notice.\n\nCreate a connection for this Consent using the request body for your accounting system. Submit once; if the result is uncertain, read the connection before taking further action.\n\nSee the [onboarding overview](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding) for setup and security guidance, and [recovery steps](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding#if-the-result-is-uncertain) for an uncertain result. Each system schema links to its guide.","operationId":"CreateConnection","parameters":[{"name":"consentId","in":"path","required":true,"schema":{"type":"string","description":"Consent ID.","format":"uuid"}},{"name":"x-correlation-id","in":"header","required":true,"schema":{"type":"string","description":"New non-empty request correlation UUID.","format":"uuid"}}],"requestBody":{"description":"Choose the schema and example for your accounting system. Send only its fields, at most 16 KiB.","content":{"application/json":{"schema":{"title":"Choose an accounting system","oneOf":[{"$ref":"#/components/schemas/FortnoxConnectionRequest"},{"$ref":"#/components/schemas/XeroConnectionRequest"},{"$ref":"#/components/schemas/BusinessCentralConnectionRequest"},{"$ref":"#/components/schemas/ProcountorConnectionRequest"},{"$ref":"#/components/schemas/SpirisConnectionRequest"},{"$ref":"#/components/schemas/BjornLundenConnectionRequest"},{"$ref":"#/components/schemas/NetvisorConnectionRequest"}],"description":"Send exactly one of these request bodies. The source selects the matching credentials; do not combine fields from different systems.","discriminator":{"propertyName":"source","mapping":{"fortnox":"#/components/schemas/FortnoxConnectionRequest","xero":"#/components/schemas/XeroConnectionRequest","businesscentral":"#/components/schemas/BusinessCentralConnectionRequest","procountor":"#/components/schemas/ProcountorConnectionRequest","vismaeaccounting":"#/components/schemas/SpirisConnectionRequest","bjornlunden":"#/components/schemas/BjornLundenConnectionRequest","vismanetvisor":"#/components/schemas/NetvisorConnectionRequest"}}}}},"required":true},"responses":{"201":{"description":"Connection completed and Consent accepted.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionResponse"}}}},"400":{"description":"Invalid request, credentials, selected settings, or inaccessible company/tenant/environment. Query parameters are not accepted.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"401":{"description":"Authentication failed or correlation ID is missing or empty.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"403":{"description":"Access denied.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"404":{"description":"Consent unavailable or no connection found.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"409":{"description":"Consent inactive/already connected, or a concurrent creation conflict.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"413":{"description":"Request body exceeds 16 KiB.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"429":{"description":"Request rate limit reached. Do not automatically retry a credential submission.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"502":{"description":"Provider verification or communication failed.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"503":{"description":"Service temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}},"504":{"description":"Upstream timeout.","headers":{"Cache-Control":{"description":"Responses must not be cached.","schema":{"enum":["no-store"],"type":"string"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.zwapgrid.com/api-guide/consents-api-guide/connections.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.