Insert a new organisation.
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. |
Email = 1 Post = 2
The organisation was created
Email = 1 Post = 2
The organisation data has validation issues