Create Tenant

POST

/v2/tenant

curl --request POST \
  --url https://sender.api.kivra.com/v2/tenant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Kivra", "company_id": [ { "name": "Kivra AB", "orgnr": "SE556840226601" } ] }'

• Production environment
• Sandbox environment

Creation of tenants via API allows clients to create new tenants in an efficient manner. The created tenant is automatically added to the client scope. The client needs to re-authenticate to have the new scope in effect.

Note: Creation of tenants via API is only allowed in certain specific cases and its usage needs to be regulated in the business relationship between the sender party and Kivra.

Authorizations

• oAuth2Client
  post:kivra.v2.tenant

Request Body

Media typeapplication/json

Tenant_v2

object

name

required

Name of the Tenant, this name shows up in the Users Inbox

string

Example

Kivra

company_id

required

Array<object>

CompanyId

object

name

required

Legal name of Company

string

Example

Kivra AB

orgnr

required

Vat number of Company

string

Example

SE556840226601

edit_security_level

Security level needed for an enduser to opt_out from this Tenant

integer

Allowed values: 25 50

Example

50

groups

List of groups this Tenant belongs to

Array<string>

Example

[]

visibility

Determines if this Tenant is visible for the enduser

string

Allowed values: visible hidden

created_at

Datum when the tenant was created in UTC format

string

Example

2019-05-20T12:42:29Z

created_by

ID of client that created the tenant

string

Example

client_15063298495eafd2749bb78e2f991af3ab023d13df

status

Internal field describing whether the user can opt-out the tenant

string

Example

optional

class

Internal field

string

Example

opt_out

Responses

200

Tenant already existing and added to the client scope

Media typeapplication/json

Tenant_v2

object

name

required

Name of the Tenant, this name shows up in the Users Inbox

string

company_id

required

Array<object>

CompanyId

object

name

required

Legal name of Company

string

orgnr

required

Vat number of Company

string

edit_security_level

Security level needed for an enduser to opt_out from this Tenant

integer

Allowed values: 25 50

groups

List of groups this Tenant belongs to

Array<string>

visibility

Determines if this Tenant is visible for the enduser

string

Allowed values: visible hidden

created_at

Datum when the tenant was created in UTC format

string

created_by

ID of client that created the tenant

string

status

Internal field describing whether the user can opt-out the tenant

string

class

Internal field

string

Example

{
  "name": "Kivra",
  "company_id": [
    {
      "name": "Kivra AB",
      "orgnr": "SE556840226601"
    }
  ],
  "edit_security_level": 25,
  "groups": [],
  "visibility": "visible",
  "created_at": "2019-05-20T12:42:29Z",
  "created_by": "client_15063298495eafd2749bb78e2f991af3ab023d13df",
  "status": "optional",
  "class": "opt_out"
}

Headers

kivra-objkey

string format: hexadecimal value

Tenant Key

location

string format: url

URL to created Object

201

Tenant Created succesfully

Media typeapplication/json

Tenant_v2

object

name

required

Name of the Tenant, this name shows up in the Users Inbox

string

company_id

required

Array<object>

CompanyId

object

name

required

Legal name of Company

string

orgnr

required

Vat number of Company

string

edit_security_level

Security level needed for an enduser to opt_out from this Tenant

integer

Allowed values: 25 50

groups

List of groups this Tenant belongs to

Array<string>

visibility

Determines if this Tenant is visible for the enduser

string

Allowed values: visible hidden

created_at

Datum when the tenant was created in UTC format

string

created_by

ID of client that created the tenant

string

status

Internal field describing whether the user can opt-out the tenant

string

class

Internal field

string

Example

{
  "name": "Kivra",
  "company_id": [
    {
      "name": "Kivra AB",
      "orgnr": "SE556840226601"
    }
  ],
  "edit_security_level": 25,
  "groups": [],
  "visibility": "visible",
  "created_at": "2019-05-20T12:42:29Z",
  "created_by": "client_15063298495eafd2749bb78e2f991af3ab023d13df",
  "status": "optional",
  "class": "opt_out"
}

Headers

kivra-objkey

string format: hexadecimal value

Tenant Key

location

string format: url

URL to created Object

409

The tenant could not be created because of a conflict, meaning that a tenant with the same orgnr already exists and cannot be automatically added to the client scope. The client may use the request_access endpoint to request access to this tenant.

Media typeapplication/json

Error40915

object

code

The 5-digits error code

string

short_message

A short message explaining the conflict

string

long_message

A text message explaining the conflict

string

Example

{
  "code": 40915,
  "short_message": "Orgnumber already exist",
  "long_message": "One or more of the organisation numbers within the company_id's you provided, already exist in existing tenants. Tenants outside your scope: {Name: TestBolag, Tenant key: 1424780396902ee9278b16417f8e3252c3ced28c38, Organisation number: SE556840226601}"
}