# Consents
Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems.
## Get a consent
> Use this endpoint to fetch the full details of a consent (e.g. after creating one via the Location header, or to check status and system settings for a specific connection).
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"ConsentDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the Consent","format":"uuid"},"name":{"type":"string","description":"The name of the Consent","nullable":true},"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"The source of the consent (i.e. what system has been connected)","nullable":true},"systemSettingsId":{"type":"string","description":"The selected system settings ID once the consent is accepted. Populated when the consent has a single connected system; see systemSettings for the full dictionary of available system settings.","format":"uuid","nullable":true},"systemSettings":{"type":"object","additionalProperties":{"type":"string","description":"System settings ID (UUID) for this accounting system (value in the dictionary).","format":"uuid"},"description":"\nDictionary of available system settings for the consent.\r\n\nKey: lower-case system identifier (e.g. fortnox, fileone).\r\n\nValue: system settings ID (UUID).\r\n\nSee API description for supported system identifiers.","nullable":true},"createdOn":{"type":"string","description":"The date the consent was created on","format":"date-time"},"updatedOn":{"type":"string","description":"The date the consent was updated on","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Consent resource returned by get and list endpoints. Represents the link between your customer and their connection to an accounting system."},"ConsentStatus":{"enum":[0,1,2,3],"type":"integer","description":"Consent status. Values: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).","format":"int32"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents/{consentId}":{"get":{"tags":["Consents"],"summary":"Get a consent","description":"Use this endpoint to fetch the full details of a consent (e.g. after creating one via the Location header, or to check status and system settings for a specific connection).","operationId":"GetConsent","parameters":[{"name":"consentId","in":"path","description":"Identifier of the consent representing the connection to the accounting system.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Returns a consent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentDto"}}}},"401":{"description":"Not authenticated to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Not authorised to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"The consent does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## Delete a consent
> Use this endpoint to permanently remove a consent. After deletion, the consent ID can no longer be used and the customer would need a new consent to reconnect.
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents/{consentId}":{"delete":{"tags":["Consents"],"summary":"Delete a consent","description":"Use this endpoint to permanently remove a consent. After deletion, the consent ID can no longer be used and the customer would need a new consent to reconnect.","operationId":"DeleteConsent","parameters":[{"name":"consentId","in":"path","description":"Identifier of the consent representing the connection to the accounting system.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"If consent is removed"},"400":{"description":"If request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## Update a consent
> Use this endpoint to change the consent display name or to revoke the consent (set status to REVOKED so the customer's connection is no longer active). Send the If-Match header with the ETag from the last GET consent response to avoid overwriting concurrent changes.
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"UpdateConsentDto":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"name":{"type":"string","description":"New display name for the consent.","nullable":true}},"additionalProperties":false,"description":"Request body for updating an existing consent. Only provided properties are updated."},"ConsentStatus":{"enum":[0,1,2,3],"type":"integer","description":"Consent status. Values: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).","format":"int32"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents/{consentId}":{"patch":{"tags":["Consents"],"summary":"Update a consent","description":"Use this endpoint to change the consent display name or to revoke the consent (set status to REVOKED so the customer's connection is no longer active). Send the If-Match header with the ETag from the last GET consent response to avoid overwriting concurrent changes.","operationId":"PatchConsent","parameters":[{"name":"consentId","in":"path","description":"Identifier of the consent representing the connection to the accounting system.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Value of the ETag returned as a response header from the get-consent endpoint.","required":true,"schema":{"type":"string"}},{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Request body containing the optional status and name to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConsentDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateConsentDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateConsentDto"}}}},"responses":{"204":{"description":"The consent was updated successfully."},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Not authenticated to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Not authorised to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"The consent does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"412":{"description":"If-Match header does not match Etag - this means that the resource has been changed and now has a different Etag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## List consents
> Use this endpoint to retrieve all consents (connections to accounting systems) for your client. Filter by status, source, name, dates, or other query parameters to find specific consents.
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"ConsentDtoPagedResultDto":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/PagedResultMetadataDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentDto"},"description":"The list of items for the current page.","nullable":true}},"additionalProperties":false,"description":"Paginated list response. Contains a page of items and metadata for total count and pagination."},"PagedResultMetadataDto":{"type":"object","properties":{"totalResources":{"type":"integer","description":"Total number of resources across all pages.","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages given the page size.","format":"int32"},"currentPage":{"type":"integer","description":"One-based index of the current page.","format":"int32"}},"additionalProperties":false,"description":"Metadata for a paginated result: total count and current page information."},"ConsentDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the Consent","format":"uuid"},"name":{"type":"string","description":"The name of the Consent","nullable":true},"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"The source of the consent (i.e. what system has been connected)","nullable":true},"systemSettingsId":{"type":"string","description":"The selected system settings ID once the consent is accepted. Populated when the consent has a single connected system; see systemSettings for the full dictionary of available system settings.","format":"uuid","nullable":true},"systemSettings":{"type":"object","additionalProperties":{"type":"string","description":"System settings ID (UUID) for this accounting system (value in the dictionary).","format":"uuid"},"description":"\nDictionary of available system settings for the consent.\r\n\nKey: lower-case system identifier (e.g. fortnox, fileone).\r\n\nValue: system settings ID (UUID).\r\n\nSee API description for supported system identifiers.","nullable":true},"createdOn":{"type":"string","description":"The date the consent was created on","format":"date-time"},"updatedOn":{"type":"string","description":"The date the consent was updated on","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Consent resource returned by get and list endpoints. Represents the link between your customer and their connection to an accounting system."},"ConsentStatus":{"enum":[0,1,2,3],"type":"integer","description":"Consent status. Values: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).","format":"int32"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents":{"get":{"tags":["Consents"],"summary":"List consents","description":"Use this endpoint to retrieve all consents (connections to accounting systems) for your client. Filter by status, source, name, dates, or other query parameters to find specific consents.","operationId":"GetConsents","parameters":[{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Count","in":"query","description":"Number of records to return per page.","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int32"}},{"name":"CurrentPage","in":"query","description":"One-based index of the page to return.","schema":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"}},{"name":"CreatedOn","in":"query","description":"Filter by creation date. Format: yyyy-MM-dd.","schema":{"type":"string"}},{"name":"UpdatedOn","in":"query","description":"Filter by last update date. Format: yyyy-MM-dd.","schema":{"type":"string"}},{"name":"OrderBy","in":"query","description":"Sort order for the results.","schema":{"type":"string"}},{"name":"Status","in":"query","description":"Filter by consent status. Use the status name or numeric value: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).","schema":{"type":"string"}},{"name":"Source","in":"query","description":"Filter by source (accounting system identifier).","schema":{"type":"string"}},{"name":"IsTest","in":"query","description":"Filter by test flag. When true, only test consents are returned.","schema":{"type":"boolean"}},{"name":"SystemSettingsId","in":"query","description":"Filter by the selected system settings ID (the system setting in effect once a consent is accepted).","schema":{"type":"string","format":"uuid"}},{"name":"Name","in":"query","description":"Filter by consent name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of consents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentDtoPagedResultDto"}}}},"401":{"description":"Not authenticated to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Not authorised to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"The client does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## Create a consent
> Use this endpoint to create a consent that links your customer to a future connection in API.1. After creating, use the Location header to get the consent ID, then create a one-time code (POST /consents/{consentId}/otc) and use it only inside your embedded client integration when starting the Onboarding Flow. Do not expose the OTC in share links because it can be prematurely consumed. The 201 response includes a Location header with the URI of the created consent.
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"CreateConsentDto":{"required":["name"],"type":"object","properties":{"name":{"minLength":1,"type":"string","description":"Display name for the consent (e.g. your customer or integration name)."},"systemsSettings":{"type":"object","additionalProperties":{"type":"string","description":"System settings ID (UUID) for this accounting system (value in the dictionary).","format":"uuid"},"description":"\nOptional dictionary of available system settings for the consent.\r\n\nKey: lower-case system identifier (e.g. fortnox, fileone).\r\n\nValue: system settings ID (UUID).\r\n\nOmit to use client defaults where applicable.\r\n\nSee API description for supported system identifiers.","nullable":true}},"additionalProperties":false,"description":"Request body for creating a new consent. Links a customer in your system to a connection that is completed in the Onboarding Flow."},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents":{"post":{"tags":["Consents"],"summary":"Create a consent","description":"Use this endpoint to create a consent that links your customer to a future connection in API.1. After creating, use the Location header to get the consent ID, then create a one-time code (POST /consents/{consentId}/otc) and use it only inside your embedded client integration when starting the Onboarding Flow. Do not expose the OTC in share links because it can be prematurely consumed. The 201 response includes a Location header with the URI of the created consent.","operationId":"PostConsent","parameters":[{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Request body containing the consent name and optional system settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConsentDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateConsentDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateConsentDto"}}}},"responses":{"201":{"description":"Created.","headers":{"Location":{"description":"URI of the created consent. Use this URL to retrieve the created resource (e.g. GET /api/v1/consents/{consentId}).","schema":{"type":"string","format":"uri"}}},"content":{"application/json":{"schema":{"type":"object","description":"No body; use the Location header to fetch the created consent."}}},"links":{"getCreatedConsent":{"operationId":"GetConsent","description":"Get the created consent using the Location header from this response."}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Not authenticated to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Not authorised to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"The consent does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## Create a one-time code
> Use this endpoint after creating a consent to obtain a one-time code (OTC). Use the OTC only inside your embedded client integration when starting the Onboarding Flow. Do not expose the OTC in share links because it can be prematurely consumed.
```json
{"openapi":"3.0.1","info":{"title":"Consents API","version":"v1"},"tags":[{"name":"Consents","description":"Create, read, update, and delete consents; create one-time codes used in the Onboarding Flow. See the API description for consent statuses and supported accounting systems."}],"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":{"OtcDto":{"type":"object","properties":{"code":{"type":"string","description":"The one-time code used by the embedded client integration when starting the Onboarding Flow.","nullable":true}},"additionalProperties":false,"description":"One-time code returned when creating an OTC. Use it only inside your embedded client integration when starting the Onboarding Flow. Do not expose it in share links because it can be prematurely consumed."},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/consents/{consentId}/otc":{"post":{"tags":["Consents"],"summary":"Create a one-time code","description":"Use this endpoint after creating a consent to obtain a one-time code (OTC). Use the OTC only inside your embedded client integration when starting the Onboarding Flow. Do not expose the OTC in share links because it can be prematurely consumed.","operationId":"PostOtc","parameters":[{"name":"consentId","in":"path","description":"Identifier of the consent representing the connection to the accounting system.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-correlation-id","in":"header","description":"Unique identifier used to correlate and trace this request.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"One-time code was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtcDto"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Not authenticated to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Not authorised to access this API endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"The consent does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.zwapgrid.com/api-guide/consents-api-guide/consents.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.