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

get

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).

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Path parameters

consentIdstring · uuidRequired

Identifier of the consent representing the connection to the accounting system.

Header parameters

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Responses

200

Returns a consent.

application/json

Consent resource returned by get and list endpoints. Represents the link between your customer and their connection to an accounting system.

idstring · uuidOptional

The ID of the Consent

namestring · nullableOptional

The name of the Consent

statusinteger · enumOptional

Consent status. Values: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).

Possible values:

sourcestring · nullableOptional

The source of the consent (i.e. what system has been connected)

systemSettingsIdstring · uuid · nullableOptional

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.

createdOnstring · date-timeOptional

The date the consent was created on

updatedOnstring · date-time · nullableOptional

The date the consent was updated on

401

Not authenticated to access this API endpoint.

application/json

403

Not authorised to access this API endpoint.

application/json

404

The consent does not exist.

application/json

get

/api/v1/consents/{consentId}

GET /api/v1/consents/{consentId} HTTP/1.1
x-api-key: YOUR_API_KEY
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Acme Corp - Fortnox",
  "status": 1,
  "source": "Fortnox",
  "systemSettingsId": "a1b2c3d4-e5f6-4a5b-8c9d-1e2f3a4b5c6d",
  "systemSettings": {
    "fileone": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fortnox": "a1b2c3d4-e5f6-4a5b-8c9d-1e2f3a4b5c6d"
  },
  "createdOn": "2024-01-15T10:30:00Z",
  "updatedOn": "2024-01-20T14:45:00Z"
}

Delete a consent

delete

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.

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Path parameters

consentIdstring · uuidRequired

Identifier of the consent representing the connection to the accounting system.

Header parameters

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Responses

204

If consent is removed

400

If request is invalid

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

delete

/api/v1/consents/{consentId}

DELETE /api/v1/consents/{consentId} HTTP/1.1
x-api-key: YOUR_API_KEY
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

No content

Update a consent

patch

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.

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Path parameters

consentIdstring · uuidRequired

Identifier of the consent representing the connection to the accounting system.

Header parameters

If-MatchstringRequired

Value of the ETag returned as a response header from the get-consent endpoint.

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Body

Request body for updating an existing consent. Only provided properties are updated.

statusinteger · enumOptional

Consent status. Values: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).

Possible values:

namestring · nullableOptional

New display name for the consent.

Responses

204

The consent was updated successfully.

400

The request is invalid.

application/json

401

Not authenticated to access this API endpoint.

application/json

403

Not authorised to access this API endpoint.

application/json

404

The consent does not exist.

application/json

412

If-Match header does not match Etag - this means that the resource has been changed and now has a different Etag.

application/json

patch

/api/v1/consents/{consentId}

PATCH /api/v1/consents/{consentId} HTTP/1.1
x-api-key: YOUR_API_KEY
If-Match: text
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "status": 2,
  "name": "Acme Corp - Fortnox (revoked)"
}

No content

List consents

get

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.

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Query parameters

Countinteger · int32 · min: 1 · max: 100Optional

Number of records to return per page.

CurrentPageinteger · int32 · min: 1 · max: 2147483647Optional

One-based index of the page to return.

CreatedOnstringOptional

Filter by creation date. Format: yyyy-MM-dd.

UpdatedOnstringOptional

Filter by last update date. Format: yyyy-MM-dd.

OrderBystringOptional

Sort order for the results.

StatusstringOptional

Filter by consent status. Use the status name or numeric value: CREATED (0), ACCEPTED (1), REVOKED (2), INACTIVE (3).

SourcestringOptional

Filter by source (accounting system identifier).

IsTestbooleanOptional

Filter by test flag. When true, only test consents are returned.

SystemSettingsIdstring · uuidOptional

Filter by the selected system settings ID (the system setting in effect once a consent is accepted).

NamestringOptional

Filter by consent name.

Header parameters

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Responses

200

Returns a list of consents.

application/json

Paginated list response. Contains a page of items and metadata for total count and pagination.

401

Not authenticated to access this API endpoint.

application/json

403

Not authorised to access this API endpoint.

application/json

404

The client does not exist.

application/json

get

/api/v1/consents

GET /api/v1/consents HTTP/1.1
x-api-key: YOUR_API_KEY
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "meta": {
    "totalResources": 42,
    "totalPages": 3,
    "currentPage": 1
  },
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Acme Corp - Fortnox",
      "status": 1,
      "source": "Fortnox",
      "systemSettingsId": "a1b2c3d4-e5f6-4a5b-8c9d-1e2f3a4b5c6d",
      "systemSettings": {
        "fileone": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fortnox": "a1b2c3d4-e5f6-4a5b-8c9d-1e2f3a4b5c6d"
      },
      "createdOn": "2024-01-15T10:30:00Z",
      "updatedOn": "2024-01-20T14:45:00Z"
    }
  ]
}

Create a consent

post

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.

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Header parameters

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Body

Request body for creating a new consent. Links a customer in your system to a connection that is completed in the Onboarding Flow.

namestring · min: 1Required

Display name for the consent (e.g. your customer or integration name).

Responses

201

Created.

application/json

400

The request is invalid.

application/json

401

Not authenticated to access this API endpoint.

application/json

403

Not authorised to access this API endpoint.

application/json

404

The consent does not exist.

application/json

post

/api/v1/consents

POST /api/v1/consents HTTP/1.1
x-api-key: YOUR_API_KEY
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 148

{
  "name": "Acme Corp - Fortnox",
  "systemsSettings": {
    "fileone": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fortnox": "a1b2c3d4-e5f6-4a5b-8c9d-1e2f3a4b5c6d"
  }
}

{}

Create a one-time code

post

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.

Authorizations

x-api-keystringRequired

You must generate an API Key by logging into the Client Portal.

You should use the API Key when calling all API endpoints in API.1.

Path parameters

consentIdstring · uuidRequired

Identifier of the consent representing the connection to the accounting system.

Header parameters

x-correlation-idstring · uuidRequired

Unique identifier used to correlate and trace this request.

Responses

201

One-time code was created successfully.

application/json

400

The request is invalid.

application/json

401

Not authenticated to access this API endpoint.

application/json

403

Not authorised to access this API endpoint.

application/json

404

The consent does not exist.

application/json

post

/api/v1/consents/{consentId}/otc

POST /api/v1/consents/{consentId}/otc HTTP/1.1
x-api-key: YOUR_API_KEY
x-correlation-id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "code": "OTC-7a3b2c1d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
}

NextModels

Last updated 10 days ago

Was this helpful?