> ## Documentation Index > Fetch the complete documentation index at: https://www.bloxs.io/llms.txt > Use this file to discover all available pages before exploring further. # Insert an organisation > Insert a new organisation. ## OpenAPI ````json POST /api/v1/relations/organisations { "openapi": "3.0.4", "info": { "title": "Relations V1", "description": "# Relation API Documentation\n\nWelcome to the Relationship Management API documentation. This API allows you to perform CRUD operations on various relationship types, including Owners, Persons, Suppliers, Estate Agents, and Organisations. \n\n## Authentication \n\nTo access the API, include your API key in the headers. Refer to our authentication documentation for details on obtaining and using your API key. \n\n## CRUD Operations \n\nThe API supports CRUD operations for the following relationship types: \n\n- **Owners**\n- **Persons**\n- **Suppliers**\n- **Estate Agents**\n- **Organisations**\n\nFor each relationship type, you can: \n\n- **GET**: Retrieve a list or apply filters.\n- **POST**: Add a new entry.\n- **PUT**: Update existing details.\n- **PATCH**: Apply partial updates.\n- **DELETE**: Remove an entry.\n\nThank you for choosing our Relation API. If you have any questions or need assistance, please contact our support team. \n", "version": "v1" }, "security": [ {} ], "tags": [ { "name": "Common" }, { "name": "CommunicationFormAPI" }, { "name": "EstateAgentAPI" }, { "name": "Metadata" }, { "name": "OrganisationAPI" }, { "name": "OwnerAPI" }, { "name": "PersonAPI" }, { "name": "RelationTypeAPI" }, { "name": "SupplierAPI" }, { "name": "SupplierTypeAPI" } ], "paths": { "/api/v1/relations/organisations": { "post": { "tags": [ "Relations" ], "summary": "Insert an organisation", "description": "Insert a new organisation.", "operationId": "InsertOrganisation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organisation" } } } }, "responses": { "200": { "description": "The organisation was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationDetails" } } } }, "400": { "description": "The organisation data has validation issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorMessageModel" } } } } }, "x-d360-narrative-url": "

Insert an Organisation

Creates a new organisation relation in Bloxs.

A developer calls this endpoint to register a new company or legal entity, for example a tenant or other business relation not yet in the system, rather than update an existing one. On success, Bloxs generates and returns the internal reference and display name for the new record, along with the full stored data.

The correspondence method determines whether an email address or a postal address must be supplied.

Request Fields

Field

Type

Required

Description

name

string, max 256

Required

The organisation's registered or trading name.

relationTypeName

string, max 256

Required

The name of the relation type to assign to this organisation. Valid values can be retrieved from the Get all relation types endpoint.

website

string, nullable

Optional

The organisation's website URL.

correspondenceMethod

integer (enum)

Required

How correspondence should be delivered to this organisation. Allowed values: 1 = Email, 2 = Post. When set to Email, primaryEmailAddresses is mandatory. When set to Post, address is mandatory.

languageISOCode

string, max 2, nullable

Optional

