Link
InExchange Docs
ON THIS PAGE

Register Customer for Kivra delivery

Requirements

Step 1: Request a token

To register for Kivra a token is needed. You create tokens with the Create Token call. We recommend that tokens are created with a short TTL of 10 minutes.

Request Example 

POST /v1/api/clientTokens/create HTTP/1.1
APIKey: --YOUR API KEY HERE--
Content-Type: application/json; charset=utf-8
Host: testapi.inexchange.se
Content-Length: 183
Expect: 100-continue

{
  "erpId": "635604692357550266",
  "validTo": "2026-05-26T12:54:10"
}

Response Example 

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 63
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
Date: Tue, 26 May 2026 12:54:10 GMT

{
  "token": "--CLIENT TOKEN HERE--"
}

Step 2: Register Kivra B2C delivery method 

POST v1/api/companies/deliverymethods/b2c/kivra HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"
Content-Type: application/json; charset=utf-8

{
  "LegalName": "Demo Company 083440-2861",
  "DisplayName": "Demo Company 083440-2861",
  "OrgNo": "083440-2861",
  "OrgVatNo": "SE083440286101",
  "ContactFirstname": "Firstname",
  "ContactLastName": "LastName",
  "ContactPersonEmail": "person@democompany.se",
  "GeneralEmail": "general@democompany.se",
  "ContactPhone": "+46000000000",
  "PubAgreement": true,
  "TermsAndConditions": true
}

Response Example 

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Length: 0
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: http://testapi.inexchange.se/v1/api/companies/deliverymethods/b2c/kivra

Error Response Example

This happens when the customer tenant is owned by other company then we get error 409.
Conflicts are manually handled by Kivra, this should be eventually resolved and registration should be retried later.

HTTP/1.1 409 CONFLICT
Server: nginx/1.13.7
Date: Thu, 03 Dec 2020 11:38:47 GMT
Content-Length: 0
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: http://testapi.inexchange.se/v1/api/companies/deliverymethods/b2c/kivra

Error Response Example

This happens when OrgVatNo is invalid:

HTTP/1.1 400 Bad Request
Server: nginx/1.13.7
Date: Thu, 03 Dec 2020 11:43:34 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 23
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Server-Id: Web02

"OrgVatNo is not valid"

(Optional) Check status for registration

Response fields:

  • Status - possible values:
    • Completed - when registration completed successfully
    • CompleteConflict - this happens when the customer tenant is owned by other integrator
    • Unknown - registration is not initiated
  • AgreementStatus possible values:
    • Signed - PubAgreement and TermsAndConditions is successfully signed
    • Expired - Agreement expired
    • Failed - internal error then signing aggreement with Kivra
GET v1/api/companies/deliverymethods/b2c/kivra HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"

Response Example 

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 351
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1

{
  "status": "Completed",
  "agreementStatus": "Signed",
  "agreementStart": "2026-05-26 12:54",
  "displayName": "Demo Company 083440-2861",
  "contactPersonEmail": "person@democompany.se",
  "contactFirstName": "Firstname",
  "contactLastName": "Lastname",
  "generalEmail": "general@democompany.se",
  "contactPhone": "+46000000000"
}

Update contact information

Use this then customer wants to update personal/company information

PATCH v1/api/companies/deliverymethods/b2c/kivra HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"
Content-Type: application/json; charset=utf-8

{
  "DisplayName": "Demo Company (Update) 083440-2861",
  "OrgNo": "083440-2861",
  "ContactFirstname": "Firstname",
  "ContactLastName": "LastName",
  "ContactPhone": "+46600000001",
  "ContactPersonEmail": "person@democompany.se",
  "GeneralEmail": "general@democompany.se"
}

Response Example 

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Length: 0
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: http://testapi.inexchange.se/v1/api/companies/deliverymethods/b2c/kivra

Provide Icon

The icon should be following format:

  • Dimensions: squared icon with size between 256x256 px and 512x512 px
  • Alpha Channel: 32-bits
  • Format: PNG
  • File size: up to 1MB

ContentType - the IANA media type corresponding to the file, e.g. “image/png” Filename - arbitrary file-name that is shown alongside the File in the Kivra client Data - Base64-encoded PNG image data PNG

We recommend to leave a little white area around the logo, to provide the best experience for the users.

Fields:

  • ContentType - the IANA media type corresponding to the file, e.g. “image/png”
  • Filename - arbitrary file-name that is shown alongside the File in the Kivra GUI
  • Data - Base64-encoded PNG image data PNG

NOTE: icon update takes time and sometimes can take days till client will see change

POST v1/api/companies/deliverymethods/b2c/kivra/icon HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"
Content-Type: application/json; charset=utf-8

{
  "ContentType": "image/png",
  "Filename": "radio-icon",
  "Data": "-- PNG image data converted to base64 string --"
}

Response Example 

HTTP/1.1 202 Accepted
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Length: 0
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: https://sandbox-static.kivra.com/img/tenant/"--tenant key--"/icon.png
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Server-Id: web01

Offboard

If the customer don’t want to use Kivra as B2C provider anymore they can offboard Kivra.
After offboarding customer won’t be able to send B2C invoices - all Kvivra B2C invoice will be stopped.

POST v1/api/companies/deliverymethods/b2c/kivra/offboard HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"
Content-Type: application/json; charset=utf-8

Response Example 

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Length: 0
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: http://testapi.inexchange.se/v1/api/companies/deliverymethods/b2c/kivra

Lookup registered ssns

Lookup if persons are registered in Kivra by sending a list of social security number (ssn) to check. Ssns registered in Kivra is returned.

400 (Bad Request) is retured for the following reasons:

  • The organsation is not registered in Kivra
  • The registration of company is not completed in Kivra
  • More than 500.000 ssns is passed in the body
POST v1/api/companies/deliverymethods/b2c/kivra/lookup HTTP/1.1
Host: testapi.inexchange.se
ClientToken: "--CLIENT TOKEN HERE--"
Content-Type: application/json; charset=utf-8

{
    "Ssns": ["ssn1","ssn2"]
}

Response Example 

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Tue, 26 May 2026 12:54:10 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 351
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1

{
    "registeredSsns": [
        "ssn2"
    ]
}

Error Response Example

This happens when the organisation is not registered in Kivra:

HTTP/1.1 400 Bad Request
Server: nginx/1.13.7
Date: Thu, 03 Dec 2020 11:43:34 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 23
Connection: close
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Server-Id: Web02

"Registration not found"