ISO 639-1 two-letter language code (for example \"nl\" or \"en\") determining the language used in correspondence.

externalIdentifier

string, max 100, nullable

Optional

An external API identifier to associate with this organisation, if the integrating system wants to track its own identifier for the record.

address.street

string, max 200

Conditionally required

Street name of the organisation's main address. Required when correspondenceMethod is set to Post (2).

address.houseNumber

string, max 40, nullable

Optional

House number of the organisation's main address, including any suffix (for example \"12A\").

address.postalCode

string, max 20

Conditionally required

Postal code of the organisation's main address. Required when correspondenceMethod is set to Post (2).

address.city

string, max 200

Conditionally required

City of the organisation's main address. Required when correspondenceMethod is set to Post (2).

address.countryISOCode

string, max 2

Conditionally required

ISO 3166-1 alpha-2 country code of the organisation's main address, for example \"NL\". Required when correspondenceMethod is set to Post (2).

invoiceAddress.street

string, max 200

Required (if invoiceAddress is set)

Street name of the address to use for invoicing this organisation, if different from the main address.

invoiceAddress.houseNumber

string, max 40, nullable

Optional

House number of the invoice address, including any suffix.

invoiceAddress.postalCode

string, max 20

Required (if invoiceAddress is set)

Postal code of the invoice address.

invoiceAddress.city

string, max 200

Required (if invoiceAddress is set)

City of the invoice address.

invoiceAddress.countryISOCode

string, max 2

Required (if invoiceAddress is set)

ISO 3166-1 alpha-2 country code of the invoice address.

postalAddress.street

string, max 200

Required (if postalAddress is set)

Street name of the postal correspondence address, if different from the main address.

postalAddress.houseNumber

string, max 40, nullable

Optional

House number of the postal address, including any suffix.

postalAddress.postalCode

string, max 20

Required (if postalAddress is set)

Postal code of the postal address.

postalAddress.city

string, max 200

Required (if postalAddress is set)

City of the postal address.

postalAddress.countryISOCode

string, max 2

Required (if postalAddress is set)

ISO 3166-1 alpha-2 country code of the postal address.

invoiceAttn

string, nullable

Optional

The name of the person or department invoices should be addressed to. Invoice templates must be configured to use this field for it to take effect.

reminderAttn

string, nullable

Optional

The name of the person or department payment reminders should be addressed to. Reminder templates must be configured to use this field for it to take effect.

indexingAttn

string, nullable

Optional

The name of the person or department indexation letters should be addressed to. Indexation letter templates must be configured to use this field for it to take effect.

phoneNumber

string, nullable

Optional

The organisation's landline phone number.

mobileNumber

string, nullable

Optional

The organisation's mobile phone number.

primaryEmailAddresses

array of string, nullable

Conditionally required

The organisation's primary email address(es), used for general correspondence. Required when correspondenceMethod is set to Email (1).

invoicesEmailAddresses

array of string, nullable

Optional

Email address(es) that should receive invoices for this organisation.

paymentRemindersEmailAddresses

array of string, nullable

Optional

Email address(es) that should receive payment reminder correspondence.

indexationsEmailAddresses

array of string, nullable

Optional

Email address(es) that should receive rent or fee indexation notices.

serviceTicketsEmailAddresses

array of string, nullable

Optional

Email address(es) that should receive service or maintenance ticket correspondence.

purchaseOrdersEmailAddresses

array of string, nullable

Optional

Email address(es) that should receive purchase order correspondence.

portalsEmailAddresses

array of string, nullable

Optional

Email address(es) used for portal-related notifications.

otherEmailAddresses

array of string, nullable

Optional

Any additional email address(es) not covered by the categories above.

cocNumber

string, max 256, nullable

Optional

Chamber of Commerce (KVK-style) registration number for the organisation.

cocDescription

string, nullable

Optional

Free-text description associated with the Chamber of Commerce registration.

vatNumber

string, max 256, nullable

Optional

The organisation's VAT identification number, used for invoicing and determining VAT/reverse-charge treatment where applicable.

remarks

string, nullable

Optional

Free-text internal remarks about the organisation.

Response Fields

Field

Type

Required

Description

reference

string, max 100

Optional

The internal identifier (Reference/Code) generated by Bloxs for the newly created organisation.

externalIdentifier

string, max 100

Optional

The external API identifier for this organisation, if one was supplied on creation.

displayName

string

Optional

The formatted display name generated by Bloxs for the organisation.

name

string, max 256

Required

The organisation's registered or trading name.

relationTypeName

string, max 256

Required

The relation type assigned to this organisation.

website

string, nullable

Optional

The organisation's website URL.

correspondenceMethod

integer (enum)

Required

How correspondence is delivered to this organisation. Allowed values: 1 = Email, 2 = Post.

languageISOCode

string, max 2, nullable

Optional

ISO 639-1 two-letter language code determining the correspondence language.

address.street

string, max 200

Conditionally required

Street name of the organisation's main address.

address.houseNumber

string, max 40, nullable

Optional

House number of the organisation's main address, including any suffix.

address.postalCode

string, max 20

Conditionally required

Postal code of the organisation's main address.

address.city

string, max 200

Conditionally required

City of the organisation's main address.

address.countryISOCode

string, max 2

Conditionally required

ISO 3166-1 alpha-2 country code of the organisation's main address.

invoiceAddress.street

string, max 200

Required (if invoiceAddress is set)

Street name of the invoice address.

invoiceAddress.houseNumber

string, max 40, nullable

Optional

House number of the invoice address.

invoiceAddress.postalCode

string, max 20

Required (if invoiceAddress is set)

Postal code of the invoice address.

invoiceAddress.city

string, max 200

Required (if invoiceAddress is set)

City of the invoice address.

invoiceAddress.countryISOCode

string, max 2

Required (if invoiceAddress is set)

ISO 3166-1 alpha-2 country code of the invoice address.

postalAddress.street

string, max 200

Required (if postalAddress is set)

Street name of the postal address.

postalAddress.houseNumber

string, max 40, nullable

Optional

House number of the postal address.

postalAddress.postalCode

string, max 20

Required (if postalAddress is set)

Postal code of the postal address.

postalAddress.city

string, max 200

Required (if postalAddress is set)

City of the postal address.

postalAddress.countryISOCode

string, max 2

Required (if postalAddress is set)

ISO 3166-1 alpha-2 country code of the postal address.

invoiceAttn

string, nullable

Optional

The name of the person or department invoices should be addressed to.

reminderAttn

string, nullable

Optional

The name of the person or department payment reminders should be addressed to.

indexingAttn

string, nullable

Optional

The name of the person or department indexation letters should be addressed to.

phoneNumber

string, nullable

Optional

The organisation's landline phone number.

mobileNumber

string, nullable

Optional

The organisation's mobile phone number.

primaryEmailAddresses

array of string, nullable

Conditionally required

The organisation's primary email address(es).

invoicesEmailAddresses

array of string, nullable

Optional

Email address(es) that receive invoices for this organisation.

paymentRemindersEmailAddresses

array of string, nullable

Optional

Email address(es) that receive payment reminder correspondence.

indexationsEmailAddresses

array of string, nullable

Optional

Email address(es) that receive rent or fee indexation notices.

serviceTicketsEmailAddresses

array of string, nullable

Optional

Email address(es) that receive service or maintenance ticket correspondence.

purchaseOrdersEmailAddresses

array of string, nullable

Optional

Email address(es) that receive purchase order correspondence.

portalsEmailAddresses

array of string, nullable

Optional

Email address(es) used for portal-related notifications.

otherEmailAddresses

array of string, nullable

Optional

Any additional email address(es) not covered by the categories above.

cocNumber

string, max 256, nullable

Optional

Chamber of Commerce (KVK-style) registration number, where applicable.

cocDescription

string, nullable

Optional

Free-text description associated with the Chamber of Commerce registration.

vatNumber

string, max 256, nullable

Optional

The organisation's VAT identification number.

remarks

string, nullable

Optional

Free-text internal remarks about the organisation.

archiveDate

string (date), nullable

Optional

The date from which the organisation is archived. Always null immediately after creation.

" } } }, "components": { "schemas": { "Organisation": { "required": [ "correspondenceMethod", "name", "relationTypeName" ], "type": "object", "properties": { "languageISOCode": { "maxLength": 2, "minLength": 0, "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/Address" }, "invoiceAddress": { "$ref": "#/components/schemas/Address" }, "postalAddress": { "$ref": "#/components/schemas/Address" }, "primaryEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "invoicesEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "paymentRemindersEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "indexationsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "serviceTicketsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "purchaseOrdersEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "portalsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "otherEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "externalIdentifier": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "mobileNumber": { "type": "string", "nullable": true }, "cocNumber": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true }, "cocDescription": { "type": "string", "nullable": true }, "vatNumber": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true }, "correspondenceMethod": { "type": "integer", "description": "Email = 1\nPost = 2", "format": "int32", "x-enumNames": [ "Email", "Post" ] }, "remarks": { "type": "string", "nullable": true }, "relationTypeName": { "maxLength": 256, "minLength": 0, "type": "string" }, "name": { "maxLength": 256, "minLength": 0, "type": "string" }, "website": { "type": "string", "nullable": true }, "invoiceAttn": { "type": "string", "nullable": true }, "reminderAttn": { "type": "string", "nullable": true }, "indexingAttn": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OrganisationDetails": { "required": [ "correspondenceMethod", "name", "relationTypeName" ], "type": "object", "properties": { "languageISOCode": { "maxLength": 2, "minLength": 0, "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/Address" }, "invoiceAddress": { "$ref": "#/components/schemas/Address" }, "postalAddress": { "$ref": "#/components/schemas/Address" }, "primaryEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "invoicesEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "paymentRemindersEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "indexationsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "serviceTicketsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "purchaseOrdersEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "portalsEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "otherEmailAddresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "externalIdentifier": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "mobileNumber": { "type": "string", "nullable": true }, "cocNumber": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true }, "cocDescription": { "type": "string", "nullable": true }, "vatNumber": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true }, "correspondenceMethod": { "type": "integer", "description": "Email = 1\nPost = 2", "format": "int32", "x-enumNames": [ "Email", "Post" ] }, "remarks": { "type": "string", "nullable": true }, "relationTypeName": { "maxLength": 256, "minLength": 0, "type": "string" }, "name": { "maxLength": 256, "minLength": 0, "type": "string" }, "website": { "type": "string", "nullable": true }, "invoiceAttn": { "type": "string", "nullable": true }, "reminderAttn": { "type": "string", "nullable": true }, "indexingAttn": { "type": "string", "nullable": true }, "reference": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "archiveDate": { "type": "string", "format": "date", "nullable": true } }, "additionalProperties": false }, "APIErrorMessageModel": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "traceId": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true } }, "additionalProperties": false }, "Address": { "required": [ "city", "countryISOCode", "postalCode", "street" ], "type": "object", "properties": { "street": { "maxLength": 200, "minLength": 0, "type": "string" }, "houseNumber": { "maxLength": 40, "minLength": 0, "type": "string", "nullable": true }, "postalCode": { "maxLength": 20, "minLength": 0, "type": "string" }, "city": { "maxLength": 200, "minLength": 0, "type": "string" }, "countryISOCode": { "maxLength": 2, "minLength": 0, "type": "string" } }, "additionalProperties": false } } } } ````